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.

• 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

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

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.

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

   ...

   }

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

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.

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 :

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.

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 :

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

Copy

TrueProfile profile = new TrueProfile.Builder(firstName, lastName).build();
TcSdk.getInstance().verifyMissedCall(profile, verificationCallback)

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

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

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:

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

Currently supported languages:

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

• 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

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

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.