Verify a Mobile Device with App Verify for Android

This tutorial shows you how to get started with the App Verify Android SDK. App Verify is a product that allows you to automatically verify an end user’s mobile device and phone number using a voice call or SMS message. Using the AppVerifySample application provided with the App Verify Android SDK, you can see how the application works.

For a general overview of the product and how it works, refer to the App Verify Android SDK page.

This tutorial includes the following sections:

Requirements

This section provides details about what you need to get started:

  • JSON Web Token (JWT) Service - A service that issues JWT tokens for use in authentication. You need your own JWT service, or (for testing purposes only) a URL for TeleSign’s trial JWT server.
  • You can get help setting this up by referring to the JWT Service for App Verify page.
  • For a sample walkthrough that shows the basics of setting up a JWT service, refer to Implement a JWT Service.
  • Android Studio - you can build and deploy using another tool if you like, however this documentation is created using Android Studio.
  • Android phone running Marshmallow (6.0 and above) - you can build and deploy using an earlier version. If you do this, you do not need to worry about permissions as they are handled automatically. If you use Marshmallow, you do need to include requests for all the appropriate permissions in your application. For this reason, Marshmallow is used in the examples.
  • App Verify Android SDK - https://github.com/TeleSign/android_appverify_sdk
  • For SMS Retriever to work you must have an Android device with Play services version 10.2 or higher.

How it Works

This section provides instructions for how to use an application (AppVerifySample) that uses the App Verify Android SDK. If you want to get started implementing the code, you can skip ahead to Implementation Walkthrough. This section is best for getting acquainted with how an application using the App Verify Android SDK works, or to test that your JWT server, Android Phone, and Android Studio works.

SMS Retriever

SMS retriever allows you to perform SMS_based user verification in your Android app without requiring an end user to type verification codes, or give any extra application permissions. If you want to use SMS retriever for verification, you must register your application hash with TeleSign. Do the following:

  1. Navigate to portal.telesign.com and log in. You will see the Dashboard Home screen.

  2. Go to the navigation menu on the left and click App Verify. A list of choices appears.

  3. Under App Verify, click Settings. You are taken to the App Verify Settings screen.

  4. Scroll down to the Android SMS Retriever section. Next to Application Hash, click Edit. The Edit Application Hash screen appears.

  5. Enter your application hash in the Application hash field. Click Save.

Download the SDK and Configure the Sample App

This section explains how to set up the SDK and sample application.

  1. Download the App Verify SDK here: https://github.com/TeleSign/android_appverify_sdk by clicking Clone or Download.

  2. Navigate to where you store the AppVerifySample folder on your computer and open AppVerifySample in Android Studio.

  3. To see the sample application work, you need a JWT service. You may use TeleSign’s trial JWT service. Your JWT URL will be: https://tokengen.telesign.com/v1/mobile/verification/token/*your customer ID goes here*.

NOTE:

The trial JWT service is just for seeing the application work. You may not use the trial service in a live production environment. You should use your own service for the implementation walkthrough. Switch to your own service as soon as possible. For help creating a JWT service, refer to the JWT Service for App Verify page or the Implement a JWT Service tutorial.

  1. Open the build.gradle file.

  2. Look for the buildConfigField and enter the URL for TeleSign’s trial JWT service into the space between the quotes "". Your trial JWT URL takes the form of https://tokengen.telesign.com/v1/mobile/verification/token/*your customer ID goes here*.

NOTE:

In your own implementation, you will want to make sure the JWT URL is dynamically constructed. The static URL is just for now, so you can see how the sample application works.

  1. You must use an Android phone that can receive phone calls and SMS messages to see this application work, as an emulator cannot handle calls and texts. (You also cannot use an Android tablet.) Make sure your phone is plugged in to your computer’s USB port.

  2. Compile the AppVerifySample program by pressing the green triangle icon.

  1. Android Studio brings up the Select Deployment Target screen. Choose a device from under Connected Devices.

  2. Click OK. The application starts.

  3. You are presented with the opening screen for the AppVerify Sample application.

  1. Enter the country code in the Country field and the phone number in the Phone Number field for the phone number you want to use to test.
NOTE:

If you are doing the free trial, you must verify the phone number you want to use before using it.

  1. Check the box next to AutoVoice, AutoSMS using Retriever, and AutoSMS using Permissions. This walkthrough shows you what would happen if you were to waterfall through each feature.

  2. You are asked for all permissions required for any of the boxes you checked. For the walkthrough, you checked all the boxes, so you are asked for permissions required for AutoVoice followed by those for AutoSMS using Permissions. Depending on what version of Android you are running, you may or may not be asked to answer a series of questions granting the application permissions. If you are using a version of Android before Marshmallow, you will not be prompted to grant permissions, they are granted automatically. If you are using Marshmallow or higher, the permissions must be granted manually. After you grant permissions the first time, you will not be prompted again. You are first asked to grant permissions for SMS.

  1. The application asks if you will allow AppVerify Sample to make and manage phone calls. Press Allow.
  1. The application asks if you will allow AppVerify Sample to send and view SMS messages. Press Allow.
  1. The sample application will try to confirm using AutoVoice. If that fails, the application waterfalls to AutoSMS using Retriever. You do not need permissions to use SMS Retriever, only your application hash and Play services 10.2 or higher. If that fails, the application waterfalls to AutoSMS using Permissions. If successful, your phone is verified and you are granted access.

Implementation Walkthrough

This section provides a walkthrough of how to set up an application of your own. It uses the AppVerifySample application and the javadocs for the App Verify SDK as a guide. You will need your own JWT service set up to go through this walkthrough. If you need help setting up a JWT service, refer to the JWT Service for App Verify page in the App Verify SDK category, or the Implement a JWT Service tutorial.

NOTE:

Your JWT service should include the phone number provided by the end user and the external ID (xid) parameter for each token, and you should have a way to store the xid values.

This section assumes that you already have your URL from TeleSign, or from your own JWT server. This section also assumes that you will use an implementation where you provide TeleSign your JWT server URL through the App Verify SDK, and then TeleSign fetches your tokens for you. You can also do your own implementation, but as having TeleSign fetch your tokens is recommended, that is the method discussed in this tutorial.

Set up Application Hash with TeleSign

If you want to use the SMS Retriever feature, you must register your application’s hash with TeleSign. Do the following:

  1. You must register your application hash with TeleSign. Navigate to portal.telesign.com and log in. You will see the Dashboard Home screen.

  2. Go to the navigation menu on the left and click App Verify. A list of choices appears.

  3. Under App Verify, click Settings. You are taken to the App Verify Settings screen.

  4. Scroll down to the Android SMS Retriever section. Next to Application Hash, click Edit. The Edit Application Hash screen appears.

  5. Enter your application hash in the Application hash field. Click Save.

NOTE:

If you are doing debugging concerning the hash, you can use the AppSignatureHelper function to retrieve hash information. This helper function is listed in the MainActivity.java file.

Importing the App Verify SDK and Walking Through MainActivity.java

This section provides instructions for setting up and importing the App Verify SDK into Android Studio.

  1. If you want to use TeleSign’s sample JWT server for testing purposes, your JWT URL is: ‘https://tokengen.telesign.com/v1/mobile/verification/token/your customer ID goes here’.

  2. Log in to GitHub and navigate to https://github.com/TeleSign/android_appverify_sdk.

  3. To download the App Verify SDK, click Clone or download.

  4. In Android Studio, open or create the application you want to use the App Verify SDK with.

  5. To use the SDK with your project, add the .aar file.

  6. Add the following code to the top level of your app.gradle:

Add Code to app.gradle
{code}
repositories {
  flatDir {
    dirs 'libs'
  }
}
{code}
  1. Add the following code snippet into the dependencies section of your app.gradle:
Add to Dependencies Section in app.gradle
{code}
compile(name:'appverify', ext: 'aar')
{code}
NOTE:

You can see an example of the code snippets from step 7 and step 8 in the AppVerifySample application. Go to AppVerifySample/app/libs and AppVerifySample/app/build.gradle to see how they are integrated.

  1. Open the MainActivity file.

  2. Add import statements to include the App Verify SDK. They look like this:

Import the App Verify Android SDK
import com.telesign.mobile.verification.AutoVoiceVerification;
import com.telesign.mobile.verification.PermissionsUtil;
import com.telesign.mobile.verification.Verification;
import com.telesign.mobile.verification.VerificationError;
import com.telesign.mobile.verification.VerificationListener;
import com.telesign.mobile.verification.AutoSMSVerificationUsingPermissions;
import com.telesign.mobile.verification.AutoSMSVerificationUsingRetriever;
import com.telesign.mobile.verification.VerificationStage;
  1. Inside public class MainActivity extends Activity {}, provide a dynamic way to construct links to your JWT service. Provide the JWT URL to the App Verify SDK.
Add String Variable for JWT Server
String jwtUrl = String.format(JWT_URL_TEMPLATE, "phone_number", "xid");
  1. If you would like to know what version of Android your Android Studio is configured for, you can check if you have the Android version you need for this tutorial (Marshmallow). In Android Studio, click Tools > Android > SDK Manager. The Default Settings screen opens displaying the SDK Platforms tab.

  2. Download and install the appropriate version of Android as necessary.

  3. You also need a working phone to test with. Download any drivers you may need and make sure it is working with your set up before proceeding.

NOTE:

For technical details about the App Verify Android SDK, you can review the documentation about what methods are available by going to the place on your machine you downloaded the App Verify Android SDK to and navigating to: ...android_appverify_sdk/tree/master/javadocs.

  1. If you are using SMS retriever, you must ensure you are using the correct hash for your application. You can use the AppSignatureHelper function to retrieve hash information.
AppSignatureHelper
 // Debug logs with application hash to be used when using AutoSMS using retriever
ArrayList<String> signatures = AppSignatureHelper.getAppSignatures(this);
for (String s : signatures) {
   Log.d("SmsRetrieverDebug", "App signature: \"" + s + "\"");
}

Set up Permissions (For Marshmallow and Higher)

This section goes over setting up requests for permissions in your application. If you are using a version of Android below Marshmallow, permissions are handled for you. Beginning with Marshmallow, you must explicitly request certain permissions you need for your application. The requests are made the first time the end user uses your application.

NOTE:

Permissions are marked to show what verification modes they go with (AutoVoice, AutoSMS using Retriever, and AutoSMS using Permissions).

Permissions

This section provides instructions for setting up permission requests in your application.

  1. To get started setting up permissions, review the MainActivity.java file as well as the RequestPermissionFragment class. These provide an idea of what permissions you need to implement in your application. There are different strategies for how to request them - for example you could ask for them as needed, or you could ask for them all at once up front.

  2. To make handling permissions easier, the App Verify SDK provides the PermissionsUtil class. It is recommended you review this class in the javadocs that come with the SDK download.

  3. In the AppVerifySample application, look in the AndroidManifest.xml file. This file displays all the permissions you potentially need for your application (you do not have to include the optional permission WRITE_EXTERNAL_STORAGE). You should include the following permissions in your own AndroidManifest.xml file:

    • 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.RECEIVE_SMS - (You must ask the end user to grant this permission.) You need this so your application can receive SMS messages using the AutoSMS using Permissions feature. You need this permission so you can read contents of SMS messages 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.
NOTE:

You do not have to explicitly ask the user for each phone (voice call) permission, they are bundled into one request with Android. The AutoSMS using Retriever feature does not require any special permissions, only that the end user’s Android phone has Play services 10.2 or higher installed. A requirements check for the AutoSMS using Retriever feature consists of making sure the right libraries for SMS Retriever are available.

Permissions to Include in AndroidManifest.xml File
<!-- 
   These are for receiving and sending SMS messages and voice calls. Handling them is made easier by the PermissionsUtil class. You must explicitly ask the end user for phone permissions and SMS message permissions. Permissions for each are bundled, so you do not need to ask about both phone (voice call) permissions individually. This is only required for Marshmallow and higher. Earlier versions of Android grant these permissions automatically.
-->
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <uses-permission android:name="android.permission.CALL_PHONE"/>
    <uses-permission android:name="android.permission.RECEIVE_SMS"/>

<!-- 
   You must include these, but you do not need to ask for them explicitly, they are granted automatically. WRITE_EXTERNAL_STORAGE is optional. 
-->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.VIBRATE"/>
  1. On start up of your application, check to see if the end user granted the permissions you need for app verification. You should check permissions regularly because your end user may have granted or revoked the permissions somewhere else already, for example, in Settings on their phone.
Check for Missing Permissions
public static String[] getMissingPermissions(Context context) {
        return a(context, c);
    }

/*Example Usage 
String[] unapproved = PermissionsUtil.getMissingPermissions(getApplicationContext());

if (unapproved.length > 0) {
   **Handle missing permissions**
}
*/ 
  1. If your end user did grant permissions, implement code that sends them to the registration process. There are different ways to set this up. For example, if your end user has GooglePlay, and you can register them using SMS retriever, you do not need to ask for any permissions to complete registration using this method. For other situations, such as for AutoVoice or AutoSMS using Permissions, if the end user did not grant permissions, you should present the end user with a message explaining that certain permissions are required for the application to work.

  2. Ask for permissions appropriate to the way you want to contact the end user to verify their phone. For each permission you ask about, describe the permission and why you need it for the application, so the end user understands what it is for. For example, when you request phone call permissions, you can include a note like “We need this permission to read voice call information to verify your phone number.” Now the end user knows what you need the permission for, and is more likely to grant it.

  3. To implement the permissions requests and the code that determines what activity to move to next, you want to use the PermissionsUtil class. The class offers methods that allow you to retrieve information about missing permissions in general, or specific to the verification mode. It also allows you to check whether the end user has already set certain permissions in the application or not.

  4. You must also handle the situation where the end user does not grant permissions, or there are not enough permissions to continue with the verification process. Implement code to check for the minimum permissions required to start the app verification process. For example, if your end user granted voice permissions only, or SMS permissions only, you could still conduct app verification using the method you have permissions for. Use methods from PermissionsUtil class to make implementation easier.

Set Up the Registration UI

This section describes how to set up the registration UI to accept your end user’s country code and phone number.

WARNING:

Do not attempt to auto-extract phone number information for your end user. Auto-extraction only works sometimes for some carriers in some countries. It is too unreliable to use.

  1. Your UI should clearly state that the end user must use a mobile device that has a phone number associated with it, because App Verify will not work with other types of devices.

  2. Your UI should display an explanation of the process the end user is about to undertake. You can provide something as simple as a title like “Online Registration Form” or similar.

  3. Your UI should display a Country Code field. This field should be completely separate from the Phone Number field. To make it easier to ensure proper input of data, use a drop-down menu or dial with preset options for the end user to choose from.

  4. Your UI should display a Phone Number field. This field should be completely separate from the Country Code field. Inform the end user that they may not enter special characters or formatting, just the numbers. Implement code to check they are not using special characters or formatting.

Set up Registration Process

This section describes how to set up the registration flow. You use the Verification class from the App Verify Android SDK. In the UI, when the user confirms registration by pressing a Submit button, or similar, it kicks off the registration flow in the sample app code (AppVerify Sample application). TeleSign recommends implementing the registration flow so that your code:

  • Determines which verification type to use
  • If waterfalling between different verification modes, the code uses the same session ID
  • Gets and validates the phone number and country code
  • Constructs a Verification object
  • setPhoneNumber() with the combined country code and phone number
  • Optionally enables debug logging (setDebugLogging(true))
  • Starts verification (Verification.startAsync())

To get started with these steps, do the following:

  1. In the build.gradle file (located at app/build.gradle): make sure you set up your JWT URL (dynamically) by editing the buildConfigField to contain the URL for your JWT server, or TeleSign’s sample JWT service (available for debugging only).
NOTE:

Remember that your JWT URL should include the end user’s phone number and the xid. Your JWT service should provide a way to store this information.

  1. Declare a new verification object. If you are following along with TeleSign’s sample code, you declare this in the MainActivity.java file.
Verification Object
private Verification verification;
  1. You should also create a way to track what mode you are in, AutoVoice, AutoSMSPermissions, or AutoSMSRetriever. This tutorial uses a waterfall, so you will want to set this up. If you know you will not do a waterfall, you can ignore this step.
Track Permissions Mode
private static final String TYPE_AUTO_SMS_USING_PERMISSIONS = "AutoSMSPermissions";
private static final String TYPE_AUTO_SMS_USING_RETRIEVER = "AutoSMSRetriever";
private static final String TYPE_AUTO_VOICE = "AutoVoice";
private String mode = TYPE_AUTO_VOICE;
  1. Create a new instance of a VerificationListener. (This is not required, it is an example of how to set up that you can use, or you can create your own.)
VerificationListener
private VerificationListener listener = new VerificationListener() {
    //Implement VerificationListener interface methods
  @Override
  public void onSuccess() {
         //Communicate client's success to your servers, which can then
    		 //check the verification status on TeleSign's server via Get Status
  }
  @Override
  public void onStageFailure() {
    		 // Handle stage failure scenarios
  }
}
  1. Create a function that kicks off when the end user presses submit/verify or similar. Steps 4 - 10 happen as part of the registration confirmation process. (This is not required, it is an example of how to set up that you can use, or you can create your own.)
Registration Confirmation Process
public void onRegisterConfirm(View v) {
			tring countryCode = countryCodeET.getText().toString();
      String phoneNumber = phoneNumberET.getText().toString();
      String userPhoneNumber = countryCode + phoneNumber;
      sessionId = UUID.randomUUID().toString();

      if (PermissionUtil.hasSmsRetrieverRequirements(getApplicationContext())) {
        // You will need to setup your JWT SERVER URL in BuildConfig as described in the sample 
        verification = new AutoSMSVerificationUsingRetriever(BuildConfig.JWT_SERVER_URL, callback_listener, userPhoneNumber);   
        verification.setSessionId(sessionId);
        verification.startAsync();
        }
}
  1. After the end user presses submit, as part of onRegisterConfirm, collect the country code and phone number and concatenate them into a single String (country code + phone number). You must have both the country code and phone number. In this tutorial, they are concatenated and stored in String userPhoneNumber. Since you are implementing a waterfall, include code in onRegisterConfirm to create a session ID. This allows you to link transactions for voice and SMS.
Include Session ID
if (v != null) {
			sessionId = UUID.randomUUID().toString();
		}
  1. Construct a new verification object as part of onRegisterConfirm. For a waterfall, you would typically move from AutoVoice to AutoSMS using Retriever to AutoSMS using Permissions.
Construct New Verification Object
if (mode.equalsIgnoreCase(TYPE_AUTO_VOICE)) {
     verification = new AutoVoiceVerification(jwtServerUrl, listener, phoneNumber);
}

else {
     verification = new AutoSMSVerification(jwtServerUrl, listener, phoneNumber);
}
  1. Pass the userPhoneNumber string to the App Verify Android SDK in your onRegisterConfirm function and start the verification process. Review the onRegisterConfirm function in the MainActivity.java file for details.

  2. Start the verification process.

Start Verification
try {
			verification.startAsync();
		} catch (IllegalStateException ex) {
  //Exceptions
    }
  1. The verification listener is set up to handle a successful or unsuccessful response from the server. In the sample application AppVerify Sample, if the response is unsuccessful (OnStageFailure in the code), you should waterfall to another verification mode.
waterfallToAutoSMS
if (mode.equalsIgnoreCase(TYPE_AUTO_VOICE)) {
     mode = TYPE_AUTO_SMS_USING_RETRIEVER;
     onRegisterConfirm(null)
}
  1. If the AutoSMS using Retriever option fails, you would then waterfall to AutoSMS using Permissions. After the process completes successfully with one of the options, you can move on to your application’s normal registration process.

  2. When the user completes the app registration process on your web server, you must then verify the end user’s information using the Get Status or Verify Transaction Callback web service to verify that the end user was verified using App Verify. This should happen before notifying the end user about the results of their attempt to register. You are doing this because data being sent from the phone cannot be completely trusted. Using server to server communication ensures security.

Final Verification with Get Status or Verify Transaction Callback

This section describes how to perform verification with Get Status or Verify Transaction Callback. This step helps ensure that your end user is legitimate by checking with TeleSign to make sure the verification was a success. There are two common ways to implement this check:

  • Get Status - Perform a single check on the fly to determine whether to grant an end user access
  • Verify Transaction Callback - Perform a high volume of checks on the fly to determine whether to grant an end user access (this is the best choice if you know you will have a lot of traffic)

In order to use either service, if you choose not to use one of TeleSign’s SDKs, you must handle authentication for your request yourself. The steps for correctly setting up your request are described in Authentication.

Get Status (With an SDK)

TeleSign provides a way to perform a Get Status request. This is the easiest way to verify a transaction.

var TeleSignSDK = require('telesignsdk');

const customerId = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"; // Todo: find in portal.telesign.com
const apiKey = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="; // Todo: find in portal.telesign.com
const rest_endpoint = "https://rest-api.telesign.com"; // Todo: Enterprise customer, change this!
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);

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

Get Status (Without an SDK)

To perform a Get Status request for a single end user transaction, do the following:

  1. Retrieve the xid for the end user’s transaction from the JWT URL you created.

  2. Send the xid in a request to TeleSign’s Get Status service using a link constructed as https://rest-api.telesign.com/v1/mobile/verification/status/[xid].

Service Request
GET /v1/mobile/verification/status/[xid]
  1. TeleSign sends back a JSON object containing details about the transaction.
Get Status Response
{
   "sub_resource" : "",
   "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 ",
   },
   "submit_timestamp": "2015-04-15T18:40:54Z",
   "session_id": "B571AA3A22D0025C8845B33F32E40A9A"
}
NOTE:

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

Verify Transaction Callback

This section describes how to receive verification results efficiently for a high volume of transaction callbacks. By using the Verify Transaction Callback service you can make more efficient use of network system resources. The Verify Transaction Callback service makes a server-to-server HTTP callback from the TeleSign server to your service endpoint to notify you. To set this up, do the following:

  1. Set up 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 Authenticated Callbacks with the Get Status/Verify Transaction API if you want to authenticate your callbacks, otherwise you can disregard this header).
    • Reference ID
    • Sub-Resource
    • Errors
    • Status: Updated On
    • Status: Code
    • Status: Description
    • Verify: Code States
    • Verify: Code Entered
    • Verify: Code Submitted
    • Submit Timeline
  2. Provide TeleSign with your private URI. (Contact support for help with set up.)

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

  4. You will receive callback notifications after both of the following occur:

    • A verification transaction completes
    • TeleSign determines the final status of the transaction
  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 Get Status, described above.

NOTE:

TeleSign only sends information about successful transactions and situations where the verification process begins. If there is no transaction information provided for a specific phone number and reference id, you can assume the transaction was unsuccessful.

  1. Search for your xid and phone number in TeleSign’s responses to determine the status of the end user’s transaction. If no information is available on the number, you can assume the transaction failed or did not complete.
NOTE:

If you wish to increase security by checking to make sure the information from TeleSign is truly from TeleSign, you may authenticate callbacks. Refer to the Authenticate Callbacks from TeleSign section of the App Verify SDK page.

Debug Loggings

Debug logs are encrypted. You must send your debug log to TeleSign to have it decrypted and reviewed for issues. To get your debug log, do the following:

  1. Add android.permission.WRITE_EXTERNAL_STORAGE to your app manifest.
  2. In your app code, on your Verification object set the setDebugLogging() function to enabled, to enable the encrypted logging on your device.
NOTE:

If you are using the TeleSign sample app to test, the debug logging is already enabled via the setDebugLogging() function.

  1. Compile your app APK and install it on your test device.
  2. Run the app on an Android phone to generate the log with the issue you are observing.
  3. Fetch the log from the mobile device.
  4. Using a File Manager (such as Astro File Manager), go to internal shared storage > Download folder.
  5. Select “encypted.key” and “encrypyed.log” files and attach to an email to TeleSign.

Error Handling

The App Verify SDK throws errors under certain conditions as described in the Error Codes section on the App Verify Android SDK page. Make sure your mobile app is able to handle these conditions. The following code is an example of how you can handle errors in your app:

Error Handling Example
public void onStageFailure(int stageCode, VerificationError err){
   if (stageCode < 0) {
       stageCode = 0;
   }

   CheckBox cb = statusCBArray[stageCode];
   cb.setTextColor(getResources().getColor(
         android.R.color.holo_red_light));

   try {
       Log.e(TAG, err.toJSON().toString());
   } catch (JSONException e) {
       Log.e(TAG, "", e);
   }
}

Rate Limiting

Rate limitation on the TeleSign server backend restricts the number of transactions per second (TPS) that can run through the verification process. By default, the Auto Voice verification rate limit is 5 TPS and the Auto SMS verification rate limit is 50 TPS.