Objective

The objective of this article is to demonstrate how to use the mimik Client Library interfaces when working with the mimOE Runtime in an iOS project.

Intended Readers

The intended readers of this document are iOS software developers, who want to familiarize themselves with the basics of the mimik Client Library interface, specifically methods for interfacing with the mimOE Runtime.

What You'll Be Doing

In this tutorial you'll be covering the following topics of working with the mimOE Runtime:

• Starting
• Stopping
• Creating an Access Token
• Retrieving Runtime Information
• Resetting
• Lifecycle Management
• Working with an iOS Simulator

Prerequisites

• Connecting a real iOS device to the development computer and selecting it as the target in Xcode. This tutorial will not work with an iOS Simulator.

• A familiarity of working with mimik Client Library components as described in this Key Concepts article.

• An understanding of the mimik Client Library components integration and initialization process as layed out in this article.

Starting mimOE Runtime

Once the mimik Client Library components have been integrated, initialized and imported into your project, you can get into the specifics of working with the mimOE Runtime.

You can think of mimOE as a host platform where edge microservices are deployed to. Also, mimOE provides http interfaces to the iOS application in order to do various tasks.

One prerequisite for being able to deploy the edge microservices is that the mimOE is in a running state. The code example below in Listing 1 shows you how to do this. An explanation of the code follows.

1: func start() async -> Result<Void, NSError> {
2:     // Developer mimOE license from mimik developer console at https://console.mimik.com
3:     let license = <DEVELOPER_MIMOE_LICENSE>
4: 
5:     // License parameter is the only parameter required for mimOE Runtime startup. There are other optional parameters also available.
6:     let startupParameters = EdgeClient.StartupParameters(license: license)
7: 
8:     // Using the mimik Client Library to start the mimOE Runtime
9:     switch await self.edgeClient.startEdgeEngine(parameters: startupParameters) {
10:     case .success:
11:         print("Success starting mimOE")
12:         // Returning a success for mimOE startup
13:         return .success(())
14:     case .failure(let error):
15:         print("Error starting mimOE", error.localizedDescription)
16:         // Returning a failure for mimOE startup
17:         return .failure(error)
18:     }
19: }

Listing 1: Starting mimOE

First, we get our developer mimOE license from mimik Developer Console and set the value. (The article Working with mimOE in an iOS project provides the details about obtaining an mimOE license.)

Next, we set the mimOE Runtime configuration object using the mimOE license. There are additional startup parameters available, but for the purpose of this article, only the license parameter will be used.

Then, we call the start method on the mimik Client Library, where we will pass our license parameter.

WHERE

parametersis the configuration object where we set our mimOE license

After the call, we validate the mimOE startup result. Returning either a success or a failure.

Stopping mimOE Runtime

Sometimes developers want to shut down the mimOE Runtime manually. For example, when opting-out from the automatic lifecycle management, or when the user wants to clear out all of their data after a logout. The code example below shows you how to do this.

We call the stop method on the mimik Client Library and that's it. There are no values returned, nor there is a need to do any validation. Once the client library method returns, mimOE Runtime will be stopped, with its storage erased.

1: func stopMimOE() {
2:     // Calling mimik Client Library method to stop mimOE synchronously.
3:     self.edgeClient.stopEdgeEngine()
4: }

Creating an Access Token

Most of the mimOE Runtime interface calls require an Access Token for their operations. The Access Token is based on the Developer ID Token generated at the mimik Developer Console. The code example below in Listing 2 shows you how to do this.

1: func authenticate() async -> Result<String, NSError> {
2:     // Using developer ID Token from mimik Developer Console
3:     let developerIdToken = <DEVELOPER_ID_TOKEN>
4:     
5:     // Calling mimik Client Library to generate the mimOE Access Token. Passing-in the Developer ID Token as the only parameter.
6:     switch await self.edgeClient.authorizeDeveloper(developerIdToken: developerIdToken) {
7:     case .success(let authorization):
8:         
9:         guard let accessToken = authorization.token?.accessToken else {
10:             // Authentication unsuccessful, returning a failure
11:             return .failure(NSError.init(domain: "Error", code: 500))
12:         }
13:         
14:         print("Success. Access Token:", accessToken)
15:         // We have the Access Token, return a success with the Access Token
16:         return .success(accessToken)
17:     case .failure(let error):
18:         print("Error", error.localizedDescription)
19:         /// We don't have the Access Token, returning a failure.
20:         return .failure(error)
21:     }
22: }

Listing 2: Authenticating for mimOE access

First, we get our Developer ID Token from mimik Developer Console and set the value. (For more information about the Developer ID Token read the section, Getting the developer ID Token and client ID from mimik Developer Portal in this tutorial.)

Next, we call the authorization method of the mimik Client Library, which requires the developerIdToken parameter.

WHERE developerIdToken is the developer ID Token we set above.

After the call is made, we attempt to get the Access Token value from the authorization's token and return a success or a failure, depending on the result.

Retrieving Runtime Information

Sometimes developers need to find out more details about the mimOE Runtime system information, such as its version, account or node information. The code example in Listing 3 below shows you how to do this. An explanation follows.

1: func info() async -> Result<Any, NSError> {
2:     // Calling mimik Client Library method to get the mimOE Runtime information
3:     switch await self.edgeClient.edgeEngineInfo() {
4:     case .success(let info):
5:         print("Success", info)
6:         // Call successful, returning a success with the mimOE Runtime information JSON
7:         return .success(info)
8:     case .failure(let error):
9:         // Call unsuccessful, returning a failure
10:         print("Error", error.localizedDescription)
11:         return .failure(error)
12:     }
13: }

Listing 3: Getting information about mimOE Runtime

First, we call the info method of the mimik Client Library.

Then we validate and print the result if successful or return a failure.

The JSON information returned in the info object is similar to the following:

 {
   "supernodeTypeName" : "_mk-v15-4247._tcp",
   "nodeId" : "1234567890",
   "accountId" : "1234567890",
   "version" : "vX.Y.Z",
   "linkLocalIp" : "192.168.1.47"
 }

Resetting mimOE Runtime

When it comes to clearing out user data, developers might want to shut down the mimOE Runtime and erase all content stored in its working directory. The code example in Listing 4 below shows you how to do this with one call. An explanation follows.

1: func reset() async -> Result<Void, NSError> {
2:     // Calling mimik Client Library method to shut down and erase mimOE storage
3:     switch self.edgeClient.resetEdgeEngine() {
4:     case .success:
5:         print("Success")
6:         // Reset successful, returning a success
7:         return .success(())
8:     case .failure(let error):
9:         print("Error", error.localizedDescription)
10:         // Reset unsuccessful, returning a failure
11:         return .failure(error)
12:     }
13: }

Listing 4: Resetting mimOE

First, we call the erase method on the mimik Client Library.

Then we validate, returning a success or a failure, depending on the result.

Lifecycle Management

When developers initialize the mimik Client Library, they opt-in to an automatic mimOE Runtime Lifecycle management by default. This means that the mimik Client Library will be monitoring the application's lifecycle notifications, and reacting to any significant changes that affect mimOE's ability to perform its functions.

When the background system notification is received, mimOE stop is called automatically.

When the foreground system notification is received, mimOE start is called automatically as well.

Developers can opt-out of this automatic lifecycle management during the mimik Client Library initialization by setting the method manage parameter to false; for example, when they prefer to start and stop the mimOE Runtime manually.

The code example below shows you how to activate the automatic mimOE Runtime Lifecycle management:

 switch EdgeClient.manageEdgeEngineLifecycle(manage: true) {
 case .success():
     print("Success")
     // Lifecycle management activation successful
 case .failure(let error):
     print("Error", error.localizedDescription)
     // Lifecycle management activation unsuccessful
 }

This code example shows you how to deactivate the automatic edgeEngine Runtime Lifecycle management:

 switch EdgeClient.manageEdgeEngineLifecycle(manage: false) {
 case .success():
     print("Success")
     // Lifecycle management deactivation successful
 case .failure(let error):
     print("Error", error.localizedDescription)
     // Lifecycle management deactivation unsuccessful
 }

Finally, the following code example code shows you how to determine whether the current lifecycle management activation state:

 func lLifecycleIsManaged() -> Bool {
     // Calling mimik Client Library class method to determine the lifecycle management state
     switch self.edgeClient.edgeEngineLifecycleIsManaged() {
     case true:
         print("Lifecycle is Managed")
         // mimOE Runtime lifecycle is being managed by the mimik Client Library
         return true
     case false:
         print("Lifecycle is not managed")
         // mimOE Runtime lifecycle is NOT being managed by the mimik Client Library
         return false
     }
 }

Working with an iOS Simulator

Normally, developers intend to run their applications on iOS devices where the mimik Client Library is used to facilitate the integration of the mimOE Runtime binary directly within the iOS application sandbox. This is done by vendoring the mimOE binary inside the mimOE-SE-iOS-developer (or mimOE-SE-iOS) cocoapod.

The inclusion of mimOE-SE-iOS-developer cocoapod in the iOS project affects the ability to compile the project for the iOS Simulator or Mac Catalyst environments. This is because the mimOE binary is compiled specifically for iOS devices (and not the simulated environments that run on a different processor architecture).

In order to provide a functional workaround, the mimik Client Library is split into EdgeCore and mimOE-SE-iOS-developer cocoapods. This gives developers the choice of having the mimOE binary bundled within the iOS application or having it run externally on a host platform of their choice (e.g., macOS, Linux, Windows, etc...)

So to summarize. When compiling the project for an iOS device, include the mimOE-SE-iOS-developer cocoapod in your project. This would run the mimOE Runtime binary internally, on the iOS device.

When compiling for an iOS Simulator or Mac Catalyst environments, only include the EdgeCore cocoapod in your project. Then, host the mimOE Runtime on an external platform of your choice and activate the external mimOE support in the mimik Client Library.

The code example below shows you how to conditionally include (or not) the mimOE-SE-iOS-developer cocoapod, using two different targets.

 target 'internal-mimOE-target' do
   pod 'EdgeCore'
   pod 'mimOE-SE-iOS-developer'
 end
 
 target 'external-mimOE-target' do
   pod 'EdgeCore'
 end

The code example below shows you how to conditionally import EdgeEngine (mimOE) into your class using the EXTERNAL compiler flag.

 import EdgeCore
 #if !EXTERNAL
 import EdgeEngine
 #endif

Next, let's assume we want to have mimOE running externally, for example on a macOS host, with a 192.168.4.47 IP address and 8083 port number.

Once mimOE is running externally on a macOS host, we can activate the external mimOE support in the mimik Client Library, by calling the external support activation method.

The code example below shows you how to do this.

 func activateExternalSupport() -> Result<URLComponents, NSError> {
     // Calling mimik Client Library class method to activate the external mimOE support
     switch EdgeClient.activateExternalEdgeEngine(host: "192.168.4.47", port: 8083) {
     case .success(let urlComponents):
         print("Success", urlComponents)
         // External mimOE activation successful, returning a success
         return .success(urlComponents)
     case .failure(let error):
         print("Error", error.localizedDescription)
         // External mimOE activation unsuccessful, returning a failure
         return .failure(error)
     }
 }

You can then continue using the application and mimik Client Library normally, keeping in mind that with the mimOE Runtime running externally, the iOS application environment wouldn't have the ability to control its lifecycle directly.