Get Started with PhoneCheck on Android

Get Started with Android

This Guide will walk you through performing your first PhoneCheck within an Android application using a Node.js server. It covers:

The final simplified application structure looks as follows:

├── app-example-android
│   └── app
│      └──
└── phonecheck-server
└── tru.json

And the running Android application looks and works as follows:

phone device wrapper

For more detailed information on how the Android application, the Node.js server and the tru.ID APIs work together see the PhoneCheck integration guide.

1. Before you begin

To run the example Android application you will need a mobile phone running Android Lollipop (Android 5.0) or above and an active SIM card with mobile data access. You'll also need Android Studio or the Android commandline tools.

To expose the locally running Node.js server to the running Android application you'll require a local tunnel solution such as ngrok.

To run through the guide as a whole you'll need a tru.ID account. If you don't already have an account, sign up now.The tru.ID tooling relies on the Node.js runtime. So please ensure you have the Node.js runtime installed.

Install and setup the tru.ID CLI

With Node.js install the tru.ID CLI (Command Line Interface) from your terminal.
$ npm install -g @tru_id/cli
After the installation you should setup the CLI with your tru.ID Default Credentials. These can be found within the tru.ID Console.
$ tru setup:credentials {YOUR_CLIENT_ID} {YOUR_CLIENT_SECRET} EU

Create a working directory

Create a directory that you will add the client and server example code to:

$ mkdir tru-id-phonecheck-example

And navigate into that directory:

$ cd tru-id-phonecheck-example

2. Setup the Node.js example server

The Node.js example server is used as an authority and sits between the Android application and the tru.ID APIs.

Clone the Node.js Server Example

Clone the tru.ID Node.js example server into thephonecheck-server directory:

$ git clone phonecheck-server

Create a tru.ID project

Create a new tru.ID project and save the configuration to the phonecheck-server directory:

$ tru projects:create "phonecheck-server" --project-dir=phonecheck-server

You will see output similar to the following:

Creating Project "phonecheck-server"
Project configuration saved to "path_to/tru-id-phonecheck-example/phonecheck-server/tru.json"

The Node.js application will read your credentials from the tru.json project configuration file.

Run the tru.ID example server

Navigate into the phonecheck-server directory:

$ cd phonecheck-server

Install the application dependencies:

$ npm install

Run the application:

$ npm start

You will see output similar to the following indicating that the server application is running at http://localhost:8080:

> tru-node-server@0.1.0 start
> nodemon src/index.js
[nodemon] 2.0.4
[nodemon] to restart at any time, enter 'rs'
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting 'node src/index.js'
project_id: '0055f3a3-6e06-4390-9048-4f5a9dfcbbd1',
name: 'phonecheck-server',
credentials: [
client_id: 'PROJECT_CLIENT_ID',
client_secret: 'PROJECT_CLIENT_SECRET',
created_at: '2021-01-11T15:44:14+0000',
scopes: [Array]
mode: 'live',
created_at: '2021-01-11T15:44:14+0000'
Example app listening at http://localhost:8080

Create a local tunnel for your server

In order for your mobile application to be able to interact with the locally running server you'll need to setup a local tunnel. For this example we'll use ngrok.

Run `ngrok` to create a local tunnel and to get a public URL which will be used in the mobile application configuration. Run the following command in a new terminal window:

$ ngrok http 8080

You will then see output similar to the following:

Session Status online
Account Phil Leggetter (Plan: Pro)
Version 2.3.35
Region United States (us)
Web Interface
Forwarding -> http://localhost:8080
Forwarding -> http://localhost:8080
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00

Navigate to your ngrok HTTPS URL to ensure the server is accessible ( from the above output).

3. Setup the Android example application

With the server running you can now setup and run the Android 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

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

$ cd app-example-android

Create a copy of the app/ file, naming the new file app/

$ cp app/ app/

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


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.

4. Perform a PhoneCheck 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:

phone device wrapper

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

5. Resources

6. 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 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.
Made withacross the 🌍
© 2021 4Auth Limited. All rights reserved. tru.ID is the trading name of 4Auth Limited.