Switch to dark theme

Switch to light theme

Adding the SDK to your App


About Fusion
Published on 25th March, 2021

Please follow the steps below to successfully complete this step

1. Accessing the SDK

We host all our SDKs on a remotely accessible Maven repository.

Gradle understands the semantics of a maven repository and can download the SDK artefacts AAR files from the remotely hosted repository.

Add the following lines of code to your project level build.gradle file

Project level

Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
allprojects {
    repositories {
        ....
        maven {
            credentials  {
                username = "<usename>"
                password = "<password>"
            }
            url 'https://apollo-sdk.zetaapps.in/repository/maven-releases/'
            authentication {
                basic(BasicAuthentication)
            }
        }
        maven {
            credentials  {
                username = "<username>"
                password = "<password>"
            }
            url 'https://apollo-sdk.zetaapps.in/repository/maven-snapshots/'
            authentication {
                basic(BasicAuthentication)
            }
        }

        ....        
    }
}
Code Copied

2. Adding the SDK to your app

Add the dependency for Cards SDK to your application level build.gradle file

Application level

Switch Theme
Expand More
Copy
1
2
3
4
5
dependencies {
    ............
    implementation 'in.zeta.apollo:cards:<latest-version>'
    .............
}
Code Copied

Add the following Kotlin JVM target to your app if you are using Kotlin as your programming language

JVM Target

Switch Theme
Expand More
Copy
1
2
3
4
5
6
7
android {
  ........
  kotlin_options = {
         jvmTarget = "1.8"
      	}
  .......
}
Code Copied

[Optional] Custom packaging options can be added with the following lines of code, if you face issues with packaging

Custom packaging

Switch Theme
Expand More
Copy
1
2
3
4
5
6
7
8
android {
..........
  packagingOptions {
     exclude 'META-INF/library_release.kotlin_module'
     exclude 'META-INF/DEPENDENCIES'
  }
.......
}
Code Copied

3. Adding permissions to Manifest

The following permissions need to be added in your Apps AndroidManifest.xml file to get the network state and take actions accordingly.

Permissions

Switch Theme
Expand More
Copy
1
2
3
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
Code Copied

4. Adding config files

Add the Supercards.json file that you received from Zeta to your app/src/main/assets folder. Shown below is what a sample file looks like, please ensure that you have your own file from Zeta for this step.

Adding config

Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
 "tenantId": <tenantId>,
 "projectId": <projectId>,
 "appId": "<appId>",
 "sdkName": "<sdkName>",
 "platform": "android",
 "sdkVersion": "<latestSdkVersion>",
 "sdkConfigVersion": "<configVersion>",
 "sdkConfigCollectionId": "<sdkConfigCollectionId>",
 "sdkConfigItemId": "<sdkCOnfigItem>",
 "authId": "<authId>",
 "apiKey": "<apiKey>",
 "sdkAuthBaseUrl": "<baseUrl>",
 "cardsApiBaseUrl": "<baseUrl>",
 "omsBaseUrl": "<baseUrl>",
 "apolloUserBaseUrl": "<baseUrl>",
 "ifiTenantId": <ifiTenantId>,
………………………
}
Code Copied

5. Adding theme & template files

Cards SDK is capable of allowing you to define the theme & layout that is in use. These can be edited remotely on the fly, so you don’t have to release a new build if you decide to change the way your views look.

To deal with first time initializations it’s preferable to release a build along with a local copy of the files that define the views within your App.

You would have received 2 files from Zeta, that are named in the format shown below

  • scopeID.<id>.templates
  • scopeID.<id>.theme_config

Add these files to app/src/main/assets/collections in your projects hierarchy. (Add the collections folder if you haven’t already)

Once you’ve successfully added the files, your project structure should look like this

6. Adding font files

To use a unified font across your app and give a good user experience, you can add your font files in the app/src/main/assets/fonts folder of your project.

Font files can be provided in either of the following formats

  • ttf
  • otf

Once you’ve successfully added the files, your project structure should look like this

Instantiate the SDK


After completing the steps mentioned in Preparing the environment and Adding the Cards SDK to your App, you are now ready to create an instance of CardsService to instantiate the SDK.

Add the following piece of code to your Apps main Application class (create one if you haven’t already)

Builder Methods

Switch Theme
Expand More
Copy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
 "tenantId": <tenantId>,
 "projectId": <projectId>,
 "appId": "<appId>",
 "sdkName": "<sdkName>",
 "platform": "android",
 "sdkVersion": "<latestSdkVersion>",
 "sdkConfigVersion": "<configVersion>",
 "sdkConfigCollectionId": "<sdkConfigCollectionId>",
 "sdkConfigItemId": "<sdkCOnfigItem>",
 "authId": "<authId>",
 "apiKey": "<apiKey>",
 "sdkAuthBaseUrl": "<baseUrl>",
 "cardsApiBaseUrl": "<baseUrl>",
 "omsBaseUrl": "<baseUrl>",
 "apolloUserBaseUrl": "<baseUrl>",
 "ifiTenantId": <ifiTenantId>,
………………………
}
Code Copied

setAppDisplayName

  • Pass the String resource for your application name. We show this String over the device lock screen when the user is asked to provide authentication.

  • Note: This is a necessary field

setUseDeviceLock

  • Enable/Disable device lock when asking for user authentication.

  • This is set as true by default.

  • If set to false or the device does not already have a lock mechanism enabled, a custom PIN setup will commence when the setupSdk() method is called.

setFontMap

  • Create a font map and set it to the builder. The Cards SDK will then use the fonts mentioned while rendering any of its views. The file names here refer to the files that you have inside your assets folder.

  • Note: You can invoke CardsServiceBuilder(..) only once per app session. To get an instance of CardsService anywhere in your application, use the following code snippet.

Creating an instance

Switch Theme
Expand More
Copy
1
   final CardsService cardsService = CardsService.getInstance();
Code Copied

  • Note: It is recommended to create the CardsService instance as the first step when the app is launched. You can do it inside your Application class.

Steps to authenticate the SDK


Please follow the steps below to successfully authenticate your SDK

About

You can authenticate the Cards SDK by invoking the authenticateSdk() function. This function expects a JWT token referred to as tenantAuthToken in subsequent sections. The tenantAuthToken contains the account holder ID in the issuer’s domain as the “claim” of the JWT token.

The tenantAuthToken needs to be computed in your backend as it needs access to sensitive information while token creation. The information used to generate the tenantAuthToken should never be compromised. More information on how to generate the tenantAuthToken can be found in this section.

As and when the user logs in to the App, your App should fetch the tenantAuthToken from your backend service. This is a one time activity and can be clubbed with the login flow of the App.

Why authenticate cards SDK

Once the user has logged in to the app, you already have a session for the logged in user. The reason why you need to separately authenticate the Cards SDK is for the issuers domain. Through the process of SDK Authentication you will authenticate your user in the issuers domain as a valid account holder ID.

Validity of tenantAuthToken

The validity of the tenantAuthToken can be kept the same as the validity of the logged in user of the App. Once the App has fetched the tenantAuthToken it should initiate the SDK Authentication flow as suggested in the code snippet below :

Authentication

Switch Theme
Expand More
Copy
1
2
final String tenantAuthToken = myBackendService.issueAuthToken(userInfo);
CardsService.getInstance().authenticateSDK(tenantAuthToken, accountHolderId);
Code Copied

This is a one time activity and should be only done along with the login flow of the App.

Steps to set the SDK up


Please follow the steps below to successfully setup your SDK

About

  • This step triggers the actual setting up of the SDK. Once this step iscompleted, the SDK will initiate background sync of the card details of the user. One critical step is setting up the secureStore on the App. SecureStore refers to the encrypted storage which is behind the device lock or custom App PIN authentication step.

  • For secureStore, the SDK always prefers device lock over custom App pin authentication. Setting up a secureStore may require the user to provide device lock authentication. In case of custom app pin authentication, it may require the user to set up the app pin or provide the app pin.

  • Note: The first invocation of the setupSDK function call may require user intervention. Subsequent invocation will not require any user intervention.

When to call setUpSdk()

  • setUpSdk() call should be made on every launch of the App On first launch the setUpSdk() could be a part of the onboarding flow of the App i.e. The time when it is appropriate for the App to setup the device lock authentication. Nonetheless, it should always be called after the authenticateSdk() step has completed.

  • On subsequent launches of the App, it should be called as early as possible. You can invoke it inside the onCreate() method of the launching activity of your App.

  • Under the hood, the setupSDK() function triggers the SDK to set up secure storage.

  • On first launch, the secure storage is actually set up, while in the subsequent launches, since the setup is already done, it simply does nothing and returns success.

  • Once the secure storage is set up, it triggers the SDK to sync the card details of the user in the background. Once the card details are fetched, the SDK needs to persist it in the secure storage for subsequent offline access. The SDK will do the “persist to secure storage” operation in the background only if the secure storage is “unlocked”. This is often the case during the first launch since it has been just set up and it is left unlocked. But in subsequent launches, this may not be the case. The SDK will never initiate unlocking the secure storage unless explicitly asked by the mobile app. For this purpose, the SdkInitListener will fire an event “Secure_Storage_Unlock_Required” to let the mobile app know of such a need. At this stage, the mobile app may, whenever it feels appropriate, invoke the SDK function - triggerSecureStorageUnlock. This will let the SDK trigger secure storage unlock. This will require user intervention. Post unlock, the SDK will persist the card details to the secure storage.

  • Note: In most of the cases, it is sufficient to sync the cards details only during the first launch. Subsequent background sync results in no further data. But for scenarios where either the sync fails after the first launch or new card is added for the user, the background sync may result in newer data to be persisted to the secure storage.

SdkInitListener

  • The setupSDK function takes as input a listener which provides regular updates about the status of the SDK setup. Listen to the listener for success & once done, you can now access the Cards SDK APIs & features.