- Created by Seema, last modified on Jun 11, 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 19 Next »
Learn how to integrate Cipher SDK on iOS device. |
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 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:
- Fusion uses
tenantAuthToken
to authenticate the SDK. To know how to createtenantAuthToken
, see Authenticating SDK. - Minimum iOS version required: 9
- Install the code editor XCode.
Getting Started with iOS Cipher SDK
Follow the steps below to integrate SDK:
- Download the Framework which contains the structure and required libraries for your Project.
- Now install the SDK in your app.
- Prepare the SDK setup.
- Add the implementation for Secured Store setup.
- Configure the API operations of Cipher service.
- Now the SDK setup is ready to begin with verifying the SDK.
- Finally, call Logout API to clear the session data.
Step 1: Download the Framework
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.
To add the Framework into your project, extract the below zip folder containing an XCFramework for Cipher SDK.
Step 2: Install the SDK
The iOS Card SDK is compatible with apps supporting iOS 9 and above. To install the SDK, follow these steps:
Drag & drop the XCFramework manually into your project's target.
Click Embed & sign under the XCFramework in your project's target.
- Set Allow Non-modular Includes in Framework Modules to "YES" under Target > Build Settings.
Set Enable Bitcode to "NO" under Target > Build Settings.
Step 3: Set up the SDK
Follow the steps below to set up the SDK:
- Add the Configuration file:
You must addcipher.plist
(properties list file) to your project as it contains all the configurations necessary for activating the SDK. You will receive thecipher.plist
file 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 theNSfaceIdUsageDescription
(Privacy - Face ID Usage Description) with a message in theinfo.plist
file. However, this step is not needed if the app is providing its own secure store access. Initialize the SDK:
The Cipher build is initialized with tenant secure store, if a new secure store is not required by the tenant.Swift
Objective C
Adding instancelet cipher: ApolloCipher = ApolloCipherBuilder() .setSecureStore(tenantSecureStore) // AppSecuredStoreAccess. To be provided when using the tenant secured store .setViewContext(viewController) // An instance of UIViewController to show modals. Not required if using tenant secured store .build()
Adding instanceApolloCipherBuilder *builder = [ApolloCipherBuilder new]; [builder setSecureStore:appSecureStoreAccess]; // AppSecuredStoreAccess. To be provided when using the tenant secured store [builder setViewContext:viewController]; // An instance of UIViewController to show modals. Not required if using tenant secured store ApolloCipher *cipher = [builder build];
Step 4: Set up the Secured Store
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:
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.
Swift
Objective C
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
- (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;
Step 5: Configure the SDK
You can configure the SDK by providing the implementation for the following APIs based on your requirement:
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.
- Check the state of Cipher SDK
If a call to
isTenantAuthTokenRequired()
returns true, you should providetenantAccessToken
by triggeringauthenticate(tenantToken:String!)
.Swift
Objective C
isTenantAuthTokenRequired() -> bool
- (BOOL) isTenantAuthTokenRequired
- We recommend updating
tenantAuthToken
token at every app launch. This ensures hassle-free creation ofauth
resource by the SDK whenever needed. tenantAuthToken
must be generated on the server-side as it involves signing the data with a private key. The private key must never be compromised.
- We recommend updating
- Create an authentication token
This method authenticates a tenant user by providing a
tenantAuthToken
to the SDK.Swift
Objective C
authenticate(tenantToken:String!) -> void
- (void) authenticateWithToken:(NSString *) tenantToken
Set up Secured Store
If a call to isSecureStoreSetUpRequired()
returns true, you are ready to set up the Secured Store by triggering the setUpSecuredStore()
.
- Check the state of Cipher SDK
If this method returns true, the SDK requires a Secured Store setup.
Swift
Objective C
isSecureStoreSetUpRequired()-> bool
- (BOOL) isSecureStoreSetUpRequired
- Call setUpSecuredStore API
This method triggers setup of secure storage. Ensure this method is called only if
isSecuredStoreSetupRequired()
returns true, else this leads the SDK into an unusable state. Post this step, SDK will be able to setup the Super PIN.Swift
Objective C
setUpSecuredStore() -> void
- (void) setUpSecuredStore
Generate Super PIN
If a call to canGenerateSuperPin()
returns true, you can generate a Super PIN to secure the store by triggering generateSuperPin(completion: String, Error)
.
- Check the state of Cipher SDK
If this method returns true, the Super PIN setup is done. If the Super PIN functionality doesn’t work, the SDK might be in an error state. In such scenario, logout and then run the whole SDK from beginning.
Swift
Objective C
canGenerateSuperPin()-> bool
- (BOOL) canGenerateSuperPin
- Create Super PIN
This method returns the Super PIN on providing authentication to the Secured Store or a device lock. Use this Super PIN to authorize the payment.
Swift
Objective C
generateSuperPin(completion: (String?, Error?)->Void ) -> void
- (void) generateSuperPinWithCompletion:(SuperPinFetchBlock) completion
Manage Listener
You can listen to any change in the state of Cipher SDK integration such as, when an authentication token is required, is Secured Store set up required, can Super PIN be generated.
- Add Listener
Use this method is used to subscribe to SDK state updates.
Swift
Objective C
add(listener: ApolloCipherStateChangeListener) -> void
- (void) addStateChangeListener:(id<ApolloCipherStateChangeListener>) listener
- Remove Listener
Use this method is used to unsubscribe from SDK state updates.
Swift
Objective C
remove(listener: ApolloCipherStateChangeListener) -> void
- (void) removeStateChangeListener:(id<ApolloCipherStateChangeListener>)
Step 6: Verify the SDK
You can instruct the SDK to perform actions based on your configurations. After the Secured Store is setup, you can decide the actions to be taken as shown in the code snippet below:
Swift
Objective C
if(cipher.isTenantAuthTokenRequired()) { // The SDK is in uninitialized state. You should provide ‘tenantAccessToken’ by triggering 'cipher.authenticate(with:)' API } else if (cipher.isSecureStoreSetUpRequired()) { // You are ready to setup the Secure Store by triggering 'setUpSecuredStore()' API } else if (cipher.canGenerateSuperPin()) { // You are ready to trigger 'cipher.generateSuperPin(completion:)' API } else { // The SDK is in a corrupt state. You can trigger logout() API to reset the SDK }
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 }
Step 7: Logout
When a user logs out from the app, ensure that you clear all the session data. A default call to Logout method is important for the SDK to work properly in next login session.
A simple logout is available by using:
Swift
Objective C
self.cipherManager?.logout()
[self.cipherManager logout]
Exceptions and Error Codes
This section explains various exceptions and error codes thrown by the Cipher SDK and how to handle 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 message:
code
: Error code related to the response.traceId
: Trace ID which can be provided to Zeta support for identifying the root cause.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 the issue persists, contact Zeta.
Error Code | Description |
---|---|
| Exception thrown due to bad request. |
3001 | Internal server error. Try again. |
1001 | Internal SDK error. Try logging out and then log in. |
2000 | Authentication of
|
2001 | Internal error caused while trying to authenticate the user. |
1001 | Error occurred when the user cancels the secure store setup. |
There will be other error codes that will be thrown from the SDK with appropriate message. For any assistance, contact Zeta.
- No labels