Start enriching your app

Docs

Android

Introduction

The Sinch Verification SDK makes verifying phone numbers easy. This SDK supports the verification of phone numbers via SMS or flash calls.

This document provides an overview for developers integrating with Sinch Verification SDK for the first time. Please see the Reference Documentation for a comprehensive description of all the classes.

First time setup

This is a step-by-step guide about setting up the Sinch Verification SDK for the first time.

Register an Application

  1. Register a Sinch Developer account at http://www.sinch.com/signup.
  2. Set up a new Application using the Dashboard, where you can then obtain an Application Key.
  3. Enable Verification for the application by selecting: Authentication > Public under App > Settings > Verification

Download

The Sinch Verification SDK can be downloaded at www.sinch.com/download/. It contains: the library aar, this user guide, reference documentation, and a sample app.

Add the Sinch library

The Verification SDK library is distributed in AAR format. To use it in your project either:

  • Copy the .aar file to the libs folder and edit the build.gradle file to include

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
    
    dependencies {
        compile(name:'sinch-android-verification-1.1.7', ext:'aar')
    }
    
  • Or using Android Studio choose File -> New -> New Module -> Import .JAR/.AAR Package option

The verification process

Verification of a phone number is performed in two steps: requesting a verification code and verifying the received code. If all of the permissions are provided (see Permissions), the Verification SDK attempts to automatically verify any matching code that is received through SMS or flash call during the verification process. This means that during a flash call verification, the Verification SDK will automatically hang up the incoming call if (and only if) it matches the expected pattern. During an SMS verification, any received messages text will be matched against the template, and if it matches, the code will be extracted and automatically sent to the Sinch backend. The Verification SDK will callback to the VerificationListener during the process, see VerificationListener for more information.

If the permissions needed for automatic verification are not provided, the verify method on the Verification object should be invoked with a user-supplied verification code to verify the phone number.

Note: The SDK will abort verification process and trigger the onVerificationFailed callback after a certain time, typically around 20 seconds. However, the SDK will continue to listen for calls for an additional time after the verification has failed, in order to intercept and report any possible late calls.

Permissions

The android.permission.INTERNET permission is required for the Verification SDK to work. To allow the Verification SDK to automatically read incoming SMS messages, use either READ_SMS or RECEIVE_SMS. To handle flash call verification automatically, use READ_PHONE_STATE, READ_CALL_LOG, and CALL_PHONE. CALL_PHONE is used to automatically hang up the call.

The full list of permissions:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />
<uses-permission android:name="android.permission.READ_CALL_LOG" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.CALL_PHONE" />

Permissions handling on API levels 23 or later.

If your application targets API 23 or later the permissions have to be requested at runtime, see Runtime Permissions.
It is recommended to ask the user for corresponding permissions just before initiating verification. See the sample application for an example.
If the verification SDK fails to intercept the code automatically due to missing permissions, the onVerificationFailed callback will be executed with an instance of CodeInterceptionException. In this case it is still possible to proceed with verification by asking the user to enter the code manually.

Flash Call Verification

To initiate a flash call verification, start by creating a Verification object through SinchVerification.createFlashCallVerification, then start the verification process by invoking initiate() on the Verification object. This method can be called multiple times, for example if another call should be placed.

Config config = SinchVerification.config().applicationKey(APPLICATION_KEY).context(getApplicationContext()).build();
VerificationListener listener = new MyVerificationListener();
String defaultRegion = PhoneNumberUtils.getDefaultCountryIso();
String phoneNumberInE164 = PhoneNumberUtils.formatNumberToE164(phoneNumberString, defaultRegion);
Verification verification = SinchVerification.createFlashCallVerification(config, phoneNumberInE164, listener);
verification.initiate();

IMPORTANT: It is important to pass ApplicationContext to the verification config builder, as the verification object might outlive the activity or fragment it is instantiated from.

SMS Verification

To initiate an SMS verification, start by creating a Verification object through SinchVerification.createSmsVerification, then start the verification process by invoking initiate() on the Verification object. This method can be called multiple times, for example, if another SMS should be sent.

Config config = SinchVerification.config().applicationKey(APPLICATION_KEY).context(getApplicationContext()).build();
VerificationListener listener = new MyVerificationListener();
String defaultRegion = PhoneNumberUtils.getDefaultCountryIso();
String phoneNumberInE164 = PhoneNumberUtils.formatNumberToE164(phoneNumberString, defaultRegion);
Verification verification = SinchVerification.createSmsVerification(config, phoneNumberInE164, listener);
verification.initiate();

A VerificationListener object must be provided.

Verification listener

The VerificationListener provides callbacks during the verification process. If initiation is successful, the onInitiated() callback runs and the verification code interceptor is started automatically. If initiation fails, the onInitiationError() callback runs and the exception describing the error is passed. If code verification is successful, the onVerified() callback is called. If verification fails, onVerificationError() callback runs and the exception describing the error is passed.

VerificationListener listener = new VerificationListener() {
    @Override
    public void onInitiated() {
        // Verification initiated
    }
    @Override
    public void onInitiationFailed(Exception e) {
        if (e instanceof InvalidInputException) {
            // Incorrect number provided
        } else if (e instanceof ServiceErrorException) {
            // Sinch service error
        } else {
            // Other system error, such as UnknownHostException in case of network error
        }
    }
    @Override
    public void onVerified() {
        // Verification successful
    }
    @Override
    public void onVerificationFailed(Exception e) {
        if (e instanceof InvalidInputException) {
            // Incorrect number or code provided
        } else if (e instanceof CodeInterceptionException) {
            // Intercepting the verification code automatically failed, input the code manually with verify()
        } else if (e instanceof IncorrectCodeException) {
            // The verification code provided was incorrect
        } else if (e instanceof ServiceErrorException) {
            // Sinch service error
        } else {
            // Other system error, such as UnknownHostException in case of network error
        }
    }
}

Phone numbers

IMPORTANT: The phone number should be specified according to the E.164 number formatting (http://en.wikipedia.org/wiki/E.164) recommendation and should be prefixed with a +. See the section Phone numbers for details.

Validate code manually

To complete the verification of the phone number, the code should be passed to verify. For SMS verification, the code is in the message body. For flash calls, the caller id is the code. Example:

verification.verify(code); 

The method verify may be invoked multiple times. For example, if the verification listener is invoked with an IncorrectCodeException, the application may hint to the user that the code was incorrect, let the user adjust it, and call verify again on the same verification instance.

Network connectivity errors

The Sinch Verification SDK will try to resend HTTP requests to the Sinch backend if a request failed due to a network related error. The SDK schedules a number of retries for approximately 30 seconds. If sending the HTTP request is still unsuccessful, it eventually invokes the verification listener onInitiationError or onVerificationError with an exception that indicates the problem, for example, java.net.UnknownHostException.

Pass data to your backend

For each call to Verification.initiate(), the Sinch backend can perform a callback to the application backend to allow or disallow an SMS or flashcall being initiated. By using the optional parameter custom on SinchVerification.createFlashCallVerification and createSmsVerification, any unique identifier can be passed from the application to the application backend. The data will be passed as a string. If there is a need for a more complex datatype, it needs to be stringified or encoded before being sent.

Phone numbers

The phone number should be specified according to the E.164 number formatting (http://en.wikipedia.org/wiki/E.164) recommendation and should be prefixed with a +. For example, to verify the US phone number 415 555 0101, the phone number should be specified as +14155550101. The + is the required prefix and the US country code 1 prepended to the local subscriber number.

The Sinch SDK provides APIs for formatting phone numbers. The primary class for this functionality is PhoneNumberUtils. A key thing when parsing user input as a phone number is the concept of default region; if a user enters their number in a local format, the parsing must know which region / country to assume. Example:

// Get user's current region by carrier info
String defaultRegion = PhoneNumberUtils.getDefaultCountryIso();

IMPORTANT: When passing a number as a string to create a Verification, the string should contain a number in E.164 format.

A number can be formatted as E.164 like this:

String phoneNumberInE164 = PhoneNumberUtils.formatNumberToE164(phoneNumberString, defaultRegion);

Improving verification performance with a great UI

For better verification performance, it should be straightforward and easy for users to enter their phone phone numbers. To simplify this step and build a UI that accurately captures the correct input from the users, the Sinch SDK provides some utility APIs.

PhoneNumberFormattingTextWatcher

The Sinch SDK provides a PhoneNumberFormattingTextWatcher class that behaves exactly like the system android version PhoneNumberFormattingTextWatcher, but allows specifying a region other than the system one when using APIs before 21. This watcher can be added as a text changed listener to a text field and will format it automatically if a phone number is entered in local or international format.

Viable phone number check

The isPossibleNumber method in PhoneNumberUtils can be used to give the user a hint whether the entered phone number is a viable one in the specified region by for example highlighting the text field with a different color.

Miscellaneous

Minimum requirements

Android SDK version 9 is the minimum version required for using the Sinch Verification SDK.

ProGuard

If ProGuard is used to shrink an artifact (e.g. an APK) that is consuming the Sinch Verification library, the ProGuard rules defined in the file proguard-rules.pro, which is included in the SDK package, must be applied.

Encryption export regulations

Please check the Summary of U.S. Export Controls Applicable to Commercial Encryption Products and ensure that the application is registered for the Encryption Regulations, if applicable. It can be found under this link.