- Created by user-5c3b0, last modified by Seema on May 23, 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 10 Next »
Learn how to integrate Cipher SDK on Android 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, you will learn how to integrate Android Cipher SDK.
Before you begin
Take care of the following prerequisites before you begin with SDK setup:
- Ensure you have a
cipher.json
file which contains configuration data necessary to set up the SDK. Contact Zeta in case if you haven't received the file. - Fusion uses authentication token to authenticate the SDK. To know how to generate an authentication token, see SDK Authentication.
- Minimum Android SDK version required: 19
- Minimum Java Runtime Environment (JRE) version required: 8
Getting Started with Android Cipher SDK
Follow the steps below to integrate SDK:
- First, you should add the SDK to your project or 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 Android Cipher SDK API to clear the session data.
Step 1: Add the SDK
The Android SDK is compatible with apps supporting Android with version 4.4 to 4.4.4 or API level 19 and above. To add the SDK to your project, follow these steps:
Add the following rule to your project-level gradle file. This downloads the Maven repository which holds all the build artifacts and dependencies necessary for your project.
Project build.gradle Expand sourceallprojects { repositories { .... maven{url 'https://apollo-maven.corp.zeta.in/nexus/content/repositories/releases/' } maven {https://apollo-maven.corp.zeta.in/nexus/content/repositories/snapshots/} .... } configurations.all { // Add this if you face issue related to rxjava2 resolutionStrategy.force "io.reactivex.rxjava2:rxandroid:2.1.0" } }
We recommend to maintain the order of including the repositories as mentioned in the above code for project-level gradle.
In your module app-level gradle file, add the following rules:
app build.gradle Expand sourceandroid { ……. defaultConfig { //Use this for debug build. multiDexEnabled true } ........ compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } kotlin_options = { jvmTarget = "1.8" } // Include this if you face any packing errors. packagingOptions { exclude 'META-INF/library_release.kotlin_module' exclude 'META-INF/DEPENDENCIES' } ........ }
Following are the descriptions of different modules in app-level gradle code:
multiDexEnabled
: Optional. Add this for debugging the build if you overshoot the 64K methods ceiling.compileOptions
: Required. Add support for Java 8 language features.packagingOptions
: Optional. Add this only if you face packaging error.dependencies
: Required. Include Card SDK dependencies for the latest version.
Step 2: Set up the SDK
Follow the steps below to set up the SDK:
Add the configuration file
A configuration file contains all the configurable 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 namedcipher.json
through email. If you haven't received the file, contact Zeta.Intialize the SDK
In the
onCreate()
method of your application class, create ain.android.zeta.acs.CipherService
instance.CipherService instancefinal CipherService cipherService = new CipherBuilder(this) .setTenantSecuredStoreAccess(securedStoreAccess) // AppSecuredStoreAccess. To be provided when using the tenant secured store .setUseDeviceLock(false) // Enable this when you want to use device lock. Application when setUseCustomStore is set as false. This is set as true by default .setUseCustomStore(true)// Set this true if you want to provide an implementation of your own secured store. This is set as false by default .setSuperPinExceptionListener(superPinExceptionListener) .build();
If you are using Timber logging utility, initialize it after initialization of Cipher SDK.
Step 3: Set up the Secured Store
The sensitive information used to generate the Super PIN is stored in the Secured Store accessible through a PIN, pattern and biometric identification. Cipher SDK provides an implementation of the Secured Store out of the box. The SDK provided secured store supports device lock or a Super PIN. The device lock is enabled by default.
During creation of the CipherService instance using CipherBuilder
, you can manage the following SDK customizations:
CipherBuilder.setUseDeviceLock(false)
means device lock is disabled. Set this to true, if you want to use device lock. By default this is set as true, when.setUseCustomStore
is set as false.CipherBuilder.setUseCustomStore(false)
means you want use SDK provided Secured Store. Set this to true, if you want to use your Secured Store. This set as false by default.
Now you are ready to provide an implementation for AppSecuredStoreAccess
interface. This interface enables the Cipher SDK to securely store/retrieve sensitive data into your Secured Store.
public interface AppSecuredStoreAccess { interface SetaDataInSecureStoreListener { void done(final boolean success, final Exception exp); } void setDataInSecureStore(@NonNull final String key, final byte[] data, @NonNull final SetaDataInSecureStoreListener listener); interface GetDataInSecureStore { void done(final byte[] data, final Exception exp); } void getDataFromSecureStore(@NonNull final String key, @NonNull final GetDataInSecureStore listener); boolean contains(@NonNull final String key); }
If you haven't provided access to your Secured Store and the device lock is also disabled, contact Zeta for assistance.
Step 4: Configure the SDK
You can configure the SDK by providing the implementation for the following Cipher service APIs based on your requirement:
Authenticate the SDK
To perform authentication, you must provide the authentication token to the SDK. Use the following API to create an authentication toke n. To know how to generate an authentication token, see SDK Authentication.
authenticate(tenantToken: String) - Returns void
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.
This API tells if the SDK needs a Secured Store setup. Only after this step, the SDK will be able to set up the Swipe to Pay and Super PIN.
isSecureStoreSetupRequired() - Return boolean
- Call setupSecuredStore()
A call to the API
setupSecuredStore()
triggers the setup of Secured Store. Ensure you callsetupSecureStore()
to set up the Secured Store only whenisSecureStoreSetupRequired
returns true. If the API returns an exception in the listener, call Logout() before retrying.
setupSecuredStore(activity: Activity, listener: SecureStoreSetupListener) - Returns void
Generate Super PIN
If a call to isSuperPinSetupDone()
API returns true, you can generate a Super PIN to secure the store by triggering setupSuperPin(listener: SetupSuperPinListener)
API.
- Check the state of Cipher SDK.
This API tells if the Super PIN setup is done or not. 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. You can get the error state using the
superPinExceptionListener
in CipherService instance.isSuperPinSetupDone() - Returns boolean
Set up the Super PIN
A call to this API creates a Super PIN. The Super PIN can be setup only when CipherSerivce.isSuperPinSetupRequired() returns true. If this setup fails and issue persists, contact Zeta.setupSuperPin(listener: SetupSuperPinListener)
- Retrieve the Super PIN
This API returns the Super PIN and it’s Time To Live (TTL) on providing authentication to the Secured Store or device lock. Use this Super PIN to authorize the payment.
getSuperPin(GetSuperPinListener listener)
Set up a parent activity
Set the parent activity on top of which we want to show the Super PIN or device lock. This option should be used when the Secured Store is setup using the SDK.
setParentActivityForAuth(Activity activity)
Adding 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.
Use this method is used to subscribe to SDK state updates.
setCipherStateUpdateListener(listener: CipherStateUpdateListener)
This method is deprecated and no longer advised to be used. Instead use the the listeners in the different methods.
Step 5: 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:
if(cipherService.isSecureStoreSetupRequired()) { // You are now ready to setup the secure store as instructed by the AppSecuredStoreAccess } else if(cipherService.isSuperPinSetupRequired()){ // You are ready to call setupSuperPin() } else if(cipherService.isSuperPinSetupDone()){ // You are ready to trigger getSuperPin() API }
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:
cipherService.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 exceptions that Cipher SDK can throw:
SdkAuthException
CardsSdkException
All the exception classes extend the ApolloException
.
The sample error response below shows server-side error code and message returned in case of any error:
apollo@console$ in.zeta.apollo.sdkauth.SdkAuthException: The tenantAuthToken token set seems invalid. Please check the parameters and signature to create the token SdkAuthException.code: SDKAUTH_ERR_001
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. |
ERR_002 | Internal server error. Try again. |
ERR_003 | Internal SDK error. Try logging out and then log in. |
SDKAUTH_ERR_001 | Following are the potential reasons for failure of an authentication token:
|
SDKAUTH_ERR_002 | Internal error caused while trying to authenticate the user. |
CIPHERSDK_ERR_001 | Error occurred when user cancels the Secured Store setup. |
To know more about exceptions and error codes handling, contact Zeta.
- No labels