Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Div | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
|
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 see Authenticating SDK Authentication. - 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.
Anchor | ||||
---|---|---|---|---|
|
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.
Div | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Anchor | ||||
---|---|---|---|---|
|
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.
Anchor | ||||
---|---|---|---|---|
|
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.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 linenumbers true let 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()
Div class tabpage_2 Code Block theme Midnight title Adding instance linenumbers true ApolloCipherBuilder *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];
Anchor | ||||
---|---|---|---|---|
|
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.
Div | ||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||
|
Anchor | ||||
---|---|---|---|---|
|
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!)
.Div dir lrt 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 isTenantAuthTokenRequired() -> bool
Div class tabpage_2 Code Block theme Midnight - (BOOL) isTenantAuthTokenRequired
Info - 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.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 authenticate(tenantToken:String!) -> void
Div class tabpage_2 Code Block theme Midnight - (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.
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 isSecureStoreSetUpRequired()-> bool
Div class tabpage_2 Code Block theme Midnight - (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.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 setUpSecuredStore() -> void
Div class tabpage_2 Code Block theme Midnight - (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.
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 canGenerateSuperPin()-> bool
Div class tabpage_2 Code Block theme Midnight - (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.
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 generateSuperPin(completion: (String?, Error?)->Void ) -> void
Div class tabpage_2 Code Block theme Midnight - (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.
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 add(listener: ApolloCipherStateChangeListener) -> void
Div class tabpage_2 Code Block theme Midnight - (void) addStateChangeListener:(id<ApolloCipherStateChangeListener>) listener
- Remove Listener
Use this method is used to unsubscribe from SDK state updates.
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 remove(listener: ApolloCipherStateChangeListener) -> void
Div class tabpage_2 Code Block theme Midnight - (void) removeStateChangeListener:(id<ApolloCipherStateChangeListener>)
Anchor | ||||
---|---|---|---|---|
|
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:
Div | ||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Anchor | ||||
---|---|---|---|---|
|
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:
Div | ||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||
|
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. |
Info |
---|
There will be other error codes that will be thrown from the SDK with appropriate message. For any assistance, contact Zeta. |
Panel | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|