iOS App Wrappers

This guide serves as a main documentation that you will need to learn how to use and integrate edgeSDK app wrappers into your iOS project.


Main Packages


Installation

Please check the iOS installation page to learn how to install iOS edgeSDK app wrapper packages to your development project.


edgeSDK-iOS wrapper

Note: Normally you would not use this wrapper directly, but use the edgeSDK-iOS-app-ops wrapper for your edgeSDK operations instead. However, it is possible to use edgeSDK-iOS wrapper directly by initializing an instance of edgeSDK-iOS and calling its APIs directly.


Usage


Import Package

                      import edgeSDK_iOS

                      var edgeWrapper: edgeSDK_iOS?
                  

edgeSDK Initialization

                    /**
                      edgeSDK initialization.
                      - Parameter nodeId: Unique node identifier.
                      - Parameter workingDirectory: The root of the working directory for edgeSDK on the file system.
                   */
                   self.edgeWrapper = edgeSDK_iOS.init(nodeId: "MY_DEVICES_PERSISTENT_UNIQUE_IDENTIFIER", workingDirectory: "/path/to/working/directory")
                  

Start edgeSDK

                      /**
                      Start edgeSDK. 
                      - Warning: It usually takes 3 seconds to complete.
                   */
                   edgeWrapper.startEdge()
                    

Stop edgeSDK

                                  /**
                                  Stops edgeSDK. 
                                  - Note: startEdge does the opposite of this function.
                               */
                               edgeWrapper.stopEdge()
                    

Configure edgeSDK

                                    /**
                                    Provides a generic edgeSDK configuration parameters object.
                                    Essentially provides a read only object with edgeSDK configuration parameters (nodeId, nodeName, edgeServiceLink, workingDir).
                                 */
                                 edgeWrapper.getConfig()
                    

Logging edgeSDK

                        /**
                        Provides a way to control the amount of logging output. 
                        mimik modules are using Apple's unified logging system and the messages are tagged with [mimik] [module-name] and then the logging level [info] [error] [fault] [debug].
                     */
                     edgeSDK_iOS.changeLoggingLevelTo(level: MMKLogLevel.error)
        

edgeSDK-iOS-app-ops wrapper

Note: Use edgeSDK-iOS-app-ops wrapper for edgeSDK related system operations, such as initialization, state changes (start, stop), microservices deployment, etc.


Usage


Import Package

                                        import edgeSDK_iOS_app_ops

                                        var appOpsWrapper:  edgeSDK_iOS_app_ops?
                                    

Wrapper Initialization

                                        /**
                                        edgeSDK_iOS_app_ops initialization. Keep a strong reference to it.
                                     */
                                     self.appOpsWrapper = edgeSDK_iOS_app_ops.init()
                                    

Start edgeSDK

                                        /**
   Starts edgeSDK and registers an optional EdgeAppOpsProtocol delegate to receive edgeSDK lifecycle change callbacks.
   Essentially a one call edgeSDK initialization with one parameter (nodeId) and a completion block, 
   as well as a protocol delegate registration to receive callbacks when edgeSDK lifecycle changes.
 
   - Parameter nodeId: Unique node identifier.
   - Parameter delegate: An optional EdgeAppOpsProtocol delegate to receive edgeSDK lifecycle change notifications.
   - Parameter completion: Completion block returning EdgeStatus or Error.
   - Important: Make sure to keep nodeId unique and tied to a specific device. Repeating calls are ignored until stopEdge is called once.
   - Warning: It usually takes 3 seconds for the completion block to be called.
*/
appOpsWrapper.startEdge(nodeId: edge_nodeId, delegate: self, completion: { (status,error) in
    
    guard error == nil else {
        // handle error
        return
    }
    
    guard status != nil else {
       // handle error
        return
    }
    
    // Now getting hashedNodeId from edgeSDK and storing it. This is a breaking change introduced in edgeSDK 1.3.1
    // where it would no longer use the supplied deviceId/nodeId, but instead use its own hashed version of it.
    // Hence we might want to retrieve and store the hashedNodeId for later use.
    
    appOpsWrapper.getInfo({ (response, error) in
        
        guard error == nil else {
            // handle error
            return
        }
        
        guard let hashedNodeId = response?.nodeId else {
            // handle error
            return
        }

        // store hashedNodeId for potential microservice configuration
    })
})
                                    

Stop edgeSDK

                                          /**
                                          Stops edgeSDK and removes the EdgeAppOpsProtocol delegate registration.
                                          Essentially a one call edgeSDK shutdown with a completion block.
                                        
                                          - Important: Repeating calls are ignored until startEdge is called once.
                                          - Warning: It usually takes 3 seconds for the completion block to be called.
                                          - Note: This will stop the edgeSDK lifecycle change notifications.
                                       */
                                       appOpsWrapper.stopEdge { (status, error) in
                                           guard error == nil else {
                                               // handle error
                                               return
                                           }
                                       }
                                    

Microservice Deployment

                                                guard let edgeAccessToken = mystorage.loadToken(type: .accessToken) else {
                                                  fatalError()
                                              }
                                              
                                              /**
                                                 Micro service configuration object. Used for micro service deployment.
                                               
                                                 - name: Name of your micro service. Used to construct paths.
                                                 - apiRootUrl: A path to deploy your micro service to.
                                                 - imagePath: An file system path to the micro service image tar file. Usually located in the application's bundle.
                                                 - envVariables: Any extra environment variables for your micro service.
                                              */
                                              let microServiceConfig: MicroserviceDeploymentConfig = configuration
                                              
                                                  /**
                                                   Deploys a micro service according to a configuration object.
                                                   Essentially a one call micro service deployment with a completion block via a simple configuration object; edge access token is required.
                                                   
                                                   - Parameter edgeAccessToken: Token retrieved from a sucessful authorization session.
                                                   - Parameter config: Micro service configuration object.
                                                   - Parameter completion: Completion block returning micro service DeploymentStatus or Error.
                                                   - Important: Repeating calls will overwrite already deployed micro services. Connected websockets will be destroyed.
                                                   - Note: First the micro service image is uploaded, then the micro service container is created.
                                                   - ToDo: Comparing deployed micro services using a digest checksum
                                                   */
                                                  appOpsWrapper.deployMicroservice(edgeAccessToken: edgeAccessToken, config: microServiceConfig) { (status,error) in
                                                  
                                                  guard error == nil else {
                                                      // handle error
                                                      return
                                                  }
                                                  
                                                  // micro service deployment sucessful, examine the status object.
                                              }
        

Get edgeSDK Info

                                                  /**
                                                  Provides an instance specific edgeSDK parameters EdgeInfo object.
                                                  Essentially provides a read only EdgeInfo object with edgeSDK instance parameters (nodeId, nodeName, version, accountId) in a completion block.
                                               */
                                               getInfo(_ completion: @escaping ((response: EdgeInfo?, error: Error?)) -> Void)
        

Get edgeSDK Config

                                                    /**
                                                    Provides a generic edgeSDK configuration parameters EdgeConfig object.
                                                    Essentially provides a read only EdgeConfig object with edgeSDK configuration parameters (nodeId, nodeName, edgeServiceLink, workingDir, backend) in a completion block.
                                                 */
                                                 getConfig(_ completion: @escaping ((response: EdgeConfig?, error: Error?)) -> Void)
        

Update edgeSDK with new Location

                                                        /**
                                                        Updates edgeSDK with a CLLocation object containing the geographical location, altitude, speed and bearing of a device.
                                                     */
                                                     updateGps(_ edgeAccessToken: String, location: CLLocation, completion: @escaping ((response: String?, error: Error?)) -> Void) 
        

edgeSDK Level Control

                                                      /**
                                                      Provides a way to control the amount of logging output.
                                                      mimik modules are using Apple's unified logging system and the messages are tagged with [mimik] [module-name] and then the logging level [info] [error] [fault] [debug].
                                                   */
                                                   edgeSDK_iOS_app_ops.changeLoggingLevelTo(level: MMKLogLevel.error)
        

edgeSDK-iOS-app-auth wrapper

Note: Use the edgeSDK-iOS-app-auth wrapper for all your edgeSDK authorization and association operations.


Usage


Import Package

                                                              import edgeSDK_iOS_app_auth

                                                              var appAuthWrapper:  edgeSDK_iOS_app_auth?
      

Wrapper Initialization

                                                                self.appAuthWrapper = edgeSDK_iOS_app_auth.init()

      

Account Authorization and Association

                                                                  let kClientId: String = "YOUR_CLIENT_ID_FROM_DEVELOPER_PORTAL"
                                                                  let kRedirectURL: URL = "YOUR_REDIRECT_URL_FROM_DEVELOPER_PORTAL"
                                                                  let kAuthorizationURL: URL = URL.init(string: "my-authorization-server")
                                                                  let additionalScopes = [ "read:myscope", "write:myscope"]
                                                                  let authConfig = AuthConfig.init(clientId: kClientId, redirectUrl: kRedirectURL, additionalScopes: additionalScopes, authorizationRootUrl: kAuthorizationURL)
                                                                  
                                                                  /**
                                                                     Starts an authorization session in a view controller according to the AuthConfig configuration object. 
                                                                     Essentially a one call authorization with a completion block via a simple configuration object.
                                                                   
                                                                     - Parameter authConfig: Authorization configuration object.
                                                                     - Parameter viewController: View controller to be used to load the sfauthenticationsession.
                                                                     - Parameter completion: Completion block returning micro service AuthStatus or Error.
                                                                     - Note: First the authorization's server configuration is discovered, then the authentication page is 
                                                                             loaded into the view controller and a sfauthenticationsession is established. If successful edgeSDK 
                                                                             gets associated with the logged in account and authentication tokens are returned in the completion block..
                                                                  */
                                                                  
                                                                  appAuthWrapper.authorize(authConfig: authConfig, viewController: self, completion: { (status, error) in
                                                                      
                                                                      guard error == nil else {
                                                                          // handle error
                                                                          return
                                                                      }
                                                                      
                                                                      guard status != nil else {
                                                                         // handle error
                                                                          return
                                                                      }
                                                                      
                                                                      // authorization successful, save status for future use (ie. access tokens)
                                                                      })
                                                                  })
      

Account Unassociation

                                                                    let kClientId: String = "YOUR_CLIENT_ID_FROM_DEVELOPER_PORTAL"
                                                                    let kRedirectURL: URL = "YOUR_REDIRECT_URL_FROM_DEVELOPER_PORTAL"
                                                                    let kAuthorizationURL: URL = URL.init(string: "my-authorization-server")
                                                                    let authConfig = AuthConfig.init(clientId: kClientId, redirectUrl: kRedirectURL, additionalScopes: nil, authorizationRootUrl: kAuthorizationURL)
                                                                    
                                                                    /**
                                                                       Starts an unauthorization session in a view controller according to the AuthConfig configuration object in order to 
                                                                       unassociate edgeSDK from the currently associated account. Essentially a one call edgeSDK account unassociation with 
                                                                       a completion block via a simple configuration object.
                                                                     
                                                                       - Parameter authConfig: Authorization configuration object.
                                                                       - Parameter viewController: View controller to be used to load the sfauthenticationsession.
                                                                       - Parameter completion: Completion block returning micro service AuthStatus or Error.
                                                                       - Note: First the authorization's server configuration is discovered, then the authentication page is loaded into the 
                                                                       view controller and a sfauthenticationsession is established. If successful edgeSDK gets unassociated from the currently associated account.
                                                                    */
                                                                    
                                                                    appAuthWrapper.unauthorize(authConfig: authConfig, viewController: self, completion: { (status,error) in
                                                                        
                                                                            guard error == nil else {
                                                                            // handle error
                                                                            return
                                                                        }
                                                                        
                                                                        guard status != nil else {
                                                                           // handle error
                                                                            return
                                                                        }
                                                                        
                                                                        // unauthorization successful, clear saved auth status
                                                                    })