Here are some advantages of using Truecaller SDK:

• Increase successful verification/ signup/ login attempts with already mobile number verified Truecaller users.

• Avoid user drop-off and app abandonment with 1-tap, instant verification - without any OTP SMS whatsoever.

• Simple, ZERO effort flow and avoid typos as users do not even need to type mobile number.

• Auto-fill user registration form by capturing mapped user profile (user name, email ID, city, etc.) post their consent.

• Achieve easy user activation and quick checkout with less number of steps/ screens.

• Optimize marketing spends and ROI by by reducing user drops resulting from failed/ delayed SMS OTP and multiple steps.

Welcome to Truecaller SDK documentation!

Here you will find answers to all your queries on how to easily integrate Verification via Truecaller feature into your mobile app and mobile sites.

What is Truecaller SDK?

Truecaller SDK is a mobile number verification service, which you can use wherever you look to verify your users.

With more than 400+ million users globally, Truecaller is the largest mobile number identity platform.

This means that these 400+ million users who have Truecaller mobile app on their mobile devices, have created their profiles with Truecaller by verifying their mobile numbers, and associating their identity.

Since these users are already mobile number verified, verification via Truecaller enables you to quickly verify/ signup/ login your users, basis their mobile number - without the need of any SMS based OTP, and at the same time capture their mapped user profile.

Along with this, the SDK also gives you an option to verify users who do not have the Truecaller app present on their devices, via the means of a drop call being triggered to the user's device in background

You should start by creating your developer account on the Truecaller Developer portal here: https://sdk-console-noneu.truecaller.com/sign-up

a) Register with email ID and set a password.

b) Verify your email ID to proceed.

PS: The developer portal link shared above is only for registering android apps, if you are looking to do the integration in Mobile Site, iOS or any other platform please sign via this developer portal link : https://verification-sdk-console.truecaller.com/sign-up

If you already have created your developer account, please login here.

To reset your account password, please request for it here.

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 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.

1. Create a TcSdkOptions object by using the tcOAuthCallback from the previous step and provide the context. Supply the appropriate customization settings to the relevant methods of TcSdkOptions and use the instance of tcSdkOptions to initialize the TcSdk in the next step.

val tcSdkOptions = TcSdkOptions.Builder(this, tcOAuthCallback)
.buttonColor(Color.parseColor("<<VALID_COLOR_HEX_CODE>>"))
          .buttonTextColor(Color.parseColor("<<VALID_COLOR_HEX_CODE>>"))
            .loginTextPrefix(TcSdkOptions.LOGIN_TEXT_PREFIX_TO_GET_STARTED)
            .ctaText(TcSdkOptions.CTA_TEXT_CONTINUE)
            .buttonShapeOptions(TcSdkOptions.BUTTON_SHAPE_ROUNDED)
            .footerType(TcSdkOptions.FOOTER_TYPE_SKIP)
            .consentTitleOption(TcSdkOptions.SDK_CONSENT_TITLE_LOG_IN)
            .sdkOptions(TcSdkOptions.OPTION_VERIFY_ONLY_TC_USERS)
            .build();

In case you do not wish to provide any customization settings and fall back to the default SDK settings, you may simply call -

val tcSdkOptions = TcSdkOptions.Builder(this, tcOAuthCallback).build()

1. Initialize TcSdk using the tcSdkOptions from the previous step :

TcSdk.init(tcSdkOptions)

Note: Truecaller OAuth SDK needs to be initialized only once in the component and the same instance can be accessed without the need to initialize it again, via TcSdk.getInstance()

Ideally, you should call the init() method when the component is getting created/initialized to avoid calling it multiple times.

The SDK init should always happen in a background thread. You can refer to an example snippet below _{[Recommended]} :

launch {
  withContext(Dispatchers.IO) {
     TcSdk.init(tcSdkOptions)
   }
// Now can access TcSdk.getInstance()
}

1. Once the SDK is initialized, check whether the OAuth functionality is usable or not by calling :

val isUsable = TcSdk.getInstance().isOAuthFlowUsable

If isUsable is True, you can proceed with further steps, otherwise, you’d have to fall back to some other mechanism ( your fallback verification flow ). Calling other SDK methods when isUsable is False would result in an exception, so please ensure to call this soon after initializing the SDK, and proceed to further steps only if this method returns True.

Make a network call to fetch the userInfo using access token from step 14. The response would be corresponding to the scopes granted by the user.

GET https://oauth-account-noneu.truecaller.com/v1/userinfo

Headers

200: OK

{

“sub”: “13627101294235520", “given_name”: “xyz”, “family_name”: “xyz”, “phone_number”: “91xxxxxxxxxx", “email”: “[email protected]”, “picture”: “https://www.truecaller.com/xyz”, “gender”: “male/female”, “phone_number_country_code”: “IN”, “phone_number_verified”: true, ˇ“address”: { “locality”: “Bangalore”, “postal_code”: “5xxxxx" } }

401: Unauthorized If authentication type is not bearer token

404: Not Found Profile information is not present for the user

500: Internal Server Error Failed to validate token due to server error

401: Unauthorized Token in invalid/ expired

422: Unprocessable Entity openid scope missing in initial request

500: Internal Server Error Unexpected error at server side

Sample cURL request :

curl --location --request GET 'https://oauth-account-noneu.truecaller.com/v1/userinfo' \
--header 'Authorization: Bearer testtoken'

• Register on the OAuth portal to create your business account and manage OAuth projects.

• Once you have created your account, create your OAuth project & generate credentials by following the steps here.

• Once you have generated the credentials, you can easily, in a few simple steps integrate the Truecaller SDK by referring to our step-by-step guide in the subsequent sections.

• Post integration completion, submit your project for review and go live.

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

TcSdk.getInstance().getAuthorizationCode(this, launcher)

where the launcher is derived in step 5 (Implementing Callback) In case isOAuthFlowUsable() method returns false, implying that the 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 implement your fallback verification mechanism.

In order to clear the resources taken up by the SDK, you may use the following method

TcSdk.clear()

Ideally, you should call this method when the component in which you initialized the SDK is getting killed/destroyed.

For instance, if you have initialized the SDK in the onCreate() method of the activity lifecycle, then you need to call clear it in the onDestroy() method of the activity lifecycle.

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.

Let us now see an example to understand how to effectively use Truecaller SDK at such touch points in your user journey

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 CentroStore - our very own in-house sample app:

Building for Various Touch points

a. Invoking user signup/ login/ verification via Truecaller at app onboarding

Example: CentroStore - our very own in-house sample 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 CetroStore.

b. Directly invoking verification via Truecaller

Example : CentroStore - our very own in-house sample app

CentroStore 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 : CentroStore - our very own in-house sample app

CentroStore also 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.

To ensure the authenticity of interactions between your app and Truecaller, you need to generate a client ID from the Truecaller developer portal by following the steps below:

• Go to https://sdk-console-noneu.truecaller.com/login and register your account.

• Once registered, log in to your account and click on the "create project” button.

• Enter the project name and select the business category from the dropdown menu. This will create a new project.

• On the project screen, click the “add credential” button and select the platform as Android from the dropdown menu.

• On the credential section, enter the package name and the SHA1.

• Your 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

• Open terminal

• Type command ./gradlew signingReport

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

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

Truecaller SDK enables you to verify your user's mobile number in a seamless way. For users who have the 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 the Truecaller app present on their smartphones, the SDK enables user verification by means of a drop call, which is triggered to the user's number in the 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 the example of CentroStore. CetroStore is using Truecaller SDK for verifying the numbers of all their users.

Scenario 1

a) New user on CentroStore app and

b) Truecaller app present on user's smartphone

Scenario 2

a) Existing user on CentroStore app, and

b) Truecaller app present on smartphone

Scenario 3

a) New user on CentroStore app, and

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

Scenario 4

a) Existing user on CentroStore app, and

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

Using the “state” from step 10, “code verifier” from step 12, and the “authorization code” from step 9, you need to make a network call to Truecaller’s backend so as to fetch the access token :

POST https://oauth-account-noneu.truecaller.com/v1/token

Headers

Request Body

200: OK Success

{ "access_token": "some-access-token", "expires_in": 3600, "token_type": "Bearer" }

400: Bad Request - If grant type is not supported 403: Forbidden - If client id is invalid 500: Internal Server Error - Unexpected error on the server side 400: Bad Request - Some of the parameters are empty in the request 403: Forbidden Valid grant type but not allowed for the client 403: Forbidden Invalid auth code provided 403: Forbidden Invalid/expired auth code in provided 403: Forbidden Invalid/expired code verifier is provided 429: Too Many Requests If the number of requests exceeds the allowed limit 503: Service Unavailable Resource unavailable due to server-side issue

Sample cURL request :

1. Ensure that your Minimum SDK version is at least API level 24 or above. In case your android project compiles for API level below 24, you can include the following line in your AndroidManifest.xml file to avoid any compilation issues : <uses-sdk tools:overrideLibrary="com.truecaller.android.sdk"/> Using this would ensure that the SDK works normally for API level 24 & above, and would be disabled for API level < 24. Note: Please make sure that you put the necessary API level checks before accessing the SDK methods in case of compiling for API level < 24

2. 2.1) Add the Truecaller SDK which contains OAuth functionality to your app-level build.gradle file dependencies {

   ...

   implementation "com.truecaller.android.sdk:truecaller-sdk:3.2.0"

   } 2.2) Also, add the following lines of code in your gradle file, if not already present android{

   compileOptions{

   sourceCompatibility JavaVersion.VERSION_1_8

   targetCompatibility JavaVersion.VERSION_1_8

   }

   }

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

   allprojects{

   repositories{

   ...

   mavenCentral()

   ...

   } Also check your AGP and distribution URL version AGP : 7.4.2 (minimum) distributionUrl=https\:// (minimum).

4. Configure Client ID :

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

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

<application android:label="@string/app_name" ...>

...

<meta-data android:name="com.truecaller.android.sdk.ClientId" android:value="@string/clientID"/>

...

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.

Client ID should be working fine ( onFailure() Error Type 12)

For complete details on this part, please refer .

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 to go through some of the commonly asked questions.

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

Please note that the first name and last name values to be passed in the above method call need to follow below mentioned rules :

• The strings need to contains at least 1 alphabet, and cannot be completely comprised of numbers or special characters.

• String length should be less than 128 characters.

• First name is a mandatory field, last name can be empty ( but non nullable ).

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

Please note that Truecaller SDK 3.1.0 is not by default enabled for the IM OTP flow. This new update is currently under early access. In case you want to enable it for your app, please drop in a request at [email protected]

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

Once the SDK shares the accessToken for any user verified via drop call based verification 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:

REQUEST :

Method : GET

Header Parameters:

Request Path Parameters:

RESPONSE:

• 200 OK - If access token is valid

• 404 Not Found - If your credentials are not valid

• 404 Not Found - If access token is invalid

• 500 Internal Error - for any other internal error

1. Set a unique state parameter & store it in the current session to use it later in the onSuccess() callback method of the TcOAuthCallback to match if the state received from the authorization server is the same as set here to prevent request forgery attacks.

One good choice for a state token is a string of around 32 characters constructed using a high-quality random-number generator as we did above. Another approach could be a hash generated by signing some of your session state variables with a key that is kept secret on your back-end.

1. Set the list of scopes to be requested.

1. Generate a unique code verifier & store it in the current session since it would be required later to generate the access token. It can be generated using the utility class CodeVerifierUtil provided in the SDK.

This utility method generates a random code verifier string using SecureRandom as the source of entropy with 64 as the default entropy quantity.

1. Set the corresponding code challenge using the code verifier generated in the previous step. This can be generated using the utility class CodeVerifierUtil provided in the SDK.

This utility method produces a code challenge from the supplied code verifier using SHA-256 as the challenge method and Base64 as encoding if the system supports it (all Android devices should ideally support SHA-256 and Base64), but in rare case if the device doesn’t, then this method would return null meaning that you can’t proceed further. Please ensure to have a null safe check for such cases.

1. In your Activity/Fragment where you want to integrate the Truecaller OAuth flow, either make the component implement the interface TcOAuthCallback or create an instance of it which you would require to initialize TcSdkOptions in the next step.

The interface has 2 functions which need to be overridden -

• onFailure() method will be called in case of an error. You would get the error details like the error code and error message through tcOAuthError returned with this method.

• onSuccess() method will be called when the user gives consent to authorize your app by tapping on the primary button on the Truecaller’s consent screen, and subsequently, an authorization code will be successfully generated and received. This method would return tcOAuthData, which contains information like : Auth Parameters [Live]

  • authorizationCode - which you can utilize to fetch the user’s access token

  • scopesGranted - list of scopes granted by the user

  • state - state parameter returned by the authorisation server. If the state set by your application is the same as the state returned by the authorisation server, it’s safe to proceed further. If state parameters are different, someone else has initiated the request, and it could be a case of request forgery.

  [New] Sim and Device Info Parameters [EAP - for access, mail us at [email protected]]

  • Sim Status - This will be a parameter returned to you in successCallback, which helps understand whether the number passed to you is actually present on the device at the time of verification. In case it is present, the variable returns 1, In case it's not present, the variable returns 0, and in case, due to OS level restrictions, the SDK is not able to detect it, the variable returns -1

  • Device Code - This parameter helps you tie the number onboarded on your platform to a particular device identifier. This parameter for a user on a device will always be the same until the Truecaller profile is changed on that very device OR the user is using some other device to verify their number.

1. Call onActivityResultObtained() within the registerForActivityResult() like below:

and then assign it to a variable _{(Ex: launcher)} to use it under step 13 ().

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. 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 TcSdk.getInstance().isOAuthFlowUsable 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 TcOAuthData response in onSuccess() callback method ]

5. Number of cases where you received any error, where you receive an error callback with TcOAuthError response in onFailure() 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):

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 ) - a.) When the callback type you receive is VerificationCallback.TYPE_MISSED_CALL_INITIATED. This implies that a drop call has been triggered to the user's mobile number b.) When the callback type you receive is VerificationCallback.TYPE_MISSED_CALL_RECEIVED. This implies that a drop call has been received on the user's mobile number on that smartphone c.) Further to the above step, you complete the user verification by invoking TcSdk.getInstance().verifyMissedCall(profile, verificationCallback) When the callback type you receive is either VerificationCallback.TYPE_VERIFICATION_COMPLETE. This implies that the verification is complete for the user d.) 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.

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

TcSdk.getInstance().getAuthorizationCode(this, launcher)

where the launcher is derived in step 5 (Implementing Callback) In case isOAuthFlowUsable() method returns false, implying that the 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 implement your fallback verification mechanism.

• Register on the OAuth portal to create your business account and manage OAuth projects.

• Once you have created your account, create your OAuth project & generate credentials by following the steps here.

• Once you have generated the credentials, you can easily, in a few simple steps integrate the Truecaller SDK by referring to our step-by-step guide in the subsequent sections.

• Post integration completion, submit your project for review and go live.

Failure/ Error responses

The "onFailure" 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 :

Please note that when you encounter any of the error scenarios and get the control in the "onFailure()" 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 initialized the SDK using ONLY_TC_USERS scope option i.e to verify only the Truecaller users, and you are not calling isOAuthFlowUsable() method before calling an SDK method. To resolve this, call isOAuthFlowUsable() before calling any SDK method if you are using VERIFY_TC_USERS 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.

"Add client id in your manifest"

This exception suggests that you are trying to call SDK initialization/build method without having your clientID mentioned in your manifest as meta-data.

"OAuth scopes cannot be null or empty"

This exception suggests that you are trying to call SDK method - getAuthorisationCode before setting up the OAuth scopes.

"OAuth state cannot be null or empty"

This exception suggests that you are trying to call SDK method - getAuthorisationCode before setting up the OAuth state.

“Code challenge cannot be null or empty”

This exception suggests that you are trying to call SDK method - getAuthorisationCode before setting up the Code challenge.

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 enables you to verify your user's mobile number in a seamless way. For users who have the 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 the Truecaller app present on their smartphones, the SDK enables user verification by means of a drop call, which is triggered to the user's number in the 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 the example of CentroStore. CetroStore is using Truecaller SDK for verifying the numbers of all their users.

Scenario 1

a) New user on CentroStore app and

b) Truecaller app present on user's smartphone

Scenario 2

a) Existing user on CentroStore app, and

b) Truecaller app present on smartphone

Scenario 3

a) New user on CentroStore app, and

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

Scenario 4

a) Existing user on CentroStore app, and

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

1. Set a unique state parameter & store it in the current session to use it later in the onSuccess() callback method of the TcOAuthCallback to match if the state received from the authorization server is the same as set here to prevent request forgery attacks.

One good choice for a state token is a string of around 32 characters constructed using a high-quality random-number generator as we did above. Another approach could be a hash generated by signing some of your session state variables with a key that is kept secret on your back-end.

1. Set the list of scopes to be requested.

1. Generate a unique code verifier & store it in the current session since it would be required later to generate the access token. It can be generated using the utility class CodeVerifierUtil provided in the SDK.

This utility method generates a random code verifier string using SecureRandom as the source of entropy with 64 as the default entropy quantity.

1. Set the corresponding code challenge using the code verifier generated in the previous step. This can be generated using the utility class CodeVerifierUtil provided in the SDK.

This utility method produces a code challenge from the supplied code verifier using SHA-256 as the challenge method and Base64 as encoding if the system supports it (all Android devices should ideally support SHA-256 and Base64), but in rare case if the device doesn’t, then this method would return null meaning that you can’t proceed further. Please ensure to have a null safe check for such cases.

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

Please note that the first name and last name values to be passed in the above method call need to follow below mentioned rules :

• The strings need to contains at least 1 alphabet, and cannot be completely comprised of numbers or special characters.

• String length should be less than 128 characters.

• First name is a mandatory field, last name can be empty ( but non nullable ).

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

Please note that Truecaller SDK 3.1.0 is not by default enabled for the IM OTP flow. This new update is currently under early access. In case you want to enable it for your app, please drop in a request at [email protected]

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.

Client ID should be working fine ( onFailure() Error Type 12)

For complete details on this part, please refer .

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 to go through some of the commonly asked questions.

1. Create a TcSdkOptions object by using the tcOAuthCallback from the previous step and provide the context. Supply the appropriate customization settings to the relevant methods of TcSdkOptions and use the instance of tcSdkOptions to initialize the TcSdk in the next step.

In case you do not wish to provide any customization settings and fall back to the default SDK settings, you may simply call -

1. Initialize TcSdk using the tcSdkOptions from the previous step :

Note: Truecaller OAuth SDK needs to be initialized only once in the component and the same instance can be accessed without the need to initialize it again, via TcSdk.getInstance()

Ideally, you should call the init() method when the component is getting created/initialized to avoid calling it multiple times. The SDK init should always happen in a background thread.

1. Once the SDK is initialized, check whether the OAuth functionality is usable or not by calling :

If isUsable is True, you can proceed with further steps, otherwise, you’d have to fall back to some other mechanism ( your fallback verification flow ). Calling other SDK methods when isUsable is False would result in an exception, so please ensure to call this soon after initializing the SDK, and proceed to further steps only if this method returns True.

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

In case isOAuthFlowUsable() 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.

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 ) 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 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.

• Register on the OAuth portal to create your business account and manage OAuth projects.

• Once you have created your account, create your OAuth project & generate credentials by following the steps here.

• Once you have generated the credentials, you can easily, in a few simple steps integrate the Truecaller SDK by referring to our step-by-step guide in the subsequent sections.

• Post integration completion, submit your project for review and go live.

1. Ensure that your Minimum SDK version is at least API level 24 or above. In case your android project compiles for API level below 24, you can include the following line in your AndroidManifest.xml file to avoid any compilation issues : <uses-sdk tools:overrideLibrary="com.truecaller.android.sdk"/> Using this would ensure that the SDK works normally for API level 24 & above, and would be disabled for API level < 24. Note: Please make sure that you put the necessary API level checks before accessing the SDK methods in case of compiling for API level < 24

2. 2.1) Add the Truecaller SDK which contains OAuth functionality to your app-level build.gradle file dependencies {

   ...

   implementation "com.truecaller.android.sdk:truecaller-sdk:3.2.0"

   } 2.2) Also, add the following lines of code in your gradle file, if not already present android{

   compileOptions{

   sourceCompatibility JavaVersion.VERSION_1_8

   targetCompatibility JavaVersion.VERSION_1_8

   }

   }

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

   allprojects{

   repositories{

   ...

   mavenCentral()

   ...

   } Also check your AGP and distribution URL version AGP : 7.4.2 (minimum) distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip (minimum).

4. Configure Client ID :

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

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

<application android:label="@string/app_name" ...>

...

<meta-data android:name="com.truecaller.android.sdk.ClientId" android:value="@string/clientID"/>

...

1. In your Activity/Fragment where you want to integrate the Truecaller OAuth flow, either make the component implement the interface TcOAuthCallback or create an instance of it which you would require to initialize TcSdkOptions in the next step.

The interface has 2 functions which need to be overridden -

private val tcOAuthCallback: TcOAuthCallback = object : TcOAuthCallback {
    override fun onSuccess(tcOAuthData: TcOAuthData) {
        ..
    }

    override fun onFailure(tcOAuthError: TcOAuthError) {
        ..
    }
}

• onFailure() method will be called in case of an error. You would get the error details like the error code and error message through tcOAuthError returned with this method.

• onSuccess() method will be called when the user gives consent to authorize your app by tapping on the primary button on the Truecaller’s consent screen, and subsequently, an authorization code will be successfully generated and received. This method would return tcOAuthData, which contains information like : Auth Parameters [Live]

  • authorizationCode - which you can utilize to fetch the user’s access token

  • scopesGranted - list of scopes granted by the user

  • state - state parameter returned by the authorisation server. If the state set by your application is the same as the state returned by the authorisation server, it’s safe to proceed further. If state parameters are different, someone else has initiated the request and it could be a case of request forgery.

  [New] Sim Info Parameters[EAP - for access, mail us at [email protected]]

  • Sim Status - This will be a parameter returned to you in successCallback, which helps understand whether the number passed to you is actually present on the device at the time of verification. In case it is present, the variable returns 1, In case it's not present, the variable returns 0, and in case, due to OS level restrictions, the SDK is not able to detect it, the variable returns -1

1. Call onActivityResultObtained() within the registerForActivityResult() like below:

val launcher = registerForActivityResult(StartActivityForResult()) { result: ActivityResult ->
    TcSdk.getInstance().onActivityResultObtained(requireActivity(), result.resultCode, result.data)
}

and then assign it to a variable _{(Ex: launcher)} to use it under step 13 (Invocation).

In order to clear the resources taken up by the SDK, you may use the following method

TcSdk.clear()

Ideally, you should call this method when the component in which you initialized the SDK is getting killed/destroyed.

For instance, if you have initialized the SDK in the onCreate() method of the activity lifecycle, then you need to call clear it in the onDestroy() method of the activity lifecycle.

1. Ensure that your Minimum SDK version is at least API level 24 or above. In case your android project compiles for API level below 24, you can include the following line in your AndroidManifest.xml file to avoid any compilation issues : <uses-sdk tools:overrideLibrary="com.truecaller.android.sdk"/> Using this would ensure that the SDK works normally for API level 24 & above, and would be disabled for API level < 24. Note: Please make sure that you put the necessary API level checks before accessing the SDK methods in case of compiling for API level < 24

2. 2.1) Add the Truecaller SDK which contains OAuth functionality to your app-level build.gradle file dependencies {

   ...

   implementation "com.truecaller.android.sdk:truecaller-sdk:3.1.0"

   } 2.2) Also, add the following lines of code in your gradle file, if not already present android{

   compileOptions{

   sourceCompatibility JavaVersion.VERSION_1_8

   targetCompatibility JavaVersion.VERSION_1_8

   }

   }

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

   allprojects{

   repositories{

   ...

   mavenCentral()

   ...

   } Also check your AGP and distribution URL version AGP : 7.4.2 (minimum) distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip (minimum).

4. Configure Client ID :

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

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

<application android:label="@string/app_name" ...>

...

<meta-data android:name="com.truecaller.android.sdk.ClientId" android:value="@string/clientID"/>

...

Make a network call to fetch the userInfo using access token from step 14. The response would be corresponding to the scopes granted by the user.

GET https://oauth-account-noneu.truecaller.com/v1/userinfo

Headers

200: OK

{

“sub”: “13627101294235520", “given_name”: “xyz”, “family_name”: “xyz”, “phone_number”: “91xxxxxxxxxx", “email”: “[email protected]”, “picture”: “https://www.truecaller.com/xyz”, “gender”: “male/female”, “phone_number_country_code”: “IN”, “phone_number_verified”: true, ˇ“address”: { “locality”: “Bangalore”, “postal_code”: “5xxxxx" } }

401: Unauthorized If authentication type is not bearer token

404: Not Found Profile information is not present for the user

500: Internal Server Error Failed to validate token due to server error

401: Unauthorized Token in invalid/ expired

422: Unprocessable Entity openid scope missing in initial request

500: Internal Server Error Unexpected error at server side

Sample cURL request :

curl --location --request GET 'https://oauth-account-noneu.truecaller.com/v1/userinfo' \
--header 'Authorization: Bearer testtoken'

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 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.

• Register on the OAuth portal to create your business account and manage OAuth projects.

• Once you have created your account, create your OAuth project & generate credentials by following the steps here.

• Once you have generated the credentials, you can easily, in a few simple steps integrate the Truecaller SDK by referring to our step-by-step guide in the subsequent sections.

• Post integration completion, submit your project for review and go live.

In order to clear the resources taken up by the SDK, you may use the following method

TcSdk.clear()

Ideally, you should call this method when the component in which you initialized the SDK is getting killed/destroyed.

For instance, if you have initialized the SDK in the onCreate() method of the activity lifecycle, then you need to call clear it in the onDestroy() method of the activity lifecycle.

In order to clear the resources taken up by the SDK, you may use the following method

TcSdk.clear()

Ideally, you should call this method when the component in which you initialized the SDK is getting killed/destroyed.

For instance, if you have initialized the SDK in the onCreate() method of the activity lifecycle, then you need to call clear it in the onDestroy() method of the activity lifecycle.

To ensure the authenticity of interactions between your app and Truecaller, you need to generate a client ID from the Truecaller developer portal by following the steps below:

• Go to https://sdk-console-noneu.truecaller.com/login and register your account.

• Once registered, log in to your account and click on the "create project” button.

• Enter the project name and select the business category from the dropdown menu. This will create a new project.

• On the project screen, click the “add credential” button and select the platform as Android from the dropdown menu.

• On the credential section, enter the package name and the SHA1.

• Your 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

• Open terminal

• Type command ./gradlew signingReport

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

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

Truecaller SDK enables you to verify your user's mobile number in a seamless way. For users who have the 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 the Truecaller app present on their smartphones, the SDK enables user verification by means of a drop call, which is triggered to the user's number in the 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 the example of CentroStore. CetroStore is using Truecaller SDK for verifying the numbers of all their users.

Scenario 1

a) New user on CentroStore app and

b) Truecaller app present on user's smartphone

Scenario 2

a) Existing user on CentroStore app, and

b) Truecaller app present on smartphone

Scenario 3

a) New user on CentroStore app, and

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

Scenario 4

a) Existing user on CentroStore app, and

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

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 both the Truecaller users (via OAuth Flow) and the non-Truecaller users (via manual verification), follow these steps :

1. Enable the Non Truecaller user verification capability for your app, by going to your project on the Truecaller developer portal and navigating to the bottom section.

1. Configure sdkOptions in the TcSdkOptions Builder and supply a value of TcSdkOptions.OPTION_VERIFY_ALL_USERS to it like below.

1. Configure permissions required by the SDK :

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

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​

• the fourth parameter is an instance of FragmentActivity

Please note that Truecaller OAuth SDK v3.0.0 currently supports the verification for non-Truecaller users for Indian numbers only

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

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

• When the OTP via Truecaller IM is successfully initiated for the input mobile number. In this case, you will get the callbackType as VerificationCallback.TYPE_IM_OTP_INITIATED

• When the OTP via Truecaller IM is successfully detected on that device by the SDK present in your app. In this case, you will get the callbackType as VerificationCallback.TYPE_IM_OTP_RECEIVED

• When drop call is successfully initiated for the input mobile number. In this case, you will get the callbackType 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 callbackType as VerificationCallback.TYPE_MISSED_CALL_RECEIVED

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

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

When callbackType 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.

When the callbackType 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 :

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

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

To ensure the authenticity of interactions between your app and Truecaller, you need to generate a client ID from the Truecaller developer portal by following the steps below:

• Go to and register your account.

• Once registered, log in to your account and click on the "create project” button.

• Enter the project name and select the business category from the dropdown menu. This will create a new project.

• On the project screen, click the “add credential” button and select the platform as Android from the dropdown menu.

• On the credential section, enter the package name and the SHA1.

• Your 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

• Open terminal

• Type command ./gradlew signingReport

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

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

Make a network call to fetch the userInfo using access token from step 14. The response would be corresponding to the scopes granted by the user.

GET https://oauth-account-noneu.truecaller.com/v1/userinfo

Headers

200: OK

{

“sub”: “13627101294235520", “given_name”: “xyz”, “family_name”: “xyz”, “phone_number”: “91xxxxxxxxxx", “email”: “[email protected]”, “picture”: “https://www.truecaller.com/xyz”, “gender”: “male/female”, “phone_number_country_code”: “IN”, “phone_number_verified”: true, ˇ“address”: { “locality”: “Bangalore”, “postal_code”: “5xxxxx" } }

401: Unauthorized If authentication type is not bearer token

404: Not Found Profile information is not present for the user

500: Internal Server Error Failed to validate token due to server error

401: Unauthorized Token in invalid/ expired

422: Unprocessable Entity openid scope missing in initial request

500: Internal Server Error Unexpected error at server side

Sample cURL request :

To ensure the authenticity of interactions between your app and Truecaller, you need to generate a client ID from the Truecaller developer portal by following the steps below:

• Go to and register your account.

• Once registered, log in to your account and click on the "create project” button.

• Enter the project name and select the business category from the dropdown menu. This will create a new project.

• On the project screen, click the “add credential” button and select the platform as Android from the dropdown menu.

• On the credential section, enter the package name and the SHA1.

• Your 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

• Open terminal

• Type command ./gradlew signingReport

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

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

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

Using the “state” from step 10, “code verifier” from step 12, and the “authorization code” from step 9, you need to make a network call to Truecaller’s backend so as to fetch the access token :

POST https://oauth-account-noneu.truecaller.com/v1/token

Headers

Request Body

200: OK Success

{ "access_token": "some-access-token", "expires_in": 3600, "token_type": "Bearer" }

400: Bad Request - If grant type is not supported 403: Forbidden - If client id is invalid 500: Internal Server Error - Unexpected error on the server side 400: Bad Request - Some of the parameters are empty in the request 403: Forbidden Valid grant type but not allowed for the client 403: Forbidden Invalid auth code provided 403: Forbidden Invalid/expired auth code in provided 403: Forbidden Invalid/expired code verifier is provided 429: Too Many Requests If the number of requests exceeds the allowed limit 503: Service Unavailable Resource unavailable due to server-side issue

Sample cURL request :

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. 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 TcSdk.getInstance().isOAuthFlowUsable 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 TcOAuthData response in onSuccess() callback method ]

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

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

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 ) - a.) When the callback type you receive is VerificationCallback.TYPE_MISSED_CALL_INITIATED. This implies that a drop call has been triggered to the user's mobile number b.) When the callback type you receive is VerificationCallback.TYPE_MISSED_CALL_RECEIVED. This implies that a drop call has been received on the user's mobile number on that smartphone c.) Further to the above step, you complete the user verification by invoking TcSdk.getInstance().verifyMissedCall(profile, verificationCallback) When the callback type you receive is either VerificationCallback.TYPE_VERIFICATION_COMPLETE. This implies that the verification is complete for the user d.) 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 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

1. Create a TcSdkOptions object by using the tcOAuthCallback from the previous step and provide the context. Supply the appropriate customization settings to the relevant methods of TcSdkOptions and use the instance of tcSdkOptions to initialize the TcSdk in the next step.

In case you do not wish to provide any customization settings and fall back to the default SDK settings, you may simply call -

1. Initialize TcSdk using the tcSdkOptions from the previous step :

Note: Truecaller OAuth SDK needs to be initialized only once in the component and the same instance can be accessed without the need to initialize it again, via TcSdk.getInstance()

Ideally, you should call the init() method when the component is getting created/initialized to avoid calling it multiple times.

The SDK init should always happen in a background thread. You can refer to an example snippet below _{[Recommended]} :

1. Once the SDK is initialized, check whether the OAuth functionality is usable or not by calling :

If isUsable is True, you can proceed with further steps, otherwise, you’d have to fall back to some other mechanism ( your fallback verification flow ). Calling other SDK methods when isUsable is False would result in an exception, so please ensure to call this soon after initializing the SDK, and proceed to further steps only if this method returns True.

1. In your Activity/Fragment where you want to integrate the Truecaller OAuth flow, either make the component implement the interface TcOAuthCallback or create an instance of it which you would require to initialize TcSdkOptions in the next step.

The interface has 2 functions which need to be overridden -

• onFailure() method will be called in case of an error. You would get the error details like the error code and error message through tcOAuthError returned with this method.

• onSuccess() method will be called when the user gives consent to authorize your app by tapping on the primary button on the Truecaller’s consent screen, and subsequently, an authorization code will be successfully generated and received. This method would return tcOAuthData which contains information like :

  • authorizationCode - which you can utilize to fetch the user’s access token

  • scopesGranted - list of scopes granted by the user

  • state - state parameter returned by the authorisation server. If the state set by your application is the same as the state returned by the authorisation server, it’s safe to proceed further. If state parameters are different, someone else has initiated the request and it could be a case of request forgery.

1. Override the onActivityResult() method of the component used in step 1 and call the onActivityResultObtained() method if the requestCode matches to TcSdk.SHARE_PROFILE_REQUEST_CODE.

1. Set a unique state parameter & store it in the current session to use it later in the onSuccess() callback method of the TcOAuthCallback to match if the state received from the authorization server is the same as set here to prevent request forgery attacks.

One good choice for a state token is a string of around 32 characters constructed using a high-quality random-number generator as we did above. Another approach could be a hash generated by signing some of your session state variables with a key that is kept secret on your back-end.

1. Set the list of scopes to be requested.

1. Generate a unique code verifier & store it in the current session since it would be required later to generate the access token. It can be generated using the utility class CodeVerifierUtil provided in the SDK.

This utility method generates a random code verifier string using SecureRandom as the source of entropy with 64 as the default entropy quantity.

1. Set the corresponding code challenge using the code verifier generated in the previous step. This can be generated using the utility class CodeVerifierUtil provided in the SDK.

This utility method produces a code challenge from the supplied code verifier using SHA-256 as the challenge method and Base64 as encoding if the system supports it (all Android devices should ideally support SHA-256 and Base64), but in rare case if the device doesn’t, then this method would return null meaning that you can’t proceed further. Please ensure to have a null safe check for such cases.

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.

Client ID should be working fine ( onFailure() Error Type 12)

For complete details on this part, please refer .

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 to go through some of the commonly asked questions.

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.

Let us now see an example to understand how to effectively use Truecaller SDK at such touch points in your user journey

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 CentroStore - our very own in-house sample app:

Building for Various Touch points

a. Invoking user signup/ login/ verification via Truecaller at app onboarding

Example: CentroStore - our very own in-house sample 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 CetroStore.

b. Directly invoking verification via Truecaller

Example : CentroStore - our very own in-house sample app

CentroStore 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 : CentroStore - our very own in-house sample app

CentroStore also 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.

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.

Let us now see an example to understand how to effectively use Truecaller SDK at such touch points in your user journey

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 CentroStore - our very own in-house sample app:

Building for Various Touch points

a. Invoking user signup/ login/ verification via Truecaller at app onboarding

Example: CentroStore - our very own in-house sample 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 CetroStore.

b. Directly invoking verification via Truecaller

Example : CentroStore - our very own in-house sample app

CentroStore 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 : CentroStore - our very own in-house sample app

CentroStore also 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.

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

Please note that the first name and last name values to be passed in the above method call need to follow below mentioned rules :

• The strings need to contains at least 1 alphabet, and cannot be completely comprised of numbers or special characters.

• String length should be less than 128 characters.

• First name is a mandatory field, last name can be empty ( but non nullable ).

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

Please note that Truecaller SDK 3.1.0 is not by default enabled for the IM OTP flow. This new update is currently under early access. In case you want to enable it for your app, please drop in a request at [email protected]

Failure/ Error responses

The "onFailure" 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 :

Please note that when you encounter any of the error scenarios and get the control in the "onFailure()" 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 initialized the SDK using ONLY_TC_USERS scope option i.e to verify only the Truecaller users, and you are not calling isOAuthFlowUsable() method before calling an SDK method. To resolve this, call isOAuthFlowUsable() before calling any SDK method if you are using VERIFY_TC_USERS 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.

"Add client id in your manifest"

This exception suggests that you are trying to call SDK initialization/build method without having your clientID mentioned in your manifest as meta-data.

"OAuth scopes cannot be null or empty"

This exception suggests that you are trying to call SDK method - getAuthorisationCode before setting up the OAuth scopes.

"OAuth state cannot be null or empty"

This exception suggests that you are trying to call SDK method - getAuthorisationCode before setting up the OAuth state.

“Code challenge cannot be null or empty”

This exception suggests that you are trying to call SDK method - getAuthorisationCode before setting up the Code challenge.

Using the “state” from step 10, “code verifier” from step 12, and the “authorization code” from step 9, you need to make a network call to Truecaller’s backend so as to fetch the access token :

POST https://oauth-account-noneu.truecaller.com/v1/token

Headers

Request Body

200: OK Success

{ "access_token": "some-access-token", "expires_in": 3600, "token_type": "Bearer" }

400: Bad Request - If grant type is not supported 403: Forbidden - If client id is invalid 500: Internal Server Error - Unexpected error on the server side 400: Bad Request - Some of the parameters are empty in the request 403: Forbidden Valid grant type but not allowed for the client 403: Forbidden Invalid auth code provided 403: Forbidden Invalid/expired auth code in provided 403: Forbidden Invalid/expired code verifier is provided 429: Too Many Requests If the number of requests exceeds the allowed limit 503: Service Unavailable Resource unavailable due to server-side issue

Sample cURL request :

curl --location --request POST 'https://oauth-account-noneu.truecaller.com/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=<<your-client-id>>' \
--data-urlencode 'code=<<authorization_code>>' \
--data-urlencode 'code_verifier=<<your-code-verifier>>'

1. Set a unique state parameter & store it in the current session to use it later in the onSuccess() callback method of the TcOAuthCallback to match if the state received from the authorization server is the same as set here to prevent request forgery attacks.

stateRequested = BigInteger(130, SecureRandom()).toString(32)
TcSdk.getInstance().setOAuthState(stateRequested)

One good choice for a state token is a string of around 32 characters constructed using a high-quality random-number generator as we did above. Another approach could be a hash generated by signing some of your session state variables with a key that is kept secret on your back-end.

1. Set the list of scopes to be requested.

TcSdk.getInstance().setOAuthScopes(arrayOf("profile", "phone", ...))

// Currently available list of scopes :
- profile
- phone
- openid
- offline_access
- email
- address

Note : 
Please include the relevant scopes for your project. 
Make sure the scopes you’re requesting above are selected on the portal for your project

1. Generate a unique code verifier & store it in the current session since it would be required later to generate the access token. It can be generated using the utility class CodeVerifierUtil provided in the SDK.

codeVerifier = CodeVerifierUtil.generateRandomCodeVerifier()

This utility method generates a random code verifier string using SecureRandom as the source of entropy with 64 as the default entropy quantity.

1. Set the corresponding code challenge using the code verifier generated in the previous step. This can be generated using the utility class CodeVerifierUtil provided in the SDK.

val codeChallenge = CodeVerifierUtil.getCodeChallenge(codeVerifier)
codeChallenge?.let {
                TcSdk.getInstance().setCodeChallenge(it)
} ?: print(“Code challenge is Null. Can’t proceed further”)

This utility method produces a code challenge from the supplied code verifier using SHA-256 as the challenge method and Base64 as encoding if the system supports it (all Android devices should ideally support SHA-256 and Base64), but in rare case if the device doesn’t, then this method would return null meaning that you can’t proceed further. Please ensure to have a null safe check for such cases.

1. In your Activity/Fragment where you want to integrate the Truecaller OAuth flow, either make the component implement the interface TcOAuthCallback or create an instance of it which you would require to initialize TcSdkOptions in the next step.

The interface has 2 functions which need to be overridden -

private val tcOAuthCallback: TcOAuthCallback = object : TcOAuthCallback {
    override fun onSuccess(tcOAuthData: TcOAuthData) {
        ..
    }

    override fun onFailure(tcOAuthError: TcOAuthError) {
        ..
    }
}

• onFailure() method will be called in case of an error. You would get the error details like the error code and error message through tcOAuthError returned with this method.

• onSuccess() method will be called when the user gives consent to authorize your app by tapping on the primary button on the Truecaller’s consent screen, and subsequently, an authorization code will be successfully generated and received. This method would return tcOAuthData which contains information like :

  • authorizationCode - which you can utilize to fetch the user’s access token

  • scopesGranted - list of scopes granted by the user

  • state - state parameter returned by the authorisation server. If the state set by your application is the same as the state returned by the authorisation server, it’s safe to proceed further. If state parameters are different, someone else has initiated the request and it could be a case of request forgery.

1. Override the onActivityResult() method of the component used in step 1 and call the onActivityResultObtained() method if the requestCode matches to TcSdk.SHARE_PROFILE_REQUEST_CODE.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        if (requestCode == TcSdk.SHARE_PROFILE_REQUEST_CODE) {
             TcSdk.getInstance().onActivityResultObtained(this, requestCode, resultCode, data)
        }
}

Once the SDK shares the accessToken for any user verified via drop call based verification 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:

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

REQUEST :

Method : GET

Header Parameters:

Request Path Parameters:

RESPONSE:

• 200 OK - If access token is valid

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

• 404 Not Found - If your credentials are not valid

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

• 404 Not Found - If access token is invalid

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

• 500 Internal Error - for any other internal error

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

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 :

1. Create a TcSdkOptions object by using the tcOAuthCallback from the previous step and provide the context. Supply the appropriate customization settings to the relevant methods of TcSdkOptions and use the instance of tcSdkOptions to initialize the TcSdk in the next step.

val tcSdkOptions = TcSdkOptions.Builder(this, tcOAuthCallback)
.buttonColor(Color.parseColor("<<VALID_COLOR_HEX_CODE>>"))
          .buttonTextColor(Color.parseColor("<<VALID_COLOR_HEX_CODE>>"))
            .loginTextPrefix(TcSdkOptions.LOGIN_TEXT_PREFIX_TO_GET_STARTED)
            .ctaText(TcSdkOptions.CTA_TEXT_CONTINUE)
            .buttonShapeOptions(TcSdkOptions.BUTTON_SHAPE_ROUNDED)
            .footerType(TcSdkOptions.FOOTER_TYPE_SKIP)
            .consentTitleOption(TcSdkOptions.SDK_CONSENT_TITLE_LOG_IN)
            .sdkOptions(TcSdkOptions.OPTION_VERIFY_ONLY_TC_USERS)
            .build();

In case you do not wish to provide any customization settings and fall back to the default SDK settings, you may simply call -

val tcSdkOptions = TcSdkOptions.Builder(this, tcOAuthCallback).build()

1. Initialize TcSdk using the tcSdkOptions from the previous step :

TcSdk.init(tcSdkOptions)

Note: Truecaller OAuth SDK needs to be initialized only once in the component and the same instance can be accessed without the need to initialize it again, via TcSdk.getInstance()

Ideally, you should call the init() method when the component is getting created/initialized to avoid calling it multiple times.

1. Once the SDK is initialized, check whether the OAuth functionality is usable or not by calling :

val isUsable = TcSdk.getInstance().isOAuthFlowUsable

If isUsable is True, you can proceed with further steps, otherwise, you’d have to fall back to some other mechanism ( your fallback verification flow ). Calling other SDK methods when isUsable is False would result in an exception, so please ensure to call this soon after initializing the SDK, and proceed to further steps only if this method returns True.

1. Ensure that your Minimum SDK version is at least API level 24 or above. In case your android project compiles for API level below 24, you can include the following line in your AndroidManifest.xml file to avoid any compilation issues : <uses-sdk tools:overrideLibrary="com.truecaller.android.sdk"/> Using this would ensure that the SDK works normally for API level 24 & above, and would be disabled for API level < 24. Note: Please make sure that you put the necessary API level checks before accessing the SDK methods in case of compiling for API level < 24

2. 2.1) Add the Truecaller SDK which contains OAuth functionality to your app-level build.gradle file dependencies {

   ...

   implementation "com.truecaller.android.sdk:truecaller-sdk:3.0.0"

   } 2.2) Also, add the following lines of code in your gradle file, if not already present android{

   compileOptions{

   sourceCompatibility JavaVersion.VERSION_1_8

   targetCompatibility JavaVersion.VERSION_1_8

   }

   }

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

   allprojects{

   repositories{

   ...

   mavenCentral()

   ...

   } Also check your AGP and distribution URL version AGP : 7.4.2 (minimum) distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip (minimum).

4. Configure Client ID :

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

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

<application android:label="@string/app_name" ...>

...

<meta-data android:name="com.truecaller.android.sdk.ClientId" android:value="@string/clientID"/>

...

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

TcSdk.getInstance().getAuthorizationCode(this);

In case isOAuthFlowUsable() 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.

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 :

Failure/ Error responses

The "onFailure" 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 :

Please note that when you encounter any of the error scenarios and get the control in the "onFailure()" 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 initialized the SDK using ONLY_TC_USERS scope option i.e to verify only the Truecaller users, and you are not calling isOAuthFlowUsable() method before calling an SDK method. To resolve this, call isOAuthFlowUsable() before calling any SDK method if you are using VERIFY_TC_USERS 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.

"Add client id in your manifest"

This exception suggests that you are trying to call SDK initialization/build method without having your clientID mentioned in your manifest as meta-data.

"OAuth scopes cannot be null or empty"

This exception suggests that you are trying to call SDK method - getAuthorisationCode before setting up the OAuth scopes.

"OAuth state cannot be null or empty"

This exception suggests that you are trying to call SDK method - getAuthorisationCode before setting up the OAuth state.

“Code challenge cannot be null or empty”

This exception suggests that you are trying to call SDK method - getAuthorisationCode before setting up the Code challenge.

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. 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 TcSdk.getInstance().isOAuthFlowUsable 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 TcOAuthData response in onSuccess() callback method ]

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

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

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 ) - a.) When the callback type you receive is VerificationCallback.TYPE_MISSED_CALL_INITIATED. This implies that a drop call has been triggered to the user's mobile number b.) When the callback type you receive is VerificationCallback.TYPE_MISSED_CALL_RECEIVED. This implies that a drop call has been received on the user's mobile number on that smartphone c.) Further to the above step, you complete the user verification by invoking TcSdk.getInstance().verifyMissedCall(profile, verificationCallback) When the callback type you receive is either VerificationCallback.TYPE_VERIFICATION_COMPLETE. This implies that the verification is complete for the user d.) 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.

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.

Let us now see an example to understand how to effectively use Truecaller SDK at such touch points in your user journey

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 CentroStore - our very own in-house sample app:

Building for Various Touch points

a. Invoking user signup/ login/ verification via Truecaller at app onboarding

Example: CentroStore - our very own in-house sample 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 CetroStore.

b. Directly invoking verification via Truecaller

Example : CentroStore - our very own in-house sample app

CentroStore 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 : CentroStore - our very own in-house sample app

CentroStore also 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.

Truecaller SDK enables you to verify your user's mobile number in a seamless way. For users who have the 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 the Truecaller app present on their smartphones, the SDK enables user verification by means of a drop call, which is triggered to the user's number in the 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 the example of CentroStore. CetroStore is using Truecaller SDK for verifying the numbers of all their users.

Scenario 1

a) New user on CentroStore app and

b) Truecaller app present on user's smartphone

Scenario 2

a) Existing user on CentroStore app, and

b) Truecaller app present on smartphone

Scenario 3

a) New user on CentroStore app, and

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

Scenario 4

a) Existing user on CentroStore app, and

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

Truecaller SDK provides you with capabilities to configure the following:

Refer to the section below for details on all the customization capabilities and the possible values you may set:

TcSdkOptions.Builder(this, tcOAuthCallback)
       .consentMode(TcSdkOptions.CONSENT_MODE_BOTTOMSHEET) 
       .buttonShapeOptions(TcSdkOptions.BUTTON_SHAPE_ROUNDED)
       .footerType(TcSdkOptions.FOOTER_TYPE_ANOTHER_MOBILE_NO)
       .sdkOptions(TcSdkOptions.OPTION_VERIFY_ONLY_TC_USERS)
       .ctaText(TcSdkOptions.CTA_TEXT_ACCEPT)
       .heading(TcSdkOptions.LOGIN_TEXT_PREFIX_TO_GET_STARTED)
       .buttonColor(1111)
       .buttonTextColor(1111)
       .build()

Consent Mode Style [ .consentMode() ]

To align the consent screen with your UX, which could either be centrally or bottom aligned, choose either of the consent screens, making the SDK integration more homogeneous with your app UX.

Contextual header [ .heading() ]

To provide the appropriate context of verification to the Truecaller user, use one of the below mentioned TruecallerSdkScope values to show the corresponding message to the user

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

Dark Theme

To set the consent screen in dark mode, you can call TcSdk.getInstance().setTheme(OAuthThemeOptions.DARK)

just before calling the TcSdk.getInstance().getAuthorizationCode(this, launcher) By default, the SDK is configured with the light theme.

Privacy policy :

To add your privacy policy link on the verification screen, you can configure the respective hyperlink from your developer account

Terms of service: To add your terms of service link on the verification screen, you can configure the respective hyperlink from your developer account

Language: You can optionally customize the consent screen in any of the supported languages. To do so, add the following line :

Copy

val locale = Locale("hi") // change language to Hindi
TcSdk.getInstance().setLocale(locale)

Currently supported languages:

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 both the Truecaller users (via OAuth Flow) and the non-Truecaller users (via manual verification), follow these steps :

1. Enable the Non Truecaller user verification capability for your app, by going to your project on the Truecaller developer portal and navigating to the bottom section.

1. Configure sdkOptions in the TcSdkOptions Builder and supply a value of TcSdkOptions.OPTION_VERIFY_ALL_USERS to it like below.

1. Configure permissions required by the SDK :

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

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​

• the fourth parameter is an instance of FragmentActivity

Please note that Truecaller OAuth SDK v3.0.0 currently supports the verification for non-Truecaller users for Indian numbers only

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

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

• When the OTP via Truecaller IM is successfully initiated for the input mobile number. In this case, you will get the callbackType as VerificationCallback.TYPE_IM_OTP_INITIATED

• When the OTP via Truecaller IM is successfully detected on that device by the SDK present in your app. In this case, you will get the callbackType as VerificationCallback.TYPE_IM_OTP_RECEIVED

• When drop call is successfully initiated for the input mobile number. In this case, you will get the callbackType 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 callbackType as VerificationCallback.TYPE_MISSED_CALL_RECEIVED

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

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

When callbackType 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.

When the callbackType 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 :

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

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

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 both the Truecaller users (via OAuth Flow) and the non-Truecaller users (via manual verification), follow these steps :

1. Enable the Non Truecaller user verification capability for your app, by going to your project on the Truecaller developer portal and navigating to the bottom section.

1. Configure sdkOptions in the TcSdkOptions Builder and supply a value of TcSdkOptions.OPTION_VERIFY_ALL_USERS to it like below.

1. Configure permissions required by the SDK :

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

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​

• the fourth parameter is an instance of FragmentActivity

Please note that Truecaller OAuth SDK v3.0.0 currently supports the verification for non-Truecaller users for Indian numbers only

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

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

• When the OTP via Truecaller IM is successfully initiated for the input mobile number. In this case, you will get the callbackType as VerificationCallback.TYPE_IM_OTP_INITIATED

• When the OTP via Truecaller IM is successfully detected on that device by the SDK present in your app. In this case, you will get the callbackType as VerificationCallback.TYPE_IM_OTP_RECEIVED

• When drop call is successfully initiated for the input mobile number. In this case, you will get the callbackType 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 callbackType as VerificationCallback.TYPE_MISSED_CALL_RECEIVED

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

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

When callbackType 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.

When the callbackType 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 :

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

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

Once the SDK shares the accessToken for any user verified via drop call based verification 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:

REQUEST :

Method : GET

Header Parameters:

Request Path Parameters:

RESPONSE:

• 200 OK - If access token is valid

• 404 Not Found - If your credentials are not valid

• 404 Not Found - If access token is invalid

• 500 Internal Error - for any other internal error

Truecaller SDK provides you with capabilities to configure the following:

Refer to the below section for details on all the customization capabilities and the possible values you may set:

TcSdkOptions.Builder(this, tcOAuthCallback)
       .buttonShapeOptions(TcSdkOptions.BUTTON_SHAPE_ROUNDED)
       .footerType(TcSdkOptions.FOOTER_TYPE_ANOTHER_MOBILE_NO)
       .sdkOptions(TcSdkOptions.OPTION_VERIFY_ONLY_TC_USERS)
       .ctaText(TcSdkOptions.CTA_TEXT_ACCEPT)
       .heading(TcSdkOptions.LOGIN_TEXT_PREFIX_TO_GET_STARTED)
       .buttonColor(1111)
       .buttonTextColor(1111)
       .build()

Contextual header [ .heading() ]

To provide the appropriate context of verification to the Truecaller user, use one of the below mentioned TruecallerSdkScope values to show the corresponding message to the user

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 :

To add your privacy policy link on the verification screen, you can configure the respective hyperlink from your developer account

Terms of service: To add your terms of service link on the verification screen, you can configure the respective hyperlink from your developer account

Language You can optionally customize the consent screen in any of the supported languages. To do so, add the following line :

Copy

val locale = Locale("hi") // change language to Hindi
TcSdk.getInstance().setLocale(locale)

Currently supported languages: