Android SDK Setup

Published on 26th Aug, 2021

Before starting the set up, Please download the SDK via App center.

Add the Cards Sdk to your app

To your module (app-level) Gradle file (usually app/build.gradle), add the dependency for the cards SDK

Sample Code

1
2
3
4
5


dependencies {
    ............
    implementation 'in.zeta.apollo:cards:<latest-version>'
    .............
}

Code Copied

Add kotlin JVM target to your if you are using Kotlin as your programming language

Sample Code

1
2
3
4
5
6
7


android {
  ........
  kotlin_options = {
         jvmTarget = "1.8"
  }
  .......
}

Code Copied

Custom packaging options if you face issues with packaging:

Sample Code

1
2
3
4
5
6
7
8


android {
..........
  packagingOptions {
     exclude 'META-INF/library_release.kotlin_module'
     exclude 'META-INF/DEPENDENCIES'
  }
.......
}

Code Copied

Enable data-binding by adding the following lines to the app-level build.gradle

Sample Code

1
2
3
4
5


android {
    dataBinding {
        enabled = true
    }
}

Code Copied

Add the following permissions to your AndroidManifest.xml file

Sample Code

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

Enable multi-dex by adding the following lines to the app-level build.gradle file

Sample Code

1
2
3
4
5


android {
  defaultConfig {
    multiDexEnabled true
  }
}

Code Copied

Add the font files to your project

To use the fonts the same as your app and give the user a similar experience, you should add your font files in the app/src/main/assets/fonts folder of your project. You can provide font files in either ttf or otf formats. Font files once added would like as follows with the Project view in Android Studio:

Instantiating Cards SDK

Once you have completed the Setup for the SDK, you are now ready to create an instance of CardsService. Add the following code to your app’s Application class (Create a one if you haven’t yet). Inside your Application class, add the following code.

Java

 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
28
29
30
31
32
33
34
35
36
37


private static final String IBXPLEXSANS_REGULAR_FONT_PATH = "fonts/IBMPlexSans-Regular.otf";
private static final String IBXPLEXSANS_MEDIUM_FONT_PATH = "fonts/IBMPlexSans-Medium.otf";
private static final String IBXPLEXSANS_SEMI_BOLD_FONT_PATH = "fonts/IBMPlexSans-SemiBold.otf";
private static final String IBXPLEXSANS_BOLD_FONT_PATH = "fonts/IBMPlexSans-Bold.otf";
private static final String OCRA_STD_FONT_PATH = "fonts/OCRAStd.otf";

private static final Map<String, String> fontMap = new HashMap<>();

static {
   fontMap.put("IBMPlexSans-Regular".toLowerCase(), IBXPLEXSANS_REGULAR_FONT_PATH);
   fontMap.put("IBMPlexSans-Medium".toLowerCase(), IBXPLEXSANS_MEDIUM_FONT_PATH);
   fontMap.put("IBMPlexSans-SemiBold".toLowerCase(), IBXPLEXSANS_SEMI_BOLD_FONT_PATH);
   fontMap.put("IBMPlexSans-Bold".toLowerCase(), IBXPLEXSANS_BOLD_FONT_PATH);
   fontMap.put("OCRAStd".toLowerCase(), OCRA_STD_FONT_PATH);
}

@Override
public void onCreate() {
   super.onCreate();

   setupCardsSdk();
}

private void setupCardsSdk() {
   new CardsServiceBuilder(this)
           .setLoggingEnabled(true)
           .setSecuredStoreTitle(R.string.title)
           .setSecuredStoreSubtitle(R.string.subtitle)
           .setFontMap(fontMap)
           .useDoor()
           .build();



   // Can get the CardsService instance once it is built.
   cardsService = CardsService.getInstance();
}

Code Copied

Kotlin

 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
28
29
30
31
32
33
34


private val IBMPLEXSANS_REGULAR_FONT_PATH = "fonts/IBMPlexSans-Regular.otf"
private val IBMPLEXSANS_MEDIUM_FONT_PATH = "fonts/IBMPlexSans-Medium.otf"
private val IBMPLEXSANS_SEMI_BOLD_FONT_PATH = "fonts/IBMPlexSans-Semibold.otf"
private val IBMPLEXSANS_BOLD_FONT_PATH = "fonts/IBMPlexSans-Bold.otf"
private val OCRA_STD_FONT_PATH = "fonts/OCRAStd.otf"

private val fontMap: MutableMap<String, String> = HashMap()

init {
   fontMap["IBMPlexSans-Regular".toLowerCase()] = IBMPLEXSANS_REGULAR_FONT_PATH
   fontMap["IBMPlexSans-Medium".toLowerCase()] = IBMPLEXSANS_MEDIUM_FONT_PATH
   fontMap["IBMPlexSans-Semibold".toLowerCase()] = IBMPLEXSANS_SEMI_BOLD_FONT_PATH
   fontMap["IBMPlexSans-Bold".toLowerCase()] = IBMPLEXSANS_BOLD_FONT_PATH
   fontMap["OCRAStd".toLowerCase()] = OCRA_STD_FONT_PATH
}

override fun onCreate() {
   super.onCreate()
   setupCardsSdk()
}

private fun setupCardsSdk() {
   CardsServiceBuilder(this)
       .setLoggingEnabled(true)
       .setSecuredStoreTitle(R.string.title)
       .setSecuredStoreSubtitle(R.string.subtitle)
       .setFontMap(fontMap)
       .useDoor()
       .build()


   // Can get the CardsService instance once it is built.
   val cardsService = CardsService.getInstance()
}

Code Copied

Following is the description of each of the builder methods

setSecuredStoreTitle
- Pass the string resource for your application name. We use this to show over the device lock screen when asked for user authentication.

Note: This is a necessary field. An exception is thrown if this is not provided.

setSecuredStoreSubtitle
- Pass the string resource for your sub-title you may want to show on the device lock screen.

Note: This is a necessary field. An exception is thrown if this is not provided.

setFontMap
- Create a font map and set it to the builder. The card SDK will, then, use the mentioned fonts while rendering the views offered by the SDK. The file names here refer to the files that you had put inside the 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.

Java

1

final CardsService cardsService = CardsService.getInstance();

Code Copied

Kotlin

1

val cardsService = CardsService.getInstance()

Code Copied

Authenticating Cards SDK

For a user of your app to be able to use the cards SDK through your app, you need to authenticate the user with the tenantAuthToken. The tenantAuthToken needs to be computed in your backend as it needs sensitive information to create the token. The information used to generate the tenantAuthToken should never be compromised.

Set the tenantAuthToken to the cards SDK once the user logs into your app and you have sufficient information to issue a tenantAuthToken for the user. Following is the code snippet on how to authenticate the SDK:

Java

1
2


final String tenantAuthToken = myBackendService.issueAuthToken(userInfo);
CardsService.getInstance().authenticateSDK(tenantAuthToken, accountHolderId);

Code Copied

Kotlin

1
2


val tenantAuthToken: String = myBackendService.issueAuthToken(userInfo)
CardsService.getInstance().authenticateSDK(tenantAuthToken, accountHolderId)

Code Copied

Note: This step has to be performed in a fresh log-in of the user or when the earlier provided tenantAuthToken expires. Note: A tenantAuthToken has an associated validity with it. The ideal practice is to reset a new token before it expires.

Setting up the SDK

This step triggers the actual setting up of the Cards SDK. Once this step is completed, the SDK will initiate background sync of the card details of the user. One critical step is setting up the secure storage on the mobile app. Secure Storage refers to the encrypted storage which is behind device lock or custom app pin authentication.

For secure storage, the SDK always prefers device lock over custom app pin authentication. Setting up secure storage 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. The first invocation of the setupSDK function call may require user intervention. Subsequent invocation will not require any user intervention.

This step has to be performed on every launch of the app (post the authentication of the SDK). You can perform this inside the onCreate() method of your launching activity.

Java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Override
protected void onCreate(Bundle savedInstanceState) {
   super.onCreate(savedInstanceState);
   setContentView(R.layout.activity_main);

   CardsService.SdkInitListener sdkInitListener = (success, exp) -> {
       // Handle the response here ...
   };
   CardsService.getInstance().setupSDK(this, sdkInitListener, null, null);

   setupView();
}

Code Copied

Kotlin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


override fun onCreate(savedInstanceState: Bundle?, persistentState: PersistableBundle?) {
   super.onCreate(savedInstanceState, persistentState)
   setContentView(R.layout.activity_main)

   val sdkInitListener = object: CardsService.SdkInitListener {
       override fun done(success: Boolean, exp: Throwable?) {
           // Handling of success/failure goes here.
       }
   }
   getInstance().setupSDK(this, sdkInitListener, null, null)

   setupView()
}

Code Copied

Listen to the listener for success. You can access the Cards SDK APIs

Choose your product

Choose your product

Android SDK Setup

Add the Cards Sdk to your app

Add the font files to your project

Instantiating Cards SDK

Authenticating Cards SDK

Setting up the SDK

Was this article helpful?