Objective

The objective of this article is to demonstrate how to use the mimik Client Library interfaces when working with the edgeEngine 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 mimik Client Library interfaces, specifically methods for interfacing with the edgeEngine Runtime.

What You'll Be Doing

In this tutorial you'll be covering the following topics that are relevant to using the mimik Client Library edgeEngine interfaces:

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

Technical Prerequisites

This article has the following technical prerequisites:

• A device running the latest iOS version.
• 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 initializiation process as layed out in this article.

Starting edgeEngine

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

You can think of edgeEngine as a host platform where edge microservices are deployed to. Also, edgeEngine 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 edgeEngine needs to be 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 startEdgeEngine() async -> Result<Void, NSError> {
2:     // Developer edge license from mimik developer console at https://console.mimik.com
3:     let edgeLicense = <DEVELOPER_EDGE_LICENSE>
4: 
5:     // Configuring StartupParameters object with the developer edge license.
6:     let startupParameters = EdgeClient.StartupParameters(license: edgeLicense)
7: 
8:     // Calling mimik Client Library method to starting edgeEngine asynchronously, waiting for the result.
9:     switch await self.edgeClient.startEdgeEngine(parameters: startupParameters) {
10:     case .success:
11:         print("Success starting edgeEngine")
12:         // Startup successful, returning success.
13:         return .success(())
14:     case .failure(let error):
15:         print("Error starting edgeEngine", error.localizedDescription)
16:         // Startup unsuccessful, returning failure.
17:         return .failure(error)
18:     }
19: }

Listing 1: Starting edgeEngine

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

Next, we set the edgeEngine Runtime configuration object at Line 6 by calling EdgeClient.StartupParameters(license: edgeLicense). There are additional startup parameters available, but for the purpose of this article, only the license parameter will be used.

Then, we call the startEdgeEngine() method of the mimik Client Library at Line 9, which requires a value for the parameter named parameters.

WHERE

parametersis the configuration object we set at Line 6

After the call, we validate the result.

If the edgeEngine startup is successful, we return a success at Line 13.

If there is an issue, we return a failure at Line 17.

Stopping edgeEngine

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

We call the stopEdgeEngine() method of 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, edgeEngine is no longer in a running state.

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

Creating an Access Token

Most of the edgeEngine Runtime functions 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 authenticateEdgeEngine() 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 method to get the Access Token for edgeEngine access
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 failure
11:             return .failure(NSError.init(domain: "Error", code: 500))
12:         }
13:         
14:         print("Success. Access Token:", accessToken)
15:         // Authentication successful, returning success with the Access Token
16:         return .success(accessToken)
17:     case .failure(let error):
18:         print("Error", error.localizedDescription)
19:         // Authentication unsuccessful, returning failure
20:         return .failure(error)
21:     }
22: }

Listing 2: Authenticating to edgeEngine

First, we get our developer ID Token from mimik Developer Portal and set the value at Line 3. (For more information about the Developer ID Token read the section, Getting the developer ID Token and client ID from mimik Developer Portal in the tutorial Getting the edgeEngine license and Identity server values from mimik Developer Portal.)

Next, we call the authorizeDeveloper() method of the mimik Client Library at Line 6, which requires the developerIdToken parameter

WHERE developerIdToken is the developer ID Token we set at Line 3 in Listing 2 above.

After the call is made, we validate the result by getting the Access Token value from the authorization's token at Line 9. If successful, we print and return the Access Token at Lines 14 and 16.

If there is an issue, we return a failure at Lines 11 or 20.

Retrieving Runtime Information

Sometimes developers need to find out more details about the edgeEngine 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 edgeEngineInfo() async -> Result<Any, NSError> {
2:     // Calling mimik Client Library method to get the edgeEngine Runtime information
3:     switch await self.edgeClient.edgeEngineInfo() {
4:     case .success(let info):
5:         print("Success", info)
6:         // Call successful, returning success with the edgeEngine Runtime information JSON
7:         return .success(info)
8:     case .failure(let error):
9:         // Call unsuccessful, returning failure
10:         print("Error", error.localizedDescription)
11:         return .failure(error)
12:     }
13: }

Listing 3: Getting information about edgeEngine Runtime

First, we call the edgeEngineInfo() method of the mimik Client Library Engine component on Line 3.

After the call, we validate the result at Lines 4-12.

If edgeEngine information JSON is received, we return a success with the JSON at Line 7.

If there is an issue, we return a failure at Line 11.

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 edgeEngine

When it comes to clearing out user data, developers need to shut down the edgeEngine Runtime and then 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 resetEdgeEngine() async -> Result<Void, NSError> {
2:     // Calling mimik Client Library method to shut down and erase edgeEngine storage
3:     switch self.edgeClient.resetEdgeEngine() {
4:     case .success:
5:         print("Success")
6:         // Call successful, returning success
7:         return .success(())
8:     case .failure(let error):
9:         print("Error", error.localizedDescription)
10:         // Call unsuccessful, returning failure
11:         return .failure(error)
12:     }
13: }

Listing 4: Resetting edgeEngine

First, we call the resetEdgeEngine() method of the mimik Client Library on Line 3.

After the call, we validate the result at Lines 4-12.

If edgeEngine reset is successful, we return success at Line 7.

If there is an issue, we return failure at Line 11.

Lifecycle Management

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

For example, when protectedDataWillBecomeUnavailableNotification or willTerminateNotification system notifications are received, edgeEngine stop is called. When protectedDataDidBecomeAvailableNotification system notification is received, edgeEngine start is called automatically.

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

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

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

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

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

Finally, this code example code shows you how to determine whether the mimik Client Library is currently managing the edgeEngine Runtime Lifecycle:

 func edgeEngineLifecycleIsManaged() -> Bool {
     // Calling mimik Client Library class method to determine the lifecycle management state
     switch self.edgeClient.edgeEngineLifecycleIsManaged() {
     case true:
         print("Success")
         // edgeEngine Runtime lifecycle is being managed by the mimik Client Library, returning true
         return true
     case false:
         print("Error")
         // edgeEngine Runtime lifecycle is not being managed by the mimik Client Library, returning false
         return false
     }
 }

Working with an iOS Simulator

Normally, developers intend to run their applications on iOS devices where the mimik Client Library Engine is used to facilitate the integration of the edgeEngine Runtime binary directly within the iOS application sandbox. This is done by vendoring the edgeEngine binary inside the EdgeEngineDeveloper pod component.

However, the inclusion of EdgeEngineDeveloper pod component in the iOS project prevents developers from being able to compile their project for the iOS Simulator or Mac Catalyst environments. This is because the edgeEngine binary is compiled specifically for iOS devices only.

In order to provide a functional workaround, the mimik Client Library is split into its Core EdgeCore and Engine EdgeEngineDeveloper pod components. This gives developers the choice of having the edgeEngine bundled in within the iOS application or having it running externally on a host platform of their choice (e.g., macOS, Linux, Windows, etc...)

So to summarize. When compiling for an iOS device, include the EdgeEngineDeveloper pod component in your project and use edgeEngine internally. When compiling for an iOS Simulator or Mac Catalyst environments, don't include the EdgeEngineDeveloper pod component in your project. Instead, host edgeEngine on an external platform, and activate edgeEngine external support in the mimik Client Library.

The code example below shows you how to conditionally include the EdgeEngineDeveloper pod component, using two different targets.

 target 'internal-edgeEngine-target' do
   pod 'EdgeCore'
   pod 'EdgeEngineDeveloper'
 end
 
 target 'external-edgeEngine-target' do
   pod 'EdgeCore'
 end

The code example below shows you how to conditionally import EdgeEngineDeveloper into your class using the EXTERNAL compiler flag.

 import EdgeCore
 #if !EXTERNAL
 import EdgeEngineDeveloper
 #endif

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

Once edgeEngine is running externally on a macOS host, we can activate the external edgeEngine support in the mimik Client Library, by calling the activateExternalEdgeEngine() method.

The code example below shows you how to do this.

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

You can continue using your application and mimik Client Library normally, keeping in mind that the edgeEngine Runtime is now running externally on a host system. As a result, your iOS application doesn't have any control over its lifecycle.