App Verify Android SDK

❗️

WARNING

This SDK is deprecated.

The App Verify Android SDK integrates a frictionless user verification process into existing native Android applications. It allows mobile applications for Android to use Telesign's proprietary auto verification service to verify an end user's device and phone number without embedding the authentication credentials in the application where they can be easily hacked and taken. The service securely sends a voice call to the end user's device and automatically verifies the number.

📘

NOTE:

A JSON Web Token (JWT) server is required to use App Verify. For details about how to create a JWT service, refer to App Verify - Tutorial: Implement a JWT Service.

Supported versions

The App Verify Android SDK supports Android API 16-25 (JellyBean to Nougat). Refer to the Android website for additional information.

How it works

The following diagram illustrates the verification process flow between your mobile application, your server, and Telesign's server:

The app verification process as depicted in the diagram works like this:

1. Open app and input phone number - Open the application and input the phone number. (The end user must input a phone number in order for a JWT token to be fetched.)

2. Start verification with phone number and JWT - When an end user opens your application, after they enter their phone number, the application obtains a security token from your JWT service. Your application initializes verification by contacting the Telesign server with the end user's phone number and the security token.

3. Voice call with code - The Telesign server calls the end user's phone with a short-duration verification call. This call will vibrate the phone for a short pulse (if the vibrate permission is enabled), and the end user might see the caller ID briefly. The end user cannot respond to or cancel this call. The call has a predefined caller ID containing a randomly generated verification code.

📘

NOTE:

The sample app waterfalls from AutoVoice to SMS Retriever to AutoSMS in order to showcase all available features. You may choose a different configuration depending on your needs.

4. Auto consume - The App Verify Android SDK automatically consumes and processes the incoming call to read the embedded verification code and verify the phone number.

5. Finalize verification with code - Telesign compares the verification code that it generated for the call with the verification code that your application sent back to determine whether they match.

6. Claim verified - Your application makes a claim to your network server that TeleSign verified the transaction.

7. Confirm verified - Your application obtains the verification status in either of the following ways. After your application confirms verification, your server can approve an end user's transaction or create a user account. Using the Get Status approach, your application makes a request to the Get Status Service.

What's in the App Verify Android repository on GitHub?

The App Verify Android GitHub repository contains the following components:

• App Verify Android SDK
• Sample App Verify application
• Sample JWT service - A JWT service is required for using App Verify. Telesign provides a sample JWT service for testing purposes. For more information, see App Verify - Tutorial: JWT Service for App Verify.

🚧

CAUTION

This repository is no longer publicly shared since this SDK is deprecated. If you are an existing customer with this product and need access to the repository, contact our Customer Support Team.

Requirements

Before using the App Verify Android SDK in an application, your application must meet the following requirements:

• minSdkVersion of 16
• Appropriate permissions - See Required permissions
• Your Telesign Customer ID and API key (used for authentication)
• JWT service - For instructions about how to set up your JWT service, refer to the App Verify - Tutorial: JWT Service for App Verify page.

📘

NOTE:

Implementing a JWT service is a critical step. Without a JWT service, client applications cannot authenticate with Telesign services used by the SDK.

Obtaining verification status

This section describes the methods available to obtain verification status.

When you implement the verification process in your application, you must check the status of each transaction with Telesign. There are two ways to do this, with the Transaction Callback Service or with the Get Status service.

📘

NOTE:

The Transaction Callback Service and Get Status options are not App Verify SDK functionality in your application, but rather REST API requests made on the back end, between your server and the TeleSign server. For example, using Verify Transaction Callback, when the auto verification service determines a successful verification result, the TeleSign server sends a callback to your server to notify the client app of the verification transaction status.

Verify with the Get Status Service

In this scenario, you have the option to request verification results from TeleSign using the Get Status service. You can retrieve verification results within the 12-hour period following each instance of a verification request by sending a GET request to the URL noted in Get Status Service.

Verify with the Verify Transaction Callback Service

In this scenario, when TeleSign verifies your application's user, it makes a callback request to a web service that you have set up. In order to use the callback service, you must first set up a web service and provide the URL to TeleSign support. Support then configures it in the TeleSign system. TeleSign then makes a server-to-server callback to notify your service of the status of the verification transaction. For more information, see Verify Transaction Callback Service.

Get Status Service

TeleSign provides the option for you to retrieve verification status using the Get Status REST API.

Service Endpoint

The URL for issuing HTTP GET requests for the Get Status web service is:

https://rest-api.telesign.com/v1/mobile/verification/status/[xid]

After you make a verification request, retrieve the verification results by sending an HTTP request with an XID identifier for the original service request.

TeleSign's web server processes REST API requests, then returns the results formatted as a JavaScript Object Notation (JSON) response in the entity-body of an HTTP response message.

Get Status by SDK

You can use a TeleSign SDK to perform Get Status requests, and Get Status code samples are available.

Choose your language:

• Node.js
• Java
• Python
• Ruby
• PHP
• C#

The code sample for using Get Status looks like this:

var TeleSignSDK = require('telesignsdk');

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
const apiKey = "ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
const rest_endpoint = "https://rest-ww.telesign.com"; 
const timeout = 10*1000; // 10 secs
const EXTERNAL_ID = "external_id";

const client = new TeleSignSDK( customerId,
    apiKey,
    rest_endpoint,
    timeout // optional
    // userAgent
);

function statusCallback(error, responseBody) {
    if (error === null) {
        console.log(`App verify transaction for External ID: ${EXTERNAL_ID}` +
            ` => code: ${responseBody['status']['code']}` +
            `, description: ${responseBody['status']['description']}`);
    } else {
        console.error("Unable to perform status for the given externalID. " + error);
    }
}

console.log("## AppVerifyClient.status ##");

client.appverify.status(statusCallback, EXTERNAL_ID);

package com.telesign.example.appverify;

import com.telesign.AppVerifyClient;
import com.telesign.RestClient;

public class GetStatusByExternalId {

    public static void main(String[] args) {

        String customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
        String apiKey = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
				String restEndpoint = "https://rest-ww.telesign.com";
        String externalId = "external_id";

        try {
            AppVerifyClient autoverifyClient = new AppVerifyClient(customerId, apiKey, restEndpoint);
            RestClient.TelesignResponse telesignResponse = appverifyClient.status(externalId, null);

            if (telesignResponse.ok) {
                System.out.println(String.format("AppVerify transaction with external_id %s has status code %s and status description %s.",
                        externalId,
                        telesignResponse.json.getAsJsonObject("status").get("code").getAsString(),
                        telesignResponse.json.getAsJsonObject("status").get("description").getAsString()));
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

from __future__ import print_function
from telesign.appverify import AppVerifyClient

customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

external_id = "external_id"

appverify = AppVerifyClient(customer_id, api_key, rest_endpoint="https://rest-ww.telesign.com")
response = appverify.status(external_id)

if response.ok:
    print("AppVerify transaction with external_id {} has status code {} and status description {}.".format(
        external_id,
        response.json['status']['code'],
        response.json['status']['description']))

require 'telesign'

customer_id = 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890'
api_key = 'EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=='

external_id = 'external_id'

app_client = Telesign::AppVerifyClient.new(customer_id, api_key, rest_endpoint: 'https://rest-ww.telesign.com')
response = app_client.status(external_id)

if response.ok
    puts 'AppVerify transaction with external_id %s has status code %s and status description %s.' %
        [external_id,
        response.json['status']['code'],
        response.json['status']['description']]
end

<?php
require __DIR__ . "/../../vendor/autoload.php";
use telesign\sdk\autoverify\AppVerifyClient;
$customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
$api_key = "EXAMPLE----ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";
$external_id = "external_id";
$appverify = new AppVerifyClient($customer_id, $api_key, $rest_endpoint = "https://rest-ww.telesign.com");
$response = $appverify->status($external_id);
if ($response->ok) {
  printf("AppVerify transaction with external_id %s has status code %u and status description %s.",
    $external_id,
    $response->json['status']['code'],
    $response->json['status']['description']);
}

using System;

namespace Telesign.Example.AppVerify
{
    class GetStatusByExternalId
    {
        static void Main(string[] args)
        {
            string customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890";
            string apiKey = "EXAMPLEABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==";

            string externalId = "external_id";

            try
            {
                AppVerifyClient appverifyClient = new AppVerifyClient(customerId, apiKey, restEndpoint: "https://rest-ww.telesign.com");
                RestClient.TelesignResponse telesignResponse = autoverifyClient.Status(externalId);

                if (telesignResponse.OK)
                {
                    Console.WriteLine(string.Format("AppVerify transaction with external_id {0} has status code {1} and status description {2}.",
                            externalId,
                            telesignResponse.Json["status"]["code"],
                            telesignResponse.Json["status"]["description"]));
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e);
            }

            Console.WriteLine("Press any key to quit.");
            Console.ReadKey();
        }
    }
}

If you want to code everything yourself, you will need to handle authentication yourself. Refer to the section Authentication.

Sending a GET Request

After you make a verification request, retrieve the verification results by sending a GET request to the following URI with an XID identifier for the original service request:

GET /v1/mobile/verification/status/resource

The XID is the reference identifier that your JSON Web Token (JWT) service generates. This value uniquely identifies each token issued by the JWT service. For more information, see JWT Service for App Verify.

After the application completes the verification process on the server side, use the Get Status service with the xid parameter.

Sample GET Request

Request:
https://rest-api.telesign.com/v1/mobile/verification/status/[xid]

Response (JSON):

Example Get Status Response

{
   "sub_resource" : "voice_auto",
   "status" : {
       "code":1800,
       "description":"Success"
      "updated_on" : "2015-04-15T18:40:54Z",
   },
   "mobile_verification" : {
      "phone_number" : "1-310-123-4567",
      "xid" : "4325217a-742e-11e4-b116-123b93f75cba ",
   },
}

The sub_resource value is the verification method type. The status code returns one of the following statuses: 1890 (Pending), 1800 (Success), or 1803 (Failure).

Transaction Get Status data is available for 12 hours. After that, the web service returns "Not Found."

Status Codes

The following table includes status codes that can be generated by the Get Status API:

Verify Transaction Callback Service

TeleSign's App Verify Android SDK offers the Verify Transaction Callback REST API to enable your application to receive verification results. The Verify Transaction Callback API makes a server­-to-server HTTP POST callback from the TeleSign server to your service endpoint to notify your web server of a successful verification transaction.

You can read any of the verification results without using your secret key, but to confirm that the results are genuinely from TeleSign, you must process the header and verify that the signature is from TeleSign. To read more about how to do that, see the section Authenticated Callbacks from TeleSign.

📘

NOTE:

You must use standard ports in order for transaction callbacks to work properly. For HTTPS, the default standard port is 443.

Service Setup

To use the Verify Transaction Callback service:

1. Create a private URI on your web server for receiving callback notifications from TeleSign. Fields that will be sent back with the JSON formatted response include:

• Custom Authorization header (refer to section Authenticate Callbacks from TeleSign below).
• Reference ID
• Sub-Resource
• Errors
• Status: Updated On
• Status: Code
• Status: Description
• Verify: Code State
• Verify: Code Entered
• Verify: Code Submitted
• Submit Timeline

📘

NOTE:

For mission critical applications, TeleSign recommends that you provide redundancy by implementing two URIs instead of one.

2. Provide TeleSign with your private URI.

3. Allow one business day for setup to be completed.

4. You will receive callback notifications after a verification transaction completes. You can check the transaction status codes you receive in the Transaction Status Codes for Get Status and Verify Transaction Callback section.

5. If TeleSign is unable to deliver your callback notification on the first attempt, the TeleSign server waits 30 seconds, then tries again. If the second attempt fails, the server waits an additional 5 minutes and then makes a final attempt. After that, to obtain verification information, your application should resort to using the Get Status method, described above.

Authenticate Callbacks from TeleSign

If you need to set up authenticated callbacks, you must use digest authentication. You can read about digest authentication and authenticated callbacks in the Authenticated Callbacks with the Get Status / Verify Transaction API section on the Authentication page.

Callback Verification Results

TeleSign provides a JSON response to Verify Transaction Callbacks only in the case of a successful App Verify verification.

📘

NOTE:

If start/initiate fails, TeleSign does not send a callback. However, if the verification process begins, TeleSign does send a callback.

The following is a sample JSON response from a POST callback request:

JSON

{
  "status": {
    "updated_on": "2014-10-30T22:57:43.984001Z",
    "code": 1800,
    "description": "Success"
  },
  "submit_timestamp": "2014-10-30T22:57:43.612000Z",
  "errors": [],
  "sub_resource": "voice_auto",
  "mobile_verification": {
    "phone_number": "13101234567",
    "xid": "4325217a-742e-11e4-b116-123b93f75cba"
  },
  "reference_id": "B149634764BC0144C833G7280C4403B8"
}

Transaction Status Codes for Get Status and Verify Transaction Callback

Best Practices

Prompt User to Enter Phone Number of Mobile Device

TeleSign recommends that you show a message prompting end users to enter the mobile phone number of the device on which the application is downloaded and installed, not the number of another device or landline. For example, the message might read:

"Please enter the mobile phone number of the device on which this application is installed and make sure that the cellular connection is on."

You should attempt auto verification only on mobile devices capable of receiving a circuit-switched voice call. For example, if an end user downloads your app to a tablet that can perform only data traffic, auto verification will fail.

In cases where the end user does not want to provide a mobile number, you should design your application workflow appropriately to utilize other types of non-mobile verification (such as TeleSign Voice Verify or SMS Verify) to provide the user with an option for an alternate form of verification, along with an appropriate message.

Enter Country and Phone Number Separately

Your application should display the country code (or country name) and the phone number in separate input text boxes. Recommended layouts are to position the fields vertically on different lines, or to position them horizontally with a gap between them. Often when end users enter the country code and phone number in the same field, it results in mistakes such as users adding a preceding '0' or '+', or inserting a '0' between country code and phone number, as practiced in different countries.

Auto-Extraction

TeleSign recommends that your application not auto-extract phone numbers. Programmatic auto-extraction of phone numbers does not work consistently for various service providers and locales. If the auto-extraction support of phone number is provided, it is recommended that developers provide an option for the end users to edit the phone number.

The SDK includes methods that can help you auto extract your end user's phone number from their phone. Auto extraction does not work well in every country, however, it can be a nice feature to offer in your application. Auto-extraction of a phone number works reliably (80% of the time or more) in the following countries:

• Austria
• Bahrain
• Bosnia
• Canada
• Croatia
• Finland
• France
• Herzegovina
• Kuwait
• Lebanon
• Norway
• Peru
• Russia
• Singapore
• Switzerland
• Taiwan
• US
• US Virgin Islands

Notify the End User They Will Receive a Voice Call

Make sure your end user is aware that they will receive a voice call for verification purposes and that they should ignore it.

Tell Users to Omit Non-Numerals from Phone Numbers

You should instruct end users to enter their phone number without spaces, dashes, or special characters, because phone number formatting varies by country.

Best Practices for Phone Number Formatting

When you pass mobile phone numbers to the App Verify SDK, you must follow strict formatting rules for the TeleSign server to be able to verify the number. You must normalize the phone number prior to submitting it to the auto verification service.

The App Verify Android SDK accepts phone numbers in the E.164 format, which includes country codes, area codes, and phone number (number string with no spaces, dashes, and so on). For example:

• 13101234567 is normalized from 1(310)123-4567 (United States)
• 447981897555 is normalized from +44-7981-897555 (United Kingdom)

Allow the user to input the phone number.

You must normalize the phone number prior to submitting the SDK to process by doing the following:

• Use regular expressions to strip characters.
• Ensure that there are no characters, such as "," and spaces.

For more information on phone number formatting for Android, see PhoneNumberUtils in the Android Developer Reference.

TeleSign recommends that developers allow end users to input the phone number directly in the application. This is because the App Verify Android SDK does not auto extract phone numbers from mobile devices. Developers can implement this feature directly, but with the caveat that it may not work consistently across carriers and devices worldwide.

📘

NOTE:

All phone numbers for Domestic / International calling must include the country code.

Android Activity Lifecycle

Because the Android OS automatically reclaims resources, you as an application developer need to be aware of application lifecycle events. Background processes are the first resources to be reclaimed when the OS needs memory. The App Verify Android SDK runs auto voice verification asynchronously on a background thread, so a verification failure or a bad end user experience could occur if the running verification is associated with an activity that is moved to the background.

An activity can be paused, stopped, or destroyed. This discussion treats stopped as the same state as paused. Each state is defined as follows:

Paused/Stopped

An activity is paused when an end user moves it to the background. The current activity can pause, for example, when an end user changes activities or turns off the phone's screen. The activity and associated threads continue to run, but can be reclaimed by the OS at any time, in which case they will be destroyed. When an activity calls onPause, you can leave Verification.startAsync running. The verification process can still call VerificationListener methods such as onStageFailure and onSuccess while the activity remains in the background. In other words, auto verification can complete successfully when an end user shuts off the screen or switches to another app. Being in a paused state poses some risk, because a paused activity can be destroyed, and a destroyed activity will lose its verification progress.

Destroyed

An activity is destroyed when an end user closes it or when it is reclaimed by the operating system. This is more likely to occur to an activity that is in the paused state. When an activity is destroyed, any references to it are destroyed as well, including the verification object. The application should call Verification.cancel in an activity's onDestroy method, so that the SDK can perform cleanup on the object and the memory can be completely reclaimed by the OS. When the verification is cancelled or destroyed, the state of the verification will be lost. Even if the verification is given a chance to cancel (using the cancel method), an out-of-band voice call can still arrive. The incoming call would not be automatically terminated, since the verification thread is no longer running.

A best practice to mitigate the problems described for the pause and destroyed states would be to run the SDK from an Android Service, which is meant to be run in the background. The OS will avoid reclaiming all paused activities before it reclaims services. An activity could start a service, and the service can act as a buffer between the activity and the SDK. Even if the activity is paused or destroyed, it can reload the state from a running service when the app is reopened. This is essentially the Model/View/Presenter (MVP) design pattern: the activity (View) loads data from the service (Model), and the code to load data into the activity dynamically is the Presenter.

Handling Duplicate Verification Requests

Ensure that a duplicate verification request for the same number is not sent to TeleSign for verification when there is an on-going request. For example, the application should not call TeleSign API methods to trigger a duplicate verification process. The request should be either a success/failure/timeout which gets returned by the SDK to the application. You should disable or hide the button which is provided to the end user to trigger the Auto Verification process after the verification process is already triggered. This is to prevent duplicate verification requests originating from the application.

Handling Non-Verification Calls

This section provides details about how to handle non-verification calls. A non-verification call is any phone call that is not part of the verification process for your end user.

To correctly handle the calls, you need to be aware of three things:

1. On a CDMA device with no Wi-Fi connection, when a phone call is in progress, the phone does not have internet access.

• The customer's registration process and App Verify fail, since they both need internet access.

2. Two calls cannot simultaneously ring on a telephone. While one call is ringing, a second call that tries to ring is sent to voicemail or gets a busy signal, depending on whether voicemail is set up.

• For the brief moment AutoVoiceVerification is ringing on the device, if another phone call comes in, it will get sent to voicemail. No call will get logged onto the device. The caller can either leave a voicemail or try again. AutoVoiceVerification will succeed normally.
• If another phone call is ringing when the AutoVoiceVerification phone call tries to ring, the App Verify phone call will either get a busy signal or get sent to voicemail. If the call gets a busy signal, the TeleSign server will retry sending the voice call and the second call will come a few seconds later while the phone is most likely not ringing. If the call is sent to voicemail, App Verify fails after waiting about 30 seconds for the call.

3. On Android, if two calls are in progress, the API does not provide support for terminating one and only one of the calls. To avoid disrupting an ongoing call, TeleSign does not terminate calls if another call is in progress.

• On a device with GSM or with both a CDMA and Wi-Fi connection, if the AutoVoice Verification call comes in while there is another phone call going on, TeleSign does not terminate either call. As a result, either the phone will ring until it gets sent to voicemail, or the phone is answered by the end user, and the call immediately hangs up and the end user is returned to their previous call. No matter which of these outcomes occurs, AutoVoiceVerification completes normally afterwards.

Required Permissions

Beginning with Marshmallow, you must explicitly request certain permissions you need for your application. This section displays all permissions you may potentially need.

• android.permission.READ_PHONE_STATE - You must ask the end user to grant this permission.) Allows read only access to the phone's state, and is used to determine the status of any ongoing calls. You need this permission so you can verify that your end user receives a phone call from TeleSign.

• android.permission.CALL_PHONE - (When you ask the end user to grant the READ_PHONE_STATE permission, Android bundles this one in with it.) You need this permission so you can cancel phone calls from TeleSign.

• android.permission.WRITE_EXTERNAL_STORAGE - This permission is optional. You only need it to write encrypted logs to the SD card.

• android.permission.INTERNET - Allows applications to open network sockets.

• android.permission.ACCESS_NETWORK_STATE - Allows applications to access information about networks.

• android.permission.VIBRATE - (Optional) Allows access to the vibrator. If this permission is enabled, a signal will be sent to alert the end user about an incoming call or SMS message.

Required Permissions for Android O

If you are targeting your application for Android O, the device must explicitly add android.permission.READ_PHONE_STATE and android.permission.CALL_PHONE in the manifest.xml in order for the App Verify SDK to read the verify code in the phone call and terminate the phone call. Previously, if you added android.permission.READ_PHONE_STATE in manifest.xml it would grant all permissions in the group (the group includes android.permission.READ_PHONE_STATE and android.permission.CALL_PHONE).

Error Codes

Verification Error Types

The App Verify Android SDK includes the Verification Listener, an interface to notify developers about events and errors in the verification flow, by way of callbacks. The Verification Listener includes the onStageFailure method, which enables developers to locate errors if the verification process fails. For more information on these errors, see the VerificationError.ErrorType enumeration in the Javadoc API Reference section of the App Verify SDK. The App Verify product is deprecated, if you want to see the GitHub repository, contact support.

The following table describes the verification error codes that the App Verify Android SDK can generate:

📘

NOTE:

A phone number is required to use verification objects. Therefore, an error will occur on any device that doesn't have a phone number associated with it.

System Unavailable

Invalid Signature

Rate Limit Exceeded

XID Not Found or XID Does Not Belong to Customer

Get Status by XID Codes

This section provides details about codes returned by App Verify when attempting to do a Get Status request using XID codes.