4. Open your strings.xml file. Example path: /app/src/main/res/values/strings.xml and add a new string with the name "partnerKey" and value as your "appKey"

5. Open your AndroidManifest.xml and add a meta-data element to the application element

Copy

<application android:label="@string/app_name" ...>
...
<meta-data android:name="com.truecaller.android.sdk.PartnerKey" android:value="@string/partnerKey"/>
...
</application>

Truecaller SDK does not require any additional app permissions if you are using the SDK for verification of only Truecaller users.

To enable verification flow for non-Truecaller users as well, the SDK needs specific android permissions to enable the drop call based background verification flow. For details, please refer

In order to clear the resources taken up by SDK, you can use the method TruecallerSDK.clear(); You can call this method when the activity/fragment in which you have initialised the SDK is getting killed/destroyed.

For example :

Copy

@Override
protected void onDestroy() {
   super.onDestroy();
   TruecallerSDK.clear();
}

1. Ensure that your Minimum SDK version is at least API level 22 or above ( Android 5.1 ). In case your android project compiles for API level below 22, you can include the following line in your AndroidManifest.xml file to avoid any compilation issues :

Copy

<uses-sdk tools:overrideLibrary="com.truecaller.android.sdk"/> 

Using this would ensure that the sdk works normally for API level 22 & above, and would be disabled for API level < 22 Please make sure that you put the necessary API level checks before accessing the SDK methods in case compiling for API level < 22

2. Add the following dependency in your app level build.gradle file :

Copy

dependencies {
    ...
    implementation "com.truecaller.android.sdk:truecaller-sdk:2.8.0"
}

Also, add the following lines of code in your gradle file, if not already present

Copy

android{
    compileOptions{
         sourceCompatibility JavaVersion.VERSION_1_8
         targetCompatibility JavaVersion.VERSION_1_8
    }
}

Add mavenCentral() in your project level build.gradle file :

Copy

allprojects{ 
    repositories{ 
       ...
       mavenCentral()
       ... 
    } 
 }

Once you receive a callback in your VerificationCallback instance with the requestCode TYPE_MISSED_CALL_RECEIVED or TYPE_OTP_RECEIVED , you can complete the verification process by calling the following method from within your activity :

Copy

TrueProfile profile = new TrueProfile.Builder(firstName, lastName).build();

You need to create a TrueProfile instance by passing the user's first and last name as defined above.

Depending on whether the verification medium is drop call or OTP, you need to call one of the following methods respectively:

DropcallOTPCopy

TruecallerSDK.getInstance().verifyMissedCall(profile, apiCallback)

You need to call this method once you have received callback with requestCode as TYPE_MISSED_CALL_RECEIVED in your VerificationCallback instance

After you call the above method, you will receive a callback in your VerificationCallback instance with requestCode as TYPE_VERIFICATION_COMPLETE, which completes your verification process.

Whenever you get the verification callback with requestType as TYPE_VERIFICATION_COMPLETE, you would get an accessToken as a parameter in the verificationDataBundle. You can use this access token to validate the authenticity of the verification flow by making an API call from your server to Truecaller's server. For details on this part, please refer here.

7. Add the following condition in the onActivityResult method TruecallerSDK.getInstance().onActivityResultObtained( this,requestCode, resultCode, data)

Copy

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == TruecallerSDK.SHARE_PROFILE_REQUEST_CODE) {
       TruecallerSDK.getInstance().onActivityResultObtained(this, requestCode, resultCode, data);
    }
}

Note : In case you passed Fragment in the getUserProfile() method [ point #6 ], override the onActivityResult() method in your corresponding Fragment

8. In your selected Activity/Fragment, either make the component implement ITrueCallback or create an instance of it :

Copy

private final ITrueCallback sdkCallback = new ITrueCallback() {
    
     @Override
     public void onSuccessProfileShared(@NonNull final TrueProfile trueProfile) {
     }

     @Override
     public void onFailureProfileShared(@NonNull final TrueError trueError) {
     }
     
     @Override
     public void onVerificationRequired(@Nullable final TrueError trueError) {
     }
     
 };

onSuccessProfileShared() method will be called in either of the following two scenarios : a.) When the user has agreed to share his profile information with your app by clicking on the "Continue" button on the Truecaller dialog b.) When a non Truecaller user is already verified previously on the same device. This would only happen when the TruecallerSdkScope#SDK_OPTION_WITH_OTP is selected while initialising the SDK to provision for the verification of non-Truecaller users also.

onFailureProfileShared() method will be called when some error occurs or if an invalid request for verification is made. You'll get the respective error code as per the details mentioned here.

onVerificationRequired() method will only be called whenTruecallerSdkScope#SDK_OPTION_WITH_OTP is selected. This will be called when the user is not a Truecaller app user. Also, you'll get a Nullable TrueError only when TC app is installed and user is logged in. For other cases, it would be null. This optional TrueError can be used to determine the user action that led to initiating manual verification. So using this TrueError, you can get to whether the user pressed on the footer CTA on the verification screen OR the system back button.

Write all the relevant logic in the above callback methods to handle the scenarios appropriately.

Quick guide on how to properly track and instrument funnel for the verification flow of users via Truecaller on your app:

For proper tracking of the verification funnel via Truecaller SDK on your app, we recommend you to implement tracking events for the following states :

When you are using the SDK for verification of Truecaller users only ( 1-tap Verification without OTP ) :

1. Total users coming to your verification flow

2. Number of cases when the Truecaller app is present on your smartphone

3. Number of profile verification requests made by your app ( when TruecallerSDK.getInstance().getUserProfile() method is invoked )

4. Number of users who proceed with this flow and click Continue on the Truecaller dialog [ for these cases, you receive a success callback with TrueProfile response in onSuccessProfileShared() callback method ]

5. Number of cases where you received any error, where you receive an error callback with TrueError response in onFailureProfileShared() callback method. For details on specific error codes, please refer here.

When you are using the SDK for verification of non-Truecaller users also ( via drop call / fallback OTP ) :

1. Total users coming to your verification flow

2. Number of cases when the Truecaller app is present on your smartphone and users get verified via the Truecaller 1-tap flow ( as described in the above section )

3. Number of verification requests made by your app for a non-Truecaller user ( when TruecallerSDK.getInstance().requestVerification() method is invoked )

4. Number of cases where the user is getting verified for the very first time on the current smartphone and you receive a success callback - onRequestSuccess() method ( Please refer here ) -

   1. When the callback type you receive is either VerificationCallback.TYPE_MISSED_CALL_INITIATED or VerificationCallback.TYPE_OTP_INITIATED. This implies that a drop call / SMS has been triggered to the user's mobile number.

   2. When the callback type you receive is either VerificationCallback.TYPE_MISSED_CALL_RECEIVED or VerificationCallback.TYPE_OTP_RECEIVED. This implies that a drop call / SMS has been received on the user's mobile number on that smartphone. Please note that for getting the TYPE_OTP_RECEIVED callback, your app needs to have the Google SMS retriever hash code configured on Truecaller's developer portal ( while creating your partner key ) so that the SDK can auto read the incoming SMS and share the OTP with you in this particular callback method.

   3. Further to the above step, when you complete the user verification by invoking either TruecallerSDK.getInstance().verifyOtp() or TruecallerSDK.getInstance().verifyMissedCall() corresponding to the verification medium being used

   4. When the callback type you receive is either VerificationCallback.TYPE_VERIFICATION_COMPLETE. This implies that the verification in complete for the user

5. Number of cases where the user is already verified previously on the current smartphone and gets verified directly. In such cases, you receive the success callback - onRequestSuccess() method with callback type as VerificationCallback.TYPE_PROFILE_VERIFIED_BEFORE

This section defines the steps that can be used to trigger verification of non Truecaller app users which will be powered via Truecaller's drop call based verification flow

In order to verify non Truecaller users, the SDK requires the below mentioned permissions -

Copy

For Android 8 and above :

<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.READ_CALL_LOG"/>
<uses-permission android:name="android.permission.ANSWER_PHONE_CALLS"/>


For Android 7 and below :

<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.READ_CALL_LOG"/>
<uses-permission android:name="android.permission.CALL_PHONE"/>

Once you receive a callback in the ITrueCallback#onVerificationRequired(), you can initiate the verification for the user by calling the following method:

Copy

try{
   TruecallerSDK.getInstance().requestVerification("IN", PHONE_NUMBER_STRING, apiCallback, ExampleActivity.this);
}catch (RuntimeException e){
   Log.i(TAG, e.getMessage());
}

Here -

• the first parameter is the country code of the mobile number for which the verification needs to be triggered

• the second parameter (PHONE_NUMBER_STRING) is the mobile number to be verified. Please ensure proper validations are in place so as to send correct phone number string to the above method, otherwise an exception would be thrown

• the third parameter is an instance of VerificationCallback as defined here

• the fourth parameter is an instance of FragmentActivity

Please note that Truecaller SDK v2.8.0 currently supports the verification for non-Truecaller users for Indian numbers only.

Once you initiate the verification via TruecallerSDK.getInstance().requestVerification() method, you will receive either a callback in your VerificationCallback instance with a specificrequestType as described below

Copy

static final VerificationCallback apiCallback = new VerificationCallback() {

     @Override
     public void onRequestSuccess(int requestCode, @Nullable VerificationDataBundle extras) {
 	    
        if (requestCode == VerificationCallback.TYPE_MISSED_CALL_INITIATED) {
               if(extras != null){
                      extras.getString(VerificationDataBundle.KEY_TTL)
                      extras.getString(VerificationDataBundle.KEY_REQUEST_NONCE)
 	      }
        }
 
        if (requestCode == VerificationCallback.TYPE_MISSED_CALL_RECEIVED) {
 	}
 
        if (requestCode == VerificationCallback.TYPE_VERIFICATION_COMPLETE) {
               if(extras != null) 
                      extras.getString(VerificationDataBundle.KEY_REQUEST_NONCE)
	}
 
        if (requestCode == VerificationCallback.TYPE_PROFILE_VERIFIED_BEFORE) {
               if(extras!=null)
                      extras.getProfile().requestNonce
 	}
 
     }

     @Override
     public void onRequestFailure(final int requestCode, @NonNull final TrueException e) {
     }
     
 };

onRequestSuccess() method is called under any of the following scenarios -

• When drop call is successfully initiated for the input mobile number. In this case, you will get the requestCode as VerificationCallback.TYPE_MISSED_CALL_INITIATED

• When drop call is successfully detected on that device by the SDK present in your app. In this case, you will get the requestCode as VerificationCallback.TYPE_MISSED_CALL_RECEIVED

• When the verification is successful for a particular number. In this case, you will get the requestCode as VerificationCallback.TYPE_VERIFICATION_COMPLETE

• When the user is already verified on that particular device before. In this case, you will get the requestCode as VerificationCallback.TYPE_PROFILE_VERIFIED_BEFORE

When requestCode is VerificationCallback.TYPE_MISSED_CALL_INITIATED, you will receive an additional parameter for the time to live i.e TTL (in seconds) which is passed as String extra in the VerificationDataBundle of onRequestSuccess(). This value determines amount of time left to complete the verification. You can use this value to show a waiting message to your user before they can try for another attempt. Once the TTL expires, you can either auto-retry the verification by calling the requestVerification() method automatically with the same input parameters OR you can also take the user back to the number input screen to enter a different number for verification.

NOTE: Truecaller SDK v2.5.0 & above won't throw timeout exceptions for missed call, so please use the TTL as stated above to control the time out scenario.

When the requestCode is VerificationCallback.TYPE_ALREADY_VERIFIED_BEFORE or VerificationCallback.TYPE_VERIFICATION_COMPLETE, it means that the user verification via Truecaller SDK is complete. In these cases, the SDK will share an additional access token with your application, which you may then use to validate the response at your server end. To fetch the access token, you may use the following code snippet :

//For when the control goes to TYPE_ALREADY_VERIFIED_BEFORE extras.getProfile().accessToken

//For when the control goes to TYPE_VERIFICATION_COMPLETE extras.getString(VerificationDataBundle.KEY_ACCESS_TOKEN)

Post fetching the access token, you may perform the server side validation by referring to the steps mentioned in the later part of the documentation here.

onRequestFailure() method will be called when some error has occurred while verifying the provided mobile number. You will receive the appropriate error message from TrueException using TrueException#getExceptionMessage().For details of different possible error types you may encounter, please refer to the next section.

6. Create a TruecallerSdkScope object by using the appropriate configurational settings and use it to initialise the TruecallerSDK in your android activity's onCreate method :

Copy

TruecallerSdkScope trueScope = new TruecallerSdkScope.Builder(this, sdkCallback)
        .consentMode(TruecallerSdkScope.CONSENT_MODE_BOTTOMSHEET)
        .buttonColor(Color.parseColor(colorSpinner.getSelectedItem().toString()))
        .buttonTextColor(Color.parseColor(colorTextSpinner.getSelectedItem().toString()))
        .loginTextPrefix(TruecallerSdkScope.LOGIN_TEXT_PREFIX_TO_GET_STARTED)
        .loginTextSuffix(TruecallerSdkScope.LOGIN_TEXT_SUFFIX_PLEASE_VERIFY_MOBILE_NO)
        .ctaTextPrefix(TruecallerSdkScope.CTA_TEXT_PREFIX_USE)
        .buttonShapeOptions(TruecallerSdkScope.BUTTON_SHAPE_ROUNDED)
        .privacyPolicyUrl("<<YOUR_PRIVACY_POLICY_LINK>>")
        .termsOfServiceUrl("<<YOUR_PRIVACY_POLICY_LINK>>")
        .footerType(TruecallerSdkScope.FOOTER_TYPE_NONE)
        .consentTitleOption(TruecallerSdkScope.SDK_CONSENT_TITLE_LOG_IN)
        .sdkOptions(TruecallerSdkScope.SDK_OPTION_WITHOUT_OTP)
.build();          

TruecallerSDK.init(trueScope);

You will find complete details on the configuration options in the TruecallerSdkScope object as described above, and all the possible available values in the immediate next section of this documentation here.

Truecaller SDK needs to be initialised only once and the same instance can be accessed at any place within your app, without the need to initialise it again, via TruecallerSDK.getInstance()

Once you initialise the TruecallerSDK using the init() method, if you are using the SDK for verification of only Truecaller users ( by setting the sdkOptions scope as TruecallerSdkScope.SDK_OPTION_WITHOUT_OTP ), you can check if the Truecaller app is present on the user's device or not by using the following method

Copy

TruecallerSDK.getInstance().isUsable()

You can trigger the Truecaller profile verification dialog anywhere in your app flow by calling the following method

Copy

TruecallerSDK.getInstance().getUserProfile() 

You can trigger the Truecaller profile verification dialog anywhere in your app flow by calling the following method

Copy

TruecallerSDK.getInstance().getUserProfile() 

In case isUsable() method returns false, implying that Truecaller app is not present on the device, you can take the user to your app screen and continue with the verification flow for non-Truecaller users OR choose to use your own verification flow [ Refer image below ].

Truecaller SDK provides you with capabilities to configure the following :

TruecallerSdkScope trueScope = new TruecallerSdkScope.Builder(this, sdkCallback)
        .consentMode(TruecallerSdkScope.CONSENT_MODE_BOTTOMSHEET)
        .buttonColor(Color.parseColor("<<YOUR_DESIRED_COLOR_HEX_CODE>>"))
        .buttonTextColor(Color.parseColor("<<YOUR_DESIRED_COLOR_HEX_CODE>>"))
        .loginTextPrefix(TruecallerSdkScope.LOGIN_TEXT_PREFIX_TO_GET_STARTED)
        .loginTextSuffix(TruecallerSdkScope.LOGIN_TEXT_SUFFIX_PLEASE_VERIFY_MOBILE_NO)
        .ctaTextPrefix(TruecallerSdkScope.CTA_TEXT_PREFIX_USE)
        .buttonShapeOptions(TruecallerSdkScope.BUTTON_SHAPE_ROUNDED)
        .privacyPolicyUrl("<<YOUR_PRIVACY_POLICY_LINK>>")
        .termsOfServiceUrl("<<YOUR_PRIVACY_POLICY_LINK>>")
        .footerType(TruecallerSdkScope.FOOTER_TYPE_NONE)
        .consentTitleOption(TruecallerSdkScope.SDK_CONSENT_TITLE_LOG_IN)
        .sdkOptions(TruecallerSdkScope.SDK_OPTION_WIHTOUT_OTP)
.build();          

Contextual text prefix [ .loginTextPrefix() ] To provide appropriate context of verification to the Truecaller user, use one of the below mentioned TruecallerSdkScope values to show the corresponding message to the user.

Contextual text suffix [ .loginTextSuffix() ] To provide appropriate context of verification to the Truecaller user and set the suffix string

Button text options [ .ctaTextPrefix() ] To set the prefix on the CTA button

Button shape [ .buttonShapeOptions() ] To chose the shape of the CTA button

Footer CTA text [ .footerType() ] To configure the text of the additional footer CTA present at the bottom

Privacy policy text [ .privacyPolicyUrl() ] To add your privacy policy link on the verification screen ( optional ), you can configure the respective hyperlink as mentioned below

Copy

.privacyPolicyUrl("<<YOUR_PRIVACY_POLICY_LINK>>")

Terms of service text [ .termsOfServiceUrl() ] To add your terms of service link on the verification screen ( optional ), you can configure the respective hyperlink as mentioned below

Copy

.termsOfServiceUrl("<<YOUR_TERMS_OF_SERVICE_LINK>>")

Language To customise the profile dialog in any of the supported Indian languages To do so, add the following lines before calling the "getUserProfile()" method as mentioned in the previous step

Copy

Locale locale = new Locale("ru");
TruecallerSDK.getInstance().setLocale(locale);

Currently supported languages :

To ensure the authenticity of interactions between your app and Truecaller, you need to generate an app key [ partner key ] from Truecaller developer account by adding your app name, package name and app SHA-1.

To generate a new app key for your Android app, go to the 'MANAGE APPS' section on the developer account dashboard and click on 'CREATE APP'. Select 'Android' in the App type and continue to enter your app details.

You package name corresponds to the applicationId in your app level build.gradle file.

You can get to know the SHA1 for your different app builds by following these steps :

• Open your project in android studio

• Click on gradle menu on the right side and expand it

• Click on android and then signing report

You should be able to see the SHA1 fingerprint of your different build configurations [ debug /release ] in the terminal window within android studio.

Once you input your app details and create the app, you will be able to see a unique "appKey" for your app which you need to include in your project to authorise all verification requests.

Advanced steps for validating the request-response correlation:

Every request sent via a Truecaller app that supports Truecaller SDK has a unique identifier. This identifier is bundled into the response for assuring a correlation between a request and a response. If you want you can check this correlation yourself by:

1. You can use your own custom request identifier via the TrueClient with TruecallerSDK.getInstance().setRequestNonce(customHash);

Note : The customHash must be a base64 URL safe string with a minimum character length of 8 and maximum of 64 characters

2. In ITrueCallback.onSuccesProfileShared(TrueProfile) verify that the previously generated identifier matches the one in TrueProfile.requestNonce.

IMPORTANT: Truecaller SDK already verifies the request-response correlation before forwarding it to the your app.

Common scenarios to check for in you app verification flow for non-Truecaller users

If the user does not have the Truecaller app present on their device or they chose to verify using a different number than the one already verified on Truecaller app currently, they can be taken to this flow in which we provision the verification of the user by sending missed call using our infrastructure.

User verifying via Truecaller's missed call mechanism for the very first time

Proceed to the flow where the user needs to input their mobile number. Give the necessary permissions ( as described here ) and proceed with the verification. You would receive a missed call on the device which gets automatically detected by the SDK. Post this, you need to pass the user's first name and last name to the SDK to complete the verification

User verifying via OTP mechanism ( if users deny phone permissions, as described here )

In case the user denies the needed permission in the above step, the means of verification would fallback to SMS based OTP instead of missed call. In that case, you can chose to implement your own fallback OTP infrastructure or opt for Truecaller's fallback SMS based OTP infrastructure. If you have opted for your own SMS infrastructure, you can chose to proceed as per your own flow. In case you have opted for Truecaller's SMS based OTP infrastructure, when you request for a verification for the user's number, Truecaller sends an SMS to the user containing the OTP. Once the OTP is keyed in by the user or automatically read ( using the SDKs SMS retriever functionality ), you need to pass the user's first name and last name along with the OTP to the Truecaller SDK method to complete the verification flow.

User already verified with the same credentials previously on the smartphone

Once a user's verification is completed successfully on a particular device, and they re-attempt to verify on the same app using the same credentials ( same smartphone, same mobile number ), Truecaller SDK is able to identify the user and we can tell you it's the same user. In this case, no additional missed call / OTP is needed to re-verify the user. The SDK will directly tell the status of the repeat user, and in this case returns the first name and last name of the user back to you in response.

Common scenarios to check for in you app verification flow for existing Truecaller users:

Truecaller app present and registration completed on Truecaller app

Ensure that the Truecaller app is present on your device and you have completed the profile creation step on Truecaller app. Open your app and initiate the Truecaller verification flow. The user should see the Truecaller profile dialog. Click on continue to complete the verification flow and ensure that the verification is completed.

Truecaller app present but registration not completed on Truecaller app

Ensure that the Truecaller app is present on your device but you have not completed the profile creation step on Truecaller app. Open your app and initiate the Truecaller verification flow. The user should not see the Truecaller profile dialog, and you would receive the control in onFailureProfileShared() with the specific error code.

Truecaller app not present on the device

Remove the Truecaller app from your device. Open your app and try to initiate the Truecaller verification flow. The user should not see the Truecaller profile dialog and should be taken to either your alternate verification flow or in case you are using Truecaller SDK's functionality of verifying non-Truecaller users, user should be redirected to that flow.

Network not available on device

Ensure that the Truecaller app is present on your device and you have completed the profile creation step on Truecaller app. Turn off the mobile data and WiFi on your device. Open your app and initiate the Truecaller verification flow. You would see the Truecaller profile dialog. Click on continue button on the dialog, you would receive control in onFailureProfileShared() method with a specific error code.

Partner key should be working fine ( onFailureProfileShared() Error Type 3 )

For complete details on this part, please refer here

User wishes to proceed with another number OR does not want to share their Truecaller profile

Initiate the Truecaller verification flow in your app to invoke the Truecaller profile dialog. Click on system back or Use another mobile number button on the dialog to dismiss the dialog. In such a scenario, user should be taken to either your alternate verification flow or in case you are using Truecaller SDK's functionality of verifying non-Truecaller users, user should be redirected to that flow.

We also recommend that you go through the FAQ section to go through some of the commonly asked questions

Recommended Steps for validating the authenticity of SDK response at your server side:

Truecaller SDK already verifies the authenticity of the response before forwarding it to your app. However, if you wish to additionally check the authenticity of the response at your end, you can do so.

In the response for TrueProfile we return -

• Payload, which is a Base64 encoding of the json object containing all profile info

• Signature, which contains the payload's signature . Signature is generated by applying signing algorithm with our private key

• Signature Algorithm in the response header

To verify the payload, our public key for a given algorithm can be fetched using this API: https://api4.truecaller.com/v1/key.

Using the payload, the signature and the public key, you can verify that the content sent is authentic through the following flow:

a. Apply verification, which means apply our public key to the signature (with given algorithm) and comparing result with payload

b. If verified, you would know that response comes from Truecaller's backend and is authentic. The profile can then be used as base64 decoding of the payload.

For details on the verification flow and sample code snippets in different programming languages, please refer this link

In order to add another layer of security, you can also put a check to identify if the payload that is passed on to your server was initially generated for your app (package name) itself. The payload that you receive in the success response has a field with a key as “verifier”. Here, you need to generate HMAC SHA256 of your package name, using your appKey (partner key) as a secret. (The appKey mentioned here is the one that you generate from our developer portal). The output that you get from above should match the verifier value received in the payload. In case it doesn't, which means that the payload that was generated was tampered.

In case you are using the app signing feature of google play store, when you upload your release build to the google play store, it assigns a new SHA1 fingerprint to your app - which might lead to UNAUTHORISED_PARTNER_KEY error for your app, since the appKey used by you in your app config was generated for a different SHA1, and hence won't work for the new SHA1.

In this scenario, you need to go to the "app integrity section" of the Google play console, where you would see 2 SHA1 keys (a) Upload Certificate SHA1 and (b) App Signing Certificate SHA1.

You need to note down the "App Signing Certificate SHA1" from the console, and generate a new Truecaller partner key ( app key ) for your play store build. Configure this key for your play store build in your project, and upload the build on play store for your users.

Once the SDK shares the accessToken for any user verified via drop call / OTP based verificaiton flow, you can verify the authenticity of the access token by making API call from your server to Truecaller's server. The following endpoint will return phone number and country code for the given access token.

API Endpoint:

Copy

"https://sdk-otp-verification-noneu.truecaller.com/v1/otp/installation/phoneNumberDetail/{accessToken}"

REQUEST :

Method : GET

Header Parameters:

Request Path Parameters:

RESPONSE:

• 200 OK - If access token is valid

Copy

{
    "phoneNumber":919999XXXXX9
    "countryCode":"IN"
}

• 404 Not Found - If your credentials are not valid

Copy

{
    "code":404
    "message":"Invalid partner credentials."
}

• 404 Not Found - If access token is invalid

Copy

{
    "code":1404
    "message":"Invalid access token."
}

• 500 Internal Error - for any other internal error

Copy

{
    "code":500
    "message":"error message"
}

While you start integrating Truecaller SDK, as the very first step, it is important to work on designing the right user flow, so that you can achieve desired results.

Truecaller SDK is a mobile number verification service, without the need for any OTP whatsoever.

The right way to implement Truecaller SDK in your mobile app, is to invoke mobile number verification via Truecaller at touch points, where you have your users to sign-up/ login/ checkout by verifying their mobile numbers.

When mobile apps onboard their users, there are multiple ways in which they address the onboarding process. For example, one could address it as Get Started, Join Us, Login, Sign up, etc., shown as a button to the users, clicking which leads to the mobile number based identity verification of users.

Here is such an example from NoBrokerHood - India’s leading visitor management platform:

Building for Various Touch points

a. Invoking user signup/ login/ verification via Truecaller at app onboarding Example : NoBroker - India’s leading realty app

When mobile apps onboard their users, there are multiple ways in which they address the onboarding process. For example, one could address it as Get Started, Join Us, Login, Sign up, etc., shown as a button to the users, clicking which leads to the mobile number based identity verification of users. Here is such an example from NoBroker:

b. Directly invoking verification via Truecaller Example : Vyapar - India's fastest growing Invoice & Billing app for small businesses

Vyapar has mobile number as the primary identifier for its users. So as soon as users lands on their mobile number login/ signup screen, it invokes Verification via Truecaller, and onboards it’s users within seconds in just 1-tap.

c. Performing user verification at checkout Example : Chalo - available in 25+ cities, tracks buses live and tells you what time your bus will reach your stop

Chalo allows users to browse through it’s app and check for bus ETAs, without needing to sign-up or log-in. However, when users wish to purchase the ticket or travel pass, it requires users to verify their mobile number.

Now that we have gone through and understood how to implement Verification via Truecaller, let’s get started with the SDK integration.

Failure/ Error responses

The "onFailureProfileShared" callback method that you just implemented in the previous step helps you to handle all the possible failure cases when the user couldn't be verified successfully via the Truecaller flow.

Below are some of the possible failure scenarios and the corresponding error response that you receive for each of the cases :

*Error Type 4 and Error Type 10 could arise in different conditions depending on whether the user has not registered on Truecaller app on their smartphone or if the user has deactivated their Truecaller profile at any point of time from the app.

Apart from the above mentioned error cases, there are few other error scenarios that you may encounter under rare circumstances. For complete and exhaustive list of all the error cases, you can refer to TrueError.class within the SDK.

Please note that when you encounter any of the error scenarios and get the control in the "onFailureProfileShared()" method, you should redirect the user to your alternate verification flow.

Exceptions

In case you face any of the following run time exceptions, please follow the recommended steps as mentioned below :

"No compatible client available. Please change your scope"

As the exception suggests, you are trying to call an SDK method even though no client is available to handle it. This usually happens if you have initialised the SDK using WITHOUT_OTP scope option i.e to verify only the Truecaller users, and you are not calling isUsable() method before calling an SDK method. To resolve this, call isUsable() before calling any SDK method if you are using WITHOUT_OTP scope option

"Please call init() on TruecallerSDK first"

This exception suggests that you are trying to call an SDK method before the SDK has been initialised. To resolve it, check for all possible user flows in your app which could lead to calling an SDK method directly before it has been initialised.

Truecaller SDK enables you to verify your user's mobile number in a seamless way. For users who have Truecaller app present on their smartphones and are already registered Truecaller users, they get verified in a 1-tap flow (supported globally), without the need of any manual input. For users who don't have Truecaller app present on their smartphones, the SDK enables user verification by means of drop call, which is triggered to the user's number in background to complete the verification flow (currently supported only for India).

To understand various possible user scenarios in the user's verification flow, let's try to take example of NoBrokerHood, India's leading realty app. NoBrokerHood is using Truecaller SDK for verifying numbers of all their users.

Scenario 1

a) New user on NoBrokerHood app, and

b) Truecaller app present on user's smartphone.

Scenario 2

a) Existing user on NoBrokerHood app, and

b) Truecaller app present on smartphone.

Scenario 3

a) New user on NoBrokerHood app, and

b) Truecaller app NOT present on smartphone, and user's mobile number NOT already verified on smartphone.

Scenario 4

a) Existing user on NoBrokerHood app, and

b) Truecaller app NOT present on smartphone and user's mobile number NOT verified on smartphone.

Scenario 5

a) Existing user on NoBrokerHood app, and

b) Truecaller app NOT present on smartphone and user's mobile number ALREADY verified on smartphone.

Changelog for Truecaller android SDK versions 2.8.0 and below :

Quick guide on getting your test setup ready to test the common verification scenarios as described in previous sections:

Pre-Requisites

• We suggest you to keep handy at-least 2 android smartphones with active SIM connections. Ensure that both the smartphones have your test app installed (Integrated with Truecaller SDK)

• 2 different smartphones are required so that in case you get verified on one of the smartphones, you can use the second smartphone to check for the fresh verification scenarios.

Steps to follow for testing user scenarios :

Truecaller SDK versions lower than v2.7.0 use device ID and SIM serial identifiers for the non-Truecaller user verification flow ( drop call based verification ). With the v2.7.0 release, we have removed dependency on these attributes. As per the recent Google play store app policy changes, apps shouldn’t use these identifiers in conjunction with the phone number. Google Play sends your app a warning in case your app ( including any integrated 3rd party libraries ) is using these identifiers.

If you are using Truecaller SDK version less than v2.7.0, we recommend you to update the same to 2.70 and above. Once you upgrade the SDK version, the above mentioned issue around play store publishing would be resolved.

The latest SDK version is completely in line to google play’s new data privacy policies and hence has been listed on the google play SDK index as well. Only policy compliant SDKs are listed on the SDK index.

This section is only relevant for apps who are using the Truecaller SDK for verifying non-Truecaller user as well and seek phone permissions from the users

If you are using the functionality of verifying non Truecaller users also via the SDK, your app would need specific phone permissions as has been described in this . If you are using the Truecaller SDK for verification of existing Truecaller users only ( 1-tap flow ), you can skip this section.

As you upload the new app build to PlayStore with user verification feature via Truecaller SDK and the requisite permissions, you might be asked to fill an app permission declaration form.

We are sharing some tips on how to appropriately justify the need for these permissions for your verification flow :

#1: In one sentence, please describe the core functionality of your app. To be defined by you as a publisher of your app

#2: What is the core functionality in your app requiring the Call Log and / or SMS permissions? Mobile number verification to onboard users on <your_app>

This is in-line with Google’s allowed usage of this permission for account verification via phone call, as stated here: https://support.google.com/googleplay/android-developer/answer/9047303 Flow: a)Enter mobile number b)Request READ_CALL_LOG permission c)Initiate drop call from 3rd party service to respective number d)Drop call hits user’s device and is rejected automatically via above permission to complete verification

#3: Do any of the following disallowed use cases apply to your app’s core functionality request for Call Log or SMS permissions? NO

#4: Do any of the following other use cases apply to your app’s core functionality request for Call Log or SMS permissions? OTP & Account verification via Phone Call (select this from the given list of options)

#5: Is your app’s use of Call Log or SMS permissions to provide functionality required by law or regulation? No

#6: Other We use drop call based verification of users’ mobile number for account creation or logging into their <your app name> accounts. Such method of mobile number verification results in better verification success rates in our key markets like India, etc.

Android guidelines for asking app permissions from user