Get Started with SubscriberCheck on Android

This guide walks you through what is required on your Android app in order to perform a SubscriberCheck using tru.ID's Android SDK. However, if you wish to see the finished working example app, you can find it on our GitHub respository. It covers:

1. Before You Begin

To fully understand the functionality required to create a SubscriberCheck in this guide, you will need to carry out some initial steps, such as creating an account, a project, and retrieving your workspace credentials. You'll also need to have an understanding of the workflow for a SubscriberCheck to be successfully carried out.

The first step is to Setup Your Environment. This page walks you through what parts are required, such as installing the tru.ID CLI, creating a project, and if needed, running the demo development server.

The second step is to gain more of an understanding of how the SubscriberCheck works. The Integration Guide provides a step by step guide on the workflow of a SubscriberCheck, and which devices need to act at what points of the workflow.

2. Install tru.ID Android SDK

The tru.ID Android SDK requires a minimum API level of 21 (Android 5), and a compile level needs to be API 30 (Android 11) or later.

In the project's Android directory, open the build.gradle file, add the tru.ID's Android SDK public repository within the buildscript and allprojects repository sections, similar to what's shown below:

buildscript {
    repositories {
      ...
      maven {
        url "https://gitlab.com/api/v4/projects/22035475/packages/maven"
      }
    }
    ...
}

allprojects {
    repositories {
        ...
        maven {
            url "https://gitlab.com/api/v4/projects/22035475/packages/maven"
        }
    }
}

Next, within your Module's build.gradle add the dependencies required:

implementation 'id.tru.sdk:tru-sdk-android:0.3.2'
implementation 'commons-io:commons-io:2.4'

3. How to implement into my app?

Importing and Initializing the SDK

Before proceeding, be sure to sync your project for these new dependencies to be installed.

Initialize tru.ID SDK

TruSDK.initializeSdk(applicationContext)

Define an instance of the tru.ID SDK:

val truSdk = TruSDK.getInstance()

Reachability

The Reachability API is a feature that enables applications to check whether the SIM card within a user's device is on a network that tru.ID has connectivity to.

The Flutter SDK has functionality built in to call the reachability, to call this you would need to run the following code:

truSdk.isReachable()

If the mobile network operator is supported by tru.ID then a JSON object is returned similar to the example below:

{
  "network_id": "23410",
  "network_name": "O2 UK",
  "country_code": "GB",
  "products": [
    {
      "product_id": "SCK",
      "product_name": "SubscriberCheck"
    }
  ]
}

However, if it isn't supported, then an error is returned in JSON format.

Call your backend server to create SubscriberCheck

As described in the Integration guide step 1 is to create a SubscriberCheck. This step is a step where your mobile application needs to call your backend server with the mobile devices telephone number. Your backend server then makes a POST request to tru.ID's SubscriberCheck API. If successful, the SubscriberCheck API will return a response with the check_id and a unique check_url. Your backend server needs to return this check_url to the mobile device.

Open Check URL to process SubscriberCheck

Step 2 of the integration guide is to process the SubscriberCheck. This step is a step where the mobile application makes a GET request to the check_url provided in the previous step. The mobile device application then needs to follow all redirects, then on the last redirect, the JSON response will contain a code. This code will be used next.

truSdk.checkUrlWithResponseBody(check_url)

Call Backend server to complete SubscriberCheck

Step 3 of the integration guide is to complete the SubscriberCheck. This step is a step where the mobile application makes a POST request to your backend server with the check_id and the code. Your backend server then makes a PATCH request to /subscriber_check/v0.2/checks/{check_id} with the JSON body below to complete the SubscriberCheck process:

[
  {
    "op": "add",
    "path": "/code",
    "value": "{check_code}"
  }
]

info

Within the response of this PATCH request, there will be a field no_sim_change, this is the field used to show if the SIM card has been changed recently, which could be an indication whether the owner of the SIM card may be a victim of SIM swap fraud. If the value is true, then proceed with the SubscriberCheck.

Finally, your backend server would need to return a success or failure response to your mobile application to allow the user of this application to proceed.

4. Setup the Android example application

Clone and configure the Android example application

Open a new terminal and ensure you are in the tru-id-phonecheck-example working directory. Run the following command to clone the Android example into a app-example-android directory:

git clone git@github.com:tru-ID/app-example-android.git

And navigate into the newly created app-example-android directory:

cd app-example-android

Create a copy of the app/tru.properties.example file, naming the new file app/tru.properties:

cp app/tru.properties.example app/tru.properties

And update the configuration value for EXAMPLE_SERVER_BASE_URL in app/tru.properties to point to the public ngrok URL of the Node.js example server. For example:

EXAMPLE_SERVER_BASE_URL=https://d88e00a17e1c.ngrok.io

Install and run the Android Example app

Ensure your Android device is connected to your computer via USB with developer mode and USB debugging enabled.

Using Android Studio

You can then install and run the Android example from Android Studio by opening the project using File -> Open and navigating to tru-id-phonecheck-example/app-example-android and then selecting Run -> Run 'app' from the application menu.

Using the commandline tools

Or you can run the following from the terminal to install the Android sample application:

./gradlew installDebug

You will see output similar to the following:

> Task :app:installDebug
Installing APK 'app-debug.apk' on 'Pixel 5 - 11' for app:debug
Installed on 1 device.

And then launch the application called Sample on the Android device.

5. Perform a SubscriberCheck on Android

Enter your phone number with the + and country code and click "Verify my phone number". The application will look similar to the following:

With that, you've completed your first SubscriberCheck from an Android application.

6. Resources

7. Troubleshooting

`INSTALL_FAILED_USER_RESTRICTED` when running `./gradlew installDebug`

See this Stackoverflow answer
You may also want to enable the "Stay awake" (Screen will never sleep while charging) option within "Developer options" to ensure the Android device is detected when installing the sample application.

Android app only gets to the "Validating Phone Number input" setup

It's likely that an error has occured but the UI isn't providing any feedback. We're working on updating the sample application to provide better error feedback.

For now, check the following:

Ensure that your tru.properties is correctly set to point to your HTTP ngrok URL
Take a look at the output from your Node.js server to see if there has been an error within the server or interacting with the tru.ID API.