Android client integration

Integration steps

Download the SDK

Log on to the Phone Number Verification Service console. On the Overview page, find the API & SDK section on the right and click Download Now. Follow the on-screen instructions to download the required SDK.

Create an authentication scheme

For more information, see Create an authentication scheme and obtain a scheme code.

Project setup

1. Ensure that your project meets the following environment requirements for minSdkVersion and compileSdkVersion.

   1. minSdkVersion: The Phone Number Verification SDK requires API level 21 or later. When you create a new project, the minSdkVersion must be 21 or higher.

   2. compileSdkVersion: The Phone Number Verification SDK requires API level 30 or later. When you create a new project, the compileSdkVersion must be 30 or higher.

      

2. Import the aar artifacts and add dependencies.

   1. In the module that uses the phone number verification feature, import the SDKs by copying all three AAR files into the libs folder.

      

      • Package starting with auth: This is the main aar artifact, which implements the one-click logon and local number verification features.

      • Package starting with logger: This is the SDK's logging component and is a required dependency.

      • Package starting with main: This is the SDK's base functional component and is a required dependency.

   2. In the app module (usually app/build.gradle), add the following dependency to the dependencies code block:

      implementation fileTree(dir: 'libs', include: ['*.aar'])
      implementation 'androidx.appcompat:appcompat:1.3.1'

      

Add permissions

Add permissions to your AndroidManifest.xml file.

• Required permissions (These are declared in the aar file and require no separate configuration.)

<uses-permission android:name="android.permission.INTERNET" /> <!-- For internet access -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <!-- To check the Wi-Fi state -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- To check the network state -->
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /> <!-- To change the network state -->

• Optional permissions (These permissions are not required for the mobile number verification feature.)

<uses-permission android:name="android.permission.READ_PHONE_STATE" /> <!-- To read the phone state -->

For more information, see Mobile number verification interaction flow.

SDK methods

Get the authentication instance

/**
 *  Gets the singleton instance of this class.
 * @param context The Android context. The application context is recommended.
 * @param tokenListener The callback for token retrieval results.
 *  @return The singleton instance of the class.
 */
public static PhoneNumberAuthHelper getInstance(Context context, TokenResultListener tokenResultListener)

Usage example

TokenResultListener mTokenResultListener = new TokenResultListener() {
    @Override
    public void onTokenSuccess(String s) {
         // Handle successful token retrieval.
    }

    @Override
    public void onTokenFailed(String s) {
         // Handle failed token retrieval.
    }
};
PhoneNumberAuthHelper mPhoneNumberAuthHelper = PhoneNumberAuthHelper.getInstance(this, mTokenResultListener);

Required method: Set SDK secret (setAuthSDKInfo)

/**
 *  Initializes the SDK. Call this method once during the app's lifecycle.
 *  @param  secretInfo Your AppID, AppKey, and scheme code.
 */
public void setAuthSDKInfo(String secretInfo)

Usage example

mPhoneNumberAuthHelper.setAuthSDKInfo(secretInfo);

Required method: Get verification token (getVerifyToken)

Before you use this method, call the setAuthListener method.

/**
     * Gets the verification token.
     *
     * @param totalTimeout The timeout in milliseconds (ms).
     */
public void getVerifyToken(final int totalTimeout)

Usage example

mPhoneNumberAuthHelper.setAuthListener(mVerifyListener);
mPhoneNumberAuthHelper.getVerifyToken(5000);

Optional method: Accelerate token retrieval (accelerateVerify)

/**
     * Accelerates the mobile number verification process.
     *
     * @param overdueTimeMills The timeout in milliseconds (ms).
     * @param listener         The callback for the result.
     */
@AuthNumber
public void accelerateVerify(final int overdueTimeMills, final PreLoginResultListener listener)

Usage example

mPhoneNumberAuthHelper.accelerateVerify(timeout, new PreLoginResultListener() {
    @Override
    public void onTokenSuccess(String vendor) {
        // Handle the successful acceleration.
    }

    @Override
    public void onTokenFailed(String vendor, String errorMsg) {
      // Handle the failed acceleration.
    }
});

Mobile number verification example

//// 1. Create an instance.
mVerifyListener = new TokenResultListener() {
            @Override
            public void onTokenSuccess(String s) {
               // Handle successful token retrieval.
            }

            @Override
            public void onTokenFailed(final String s) {
                // Handle failed token retrieval.
            }
        };
 mPhoneNumberAuthHelper = PhoneNumberAuthHelper.getInstance(getApplicationContext(), mVerifyListener);

// 2. Check if the environment is ready.
mPhoneNumberAuthHelper.checkEnvAvailable(PhoneNumberAuthHelper.SERVICE_TYPE_AUTH);

// 3.1. (Optional) Accelerate verification.
 mPhoneNumberAuthHelper.accelerateVerify(5000, new PreLoginResultListener() {
            @Override
            public void onTokenSuccess(String vendor) {
                // Handle the successful acceleration.
            }

            @Override
            public void onTokenFailed(String vendor, String errorMsg) {
                 // Handle the failed acceleration.
            }
        });
// 3.2. Get the verification token.
mPhoneNumberAuthHelper.setAuthListener(mVerifyListener);
mPhoneNumberAuthHelper.getVerifyToken(timeout);
// 4. Verify the token on your server.
// Your server must integrate with the Phone Number Verification Service and provide an API that your app calls to pass the mobile number and verification token.