developer portal

Documentation

edgeSDK iOS Wrapper

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

  • edgeSDK-iOS wrapper: helps you to initialize edgeSDK in iOS application.
  • edgeSDK-iOS-app-ops wrapper: helps you to operate edgeSDK, such as microservices deployment and other functions.
  • edgeSDK-iOS-app-auth wrapper: helps you with edgeSDK account authorization and association.

Wrapper installation

The easiest way to integrate edgeSDK to an iOS application is by adding the iOS edgeSDK app wrappers as dependencies to your iOS project. You can use CocoaPods to install iOS edgeSDK app wrappers easily. Just add the following lines of codes to your Podfile:

platform: ios, '11.0'
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/mimikgit/cocoapod-edge-specs.git'

target 'your_target' do
    /* below packages includes edgeSDK-iOS as dependency */
    pod 'edgeSDK-iOS-app-auth'
    pod 'edgeSDK-iOS-app-ops'
end

 

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.

This wrapper has the following usages:

  • Import package
  • Wrapper initialization
  • Start edgeSDK
  • Stop edgeSDK
  • Microservice Deployment
  • Get edgeSDK info
  • Get edgeSDK config
  • Update edgeSDK with new location
  • edgeSDK level control

Import and initialize package

Description

Import wrapper to project.

Example Code

import edgeSDK_iOS_app_ops
var appOpsWrapper:  edgeSDK_iOS_app_ops?
self.appOpsWrapper = edgeSDK_iOS_app_ops.init()

Start edgeSDK

Description

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.

Example Code

/**
   - 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.
    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

Description

Stops edgeSDK and removes the EdgeAppOpsProtocol delegate registration. Essentially a one call edgeSDK shutdown with a completion block.

Example Code

/**
   - 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

Description

First, you create a microservice configuration object which used for microservice deployment. Then, deploys a micro service according to a configuration object. Essentially one call microservice deployment with a completion block via a simple configuration object and edge access token is required.

Example Code

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

Get edgeSDK info

Description

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.

Example Code

getInfo(_ completion: @escaping ((response: EdgeInfo?, error: Error?)) -> Void)

Get edgeSDK config

Description

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.

Example Code

getConfig(_ completion: @escaping ((response: EdgeConfig?, error: Error?)) -> Void)

Update GPS location

Description

Updates edgeSDK with a CLLocation object containing the geographical location, altitude, speed and bearing of a device.

Example Code

updateGps(_ edgeAccessToken: String, location: CLLocation, completion: @escaping ((response: String?, error: Error?)) -> Void)

edgeSDK log level control

Description

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].

Example Code

edgeSDK_iOS_app_ops.changeLoggingLevelTo(level: MMKLogLevel.error)

 

iOS App Auth wrapper

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

This wrapper has the following usages:

  • Import package
  • Wrapper initialization
  • Account authorization and association
  • Account unassociation

Import and initialize package

Description

Import wrapper to project.

Example Code

import edgeSDK_iOS_app_auth
var appAuthWrapper:  edgeSDK_iOS_app_auth?
self.appAuthWrapper = edgeSDK_iOS_app_auth.init()

Account authorization and association

Description

Starts an authorization session in a view controller according to the AuthConfig configuration object. Essentially one call authorization with a completion block via a simple configuration object.

Example Code

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)

/**
   - 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

Description

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.

Example Code

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)

/**
   - 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
})

Need more help?

Feel free to contact us on stack overflow or send us a question via our support page if you have any questions.

Was this page helpful?