Cipher SDK is a Two Factor Authentication (2FA) solution designed to provide a secure way of verifying transactions. This is achieved by enabling customers to verify their identity.  Cipher Cipher SDK ensures a safe implementation of 2FA with minimum friction without the need of OTP generation . 

In this article, SDK integration is documented in both Swift and Objective C languages.

Before you begin

Take care of the following prerequisites before you begin with SDK setup:

with SDK set up:

• Fusion uses an authentication token to authenticate the SDK. Know more about the authentication token and see how to create an authentication token.
• Minimum iOS version required: 10
• Minimum Cocoapods version required: 1.9
• Install the code editor XCode.
• .1
• Ensure you have a cipher.plist file which contains configuration data necessary to set up the SDK. Contact Zeta in case if you haven't received the file.

• Set up push notifications for your app and share the .p8 file, APNS Key and Team ID in our dashboard. This set up is required only if you are integrating the Swipe to Authenticate feature of SDK.

Getting Started with iOS Cipher SDK

Follow the steps below to integrate SDK:

1. Download the Framework which contains the structure and required libraries for your Project. 
2. Now install the SDK in your First, you should add the SDK to your project or app.
3. Prepare the the SDK setupset up.
4. Add the implementation for Secured Store setup.
5. Configure the API operations of Cipher service.
6. Now the SDK setup set up is ready to begin with verifying with integration process

Anchor
Adding the SDK

Adding the SDK

Step 1:

Adding the

In Fusion, the SDKs are built on top of a Framework  which is a combined set of libraries to help you easily create a production-ready app, by providing a unified platform from where you can manage your app and observe the analytics of the app. The XC Framework packaging is used to package different variants of the Framework to support any platform such as iOS, macOS and others. 

SDK

The iOS Cipher SDK is compatible with apps supporting iOS with version 10 and above. To add the SDK to your project, follow these steps:

1. Download and extract the below zip folder containing

The iOS Card SDK is compatible with apps supporting iOS 9 and above. To install the SDK, follow these steps:

1. an XCFramework for Cipher SDK.
   

   Div
   class custom-zip-cls
   View file name Cipher_XCFramework.zip height 150

1. Drag & drop the XCFramework manually manually into your project's target.  

   Image Modified

2. Click Click Embed & sign under the  under the XCFramework in in your project's target.
   Image Modified

3. Set Set Allow Non-modular Includes in Framework Modules to to "YES" under underTarget >  > Build Settings.

4. Set Set Enable Bitcode to to "NO" under underTarget >  > Build Settings.

Anchor

SettinguptheSDK

SettinguptheSDK

Step

2:

Setting up the SDK

Follow the steps below to set up the SDK: 

• Add the

• configuration file

• Configure properties
• Initialize the SDK

Add the configuration file

A configuration file contains all the properties necessary for activating the SDK.

You should add the file to your project (app/src/main/assets/) to prepare your app to work with the SDK. You will receive the configuration file named cipher.plist

through email.

If you haven't received the file,

contact Zeta.

Configure properties

To enable authentication using face recognition (Face ID), add a value to the NSfaceIdUsageDescription (Privacy - Face ID Usage Description) with a message in the info.plist file.

However, this step is not needed if the app is providing its own secure store access.

Initialize the SDK

Create the ApolloCipher instance in your AppDelegate file. Initialize it inside the [application didFinishLaunchingWithOptions:] method of your Application class. Keep the instance for ApolloCipher globally accessible.

Div
class customtabs remove-codeblock-space
Div class tabsmenu Div class tabsmenu_1 Swift Div class tabsmenu_2 Objective C Div class tabscontent Div class tabpage_1 Code Block theme Midnight title Adding

instance

instances linenumbers true

let

import CipherFramework @UIApplicationMain Class AppDelegate { var cipher: ApolloCipher? func application:(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionKey: Any]?) -> Bool { let builder = ApolloCipherBuilder()

.setSecureStore(tenantSecureStore

builder.setSendPushForSandbox(true) //

AppSecuredStoreAccess.

Set this false when you are archiving for App Store. By Default, this is set as false. builder.setSecureStore(securedStoreAccess) //AppSecuredStoreAccess - To be provided when using

the

tenant secured store

.

setViewContext(viewController)//AninstanceofUIViewControllertoshow

cipher

modals. Not required if using tenant secured store .build()

= builder.build() //… } //... } Div class tabpage_2 Code Block theme Midnight title Adding

instance

instances linenumbers true #import <CipherFramework/CipherFramework.h> @interface AppDelegate() @property (nonatomic, strong) ApolloCipher *cipher; @end @implementation AppDelegate -(BOOL) application:(UIApplication*) application didFinishLaunchingWithOptions:(NSDictionary *) launchOptions { ApolloCipherBuilder *builder = [ApolloCipherBuilder new]; [builder

setSecureStore:appSecureStoreAccess

setSendPushForSandbox: YES]; // Set this as NO when you are archiving for App Store. By Default, this is set as NO. [builder setSecureStore:securedStoreAccess]; // AppSecuredStoreAccess

.

- To be provided when using

the

tenant secured store. self.cipher = [builder

setViewContext:viewController];

.build] //…

An instance of UIViewController to show modals. Not required if using tenant secured store ApolloCipher *cipher = [builder build]; AnchorSetuptheSecuredStoreSetuptheSecuredStoreStep 4: Set up the Secured StoreFor setting up

} //... @end

Anchor
IntegratingtheSDK IntegratingtheSDK

Step 3: Integrating the SDK

Cipher SDK is a stateful SDK. Before you start using the Cipher SDK features, take care of the following:

• Registering the SDK
• Setting up the Secured Store
• Setting up the state change listener
• Setting up Swipe to Authenticate

Registering the SDK

Cipher SDK registration triggers the authentication of the SDK using an authentication token. This token is also called a JSON Web Token (JWT) token. Please ensure to set a valid JWT token every time to register the SDK. We recommend calling the method inside the following Application function. To know how to create the authentication token, see Authenticating SDK. You require this token in Authentication API request.

func applicationDidBecomeActive(_ application: UIApplication) {
   cipher?.authenticate(tenantToken: tenantTokenView.text)
   //...
}

- (void)applicationDidBecomeActive:(UIApplication *)application {
   [self.cipher authenticateWithToken:<JWT_TOKEN>];
   //...
}

Setting up the Secured Store

Cipher SDK maintains various pieces of sensitive information like Super PIN, secrets. The SDK stores this sensitive information in a Secured Store. Cipher SDK supports the following Secured Store implementations:

• SDK implementation
• Hosting app’s custom implementation

SDK implementation

Cipher SDK provides an implementation of the Secured Store out of the box. The SDK provided secured store supports the following:

• Device lock:
  The device lock is enabled by default.

• SDK Super PIN:
  The SDK uses 4 digit SDK PIN, if you haven't enabled the device lock to access your custom secured store. In this case, the SDK prompt you to set up the SDK PIN for securing sensitive data.

  Note
  Ensure you run setModalPresenterScreen before accessing the Super PIN and Swipe to Authenticate functionalities .

For setting up the Secured Store, you must provide an implementation for AppSecuredStoreAccess protocol. This protocol enables the Cipher SDK to securely store/retrieve sensitive data into your secure store. The protocol is responsible for four different functionalities as mentioned below Secured Store. To adhere to the protocol, implement the following functionalities:

• dataforKey:completion: to fetch data from the store for a particular key.
  
• setDataforKey:completion: to set data in the store for a particular key.
  
• resetAllData: to reset all the data in store.
  
• containsKey: to check if data for a key exists.

If you haven't provided access to your Secured Store and the device lock is also disabled, contact Zeta for assistance. 

@protocol AppSecuredStoreAccess {
    func data(forKey key: String, completion: ((Error?, Data?) -> Void)? = nil)  
    func setData(_ data: Data?, forKey key: String, completion: ((Error?) -> Void)? = nil)  
    func resetAllData()    
    func containsKey(_ key: String) -> Bool 
}

@protocol AppSecuredStoreAccess
 - (void)dataForKey:(NSString *_Nonnull)key
        completion:(nullable void (^)(NSError * _Nullable error, NSData * _Nullable data))completion;
 
- (void)setData:(NSData *_Nullable)data forKey:(NSString *_Nonnull)key completion:(nullable void (^)(NSError * _Nullable error))completion;
 
- (void)resetAllData;
 
- (BOOL)containsKey:(NSString *_Nonnull) key;

@end

Setting up the state change listener

You can configure instruct the SDK by providing the implementation for the following APIs based on your requirement:

• Authenticate the SDK
• Set up Secured Store
• Generate Super PIN
• Manage Listener

Authenticate the SDK

An authentication token is required to authenticate the SDK. This is an initial state of the SDK which is achieved on clean install.

If a call to isTenantAuthTokenRequired() returns true, you should provide tenantAccessToken by triggering authenticate(tenantToken:String!).

to perform actions based on your configurations. After the Secured Store is set up, you can decide the actions to be taken as shown in the code snippet below:

cipher?.add(listener: <ApolloCipherStateChangeListenerImplementation>)
cipher?.authenticate(tenantToken: tenantTokenView.text) 
// In Implementation of ApolloCipherStateChangeListener protocol
- (func) stateChanged {
    if(cipher?.isSecureStoresetupRequired())
        cipher?.setModalPresenterScreen(<TopViewController>)
        cipher?.set upSecuredStore()
    } else if (cipher?.canGenerateSuperPin()) {
    	//Now Cipher SDK is ready to generate Super PIN and handle Swipe To Authenticate requests
    	} else {
        	cipher?.logout()
    		}
} 

[self.cipher addStateChangeListener:<ApolloCipherStateChangeListenerImplementation>]
[self.cipher authenticateWithToken:<JWT_TOKEN>];
// In Implementation of ApolloCipherStateChangeListener protocol
- (void) stateChanged {
    if ([self.cipher isSecureStoreset upRequired]) {
        [self.cipher setModalPresenterScreen:<TopViewController>]
        [self.cipher setupSecuredStore];
    } else if ([self.cipher canGenerateSuperPin]) {
        //Now Cipher SDK is ready to generate Super PIN and handle Swipe To Authenticate requests
      } else {
        [self.cipher logout]
        }
}

Setting up Swipe to Authenticate

The Swipe to Authenticate flow is set up along with the setting up the state change listener flow. At Zeta, we use Apple Push Notification Service (APNs) to deliver Swipe to Authenticate notifications to your app . You should set up push notifications for your app if you have not done that already. Here are the details on how to do this. After setting up the push notifications for your app, share your p8 file, team id and push notification key with our team at Zeta . We will use your APNs key to deliver notifications to your app from our server.

Syncing the push token

You should override your [application:didRegisterForRemoteNotificationsWithDeviceToken:]
inside your AppDelegate and convert the received push token to string. Now call updatePushToken: method whenever you receive a callback for the new push token . This helps the SDK to keep the push token synced in our servers and ensure a hassle-free push experience. You can use the following code snippet:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        let tokenParts = deviceToken.map { data in String(format: "%02.2hhx", data) }
        let token = tokenParts.joined()
        cipher?.updatePushToken(token)
}

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    const unsigned *tokenBytes = [deviceToken bytes];
    NSString *hexToken = [NSString stringWithFormat:@"%08x%08x%08x%08x%08x%08x%08x%08x",
                         ntohl(tokenBytes[0]), ntohl(tokenBytes[1]), ntohl(tokenBytes[2]),
                         ntohl(tokenBytes[3]), ntohl(tokenBytes[4]), ntohl(tokenBytes[5]),
                         ntohl(tokenBytes[6]), ntohl(tokenBytes[7])];
    [self.cipher updatePushToken:hexToken];
}

Listen to Swipe to Authenticate Push

When you receive a push notification inside the overridden didReceiveRemoteNotificationmethod of your AppDelegate, you should relay that remote notification received to Cipher SDK . You can use processSwipe2PayRemoteNotification:presentingWindow method to relay the push message object to the Cipher SDK . You can use the following code snippet:

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> 

Void) {
	if let cipher = cipher {
    	if cipher.canProcessRemoteNotification(userInfo) {
        	cipher.processSwipe2PayRemoteNotification(userInfo, presenting: window!)
		}
	}
}

- (

void)

application:(UIApplication *)application
	didReceiveRemoteNotification:(NSDictionary *)userInfo
    	fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    		if([self.cipher canProcessRemoteNotification:userInfo]) {
        		[self.cipher processSwipe2PayRemoteNotification:userInfo presentingWindow:self.window];
    		}
}

API Reference

Cipher SDK provides a set of public APIs which are useful to set up the SDK and access its functionalities.

• Authentication
• Secured Store
• Generate Super PIN
• Set up the modal presenter screen
• Handle notification
• Monitor token update
• Manage Listener
• Remote notification
• Logout

Authentication

This API authenticates and provides you the access to the SDK. You should pass the authentication token (tenantToken) in this API request.

authenticate(tenantToken:

 NSString!) -> void

- (void) authenticateWithToken:(NSString *) tenantToken

Secured Store

If a call to isSecureStoreSetUpRequiredisSecureStoresetupRequired() returns returns true, you are ready to set up the Secured Store by triggering the setUpSecuredStorethe setupSecuredStore().

1. Check the state of Cipher SDK
   

   If this method returns true, the SDK requires a Secured Store setup set up.

   Div
   class customtabs remove-codeblock-space
   Div class tabsmenu Div class tabsmenu_1 Swift Div class tabsmenu_2 Objective C Div class tabscontent Div class tabpage_1 Code Block theme Midnight isSecureStoreSetUpRequiredisSecureStoresetupRequired()-> bool Div class tabpage_2 Code Block theme Midnight - (BOOL) isSecureStoreSetUpRequiredisSecureStoresetupRequired

2. Call setUpSecuredStore setupSecuredStore API
   

   This method triggers setup set up of secure storage. Ensure this method is called only if isSecuredStoreSetupRequiredif isSecuredStoresetupRequired() returns returns true, else this leads the SDK into an unusable state. Post this step, SDK will be able to setup set up the Super PIN.

   Div
   class customtabs remove-codeblock-space
   Div class tabsmenu Div class tabsmenu_1 Swift Div class tabsmenu_2 Objective C Div class tabscontent Div class tabpage_1 Code Block theme Midnight setUpSecuredStoresetupSecuredStore() -> void Div class tabpage_2 Code Block theme Midnight - (void) setUpSecuredStoresetupSecuredStore

setModalPresenterScreen:(_ modalPresenter: UIViewController)

- (void) setModalPresenterScreen: (UIViewController *)modalPresenter;

canProcessRemoteNotification(_ userInfo: NSDictionary) -> bool

- (

BOOL) canProcessRemoteNotification:(NSDictionary *)userInfo

updatePushToken(_ pushToken:String)

- (void) updatePushToken:(NSString *) pushToken

processSwipe2PayRemoteNotification:(_ userInfo:NSDictionary,  presentingWindow window:UIWindow)

if([_cipher isTenantAuthTokenRequired]) {
        // The SDK is in uninitialized state. You should provide ‘tenantAccessToken’ by triggering [_cipher authenticateWithToken:] API
} else if ([_cipher isSecureStoreSetUpRequired]) {
        // You are now ready to setup the secure store by triggering [_cipher setUpSecuredStore] API
} else if ([_cipher canGenerateSuperPin]) {
        // You are ready to trigger [_cipher generateSuperPinWithCompletion:] API
} else {
        // The SDK is in a corrupt state. You can trigger [_cipher logout] API to reset the SDK 
}

- (void) processSwipe2PayRemoteNotification:(NSDictionary *)userInfo presentingWindow:(UIWindow *) window

cipher?.logout()

[self.

cipher logout]

Exceptions and Error Codes

This section explains section explains various exceptions and error codes thrown by the Cipher SDK and how to handle themhandle them. Exceptions provide system error codes along with Throwable message, that helps to recognize and troubleshoot the issue.

All the exceptions thrown will have the following fields in addition to the messagethe message:

1. code: Error code related to the response.
2. traceId: Trace ID which can be provided to Zeta support for identifying the root cause.
3. errorType: Type of error. 

There are two kinds of exception that Cipher SDK can throw:

• SdkAuthException
• CipherException

The following table lists the error codes, descriptions and possible solutions.  If If the issue persists, contact contact Zeta.