quoraboy / android-sdk

Android SDK 0.7

Understanding how the user verification flow works

• Truecaller app needs to be installed on the user's device. User starts by clicking on your defined CTA ( Login / Verify / Signup etc. ) or you can even directly trigger the Truecaller verification anywhere in your app flow. User would then be shown the standard Truecaller profile verification dialog asking for user's consent. The user authorizes by clicking verify and their Truecaller profile would be shared with the app as response object

Getting Started

Account Setup

To ensure the authenticity of the interactions between your app and Truecaller, you need to generate a app key from the truecaller developer portal ( https://developer.truecaller.com/login ) by providing us with your package name and SHA-1 signing-fingerprint.

You package name corresponds to the applicationId in your app level build.gradle file. You can get to know the SHA1 for your different app builds by following these steps :

1. Open your project in android studio
2. Click on gradle menu on the right side and expland it
3. Click on android and then signing report

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

Once we have received the package name and the SHA-1 signing-fingerprint, we will provide you with a unique "appKey" which you need to include in your project to authorize all verification requests.

NOTE : While generating your release build and the corresponding partnerKey, please refer to this section for generating app key for release build.

Using the SDK with your Android Studio Project

1. Ensure that your Minimum SDK version is atleast API level 16 or above ( Android 4.1 ). In case your android project compiles for API level below 16, 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 16 & above, and would be disabled for API level < 16 Please make sure that you put the necessary API level checks before accessing the SDK methods in case compiling for API level < 16

2. Add the provided truesdk-0.7-releasePartner.aar file into your libs folder. Example path: /app/libs/

3. Open the build.gradle of your application module and ensure that your lib folder can be used as a repository :

   repositories {
       flatDir {
           dirs 'libs'
       }
   }

   Secondly add the compile dependency with the latest version of the TrueSDK aar :

   dependencies {
       implementation(name: "truesdk-0.7-releasePartner", ext: "aar")
   }

   Add the following dependencies within your gradle file :

   implementation 'com.squareup.retrofit2:retrofit:2.3.0'
   implementation 'com.squareup.okhttp3:okhttp:3.7.0'

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

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

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

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

   TrueSdkScope trueScope = new TrueSdkScope.Builder(this, sdkCallback)
      .consentMode(TrueSdkScope.CONSENT_MODE_FULLSCREEN )
      .consentTitleOption( TrueSdkScope.SDK_CONSENT_TITLE_VERIFY )
      .footerType( TrueSdkScope.FOOTER_TYPE_SKIP )
      .build();
              
   TrueSDK.init(trueScope);	

   Once you initialize the TrueSDK using the init() method, you can check if the truecaller app is present on the user's device or not by using the following method

   TrueSDK.getInstance().isUsable()

   TrueSDK v0.7 provides you with capabilities to configure the following settings -

   Consent Mode

   To switch between a full screen view or an overlay view of the truecaller profile verification view

   Possible values for Consent Mode :

   // To display the user's Truecaller profile in a popup view
   TrueSdkScope.CONSENT_MODE_POPUP
   
   // To display the user's Truecaller profile in a full screen view
   TrueSdkScope.CONSENT_MODE_FULLSCREEN

   Footer Type

   To configure the CTA present at the bottom

   Possible values for Footer Type :

   // To use "USE DIFFERENT NUMBER" CTA at the bottom of the user profile view
   TrueSdkScope.FOOTER_TYPE_CONTINUE
   
   // To use "SKIP" CTA at the bottom of the user profile view
   TrueSdkScope.FOOTER_TYPE_SKIP

   Consent Title Options

   To provide appropriate context of verification to the truecaller user

   Possible values for the Title option :

   // To use "Login" as the contextual text in the user profile view title
   TrueSdkScope.SDK_CONSENT_TITLE_LOG_IN
   
   // To use "Signup" as the contextual text in the user profile view title
   TrueSdkScope.SDK_CONSENT_TITLE_SIGN_UP
   
   // To use "Sign in" as the contextual text in the user profile view title
   TrueSdkScope.SDK_CONSENT_TITLE_SIGN_IN
   
   // To use "Verify" as the contextual text in the user profile view title
   TrueSdkScope.SDK_CONSENT_TITLE_VERIFY
   
   // To use "Register" as the contextual text in the user profile view title
   TrueSdkScope.SDK_CONSENT_TITLE_REGISTER
   
   // To use "Get Started" as the contextual text in the user profile view title
   TrueSdkScope.SDK_CONSENT_TITLE_GET_STARTED

7. Add the following condition in the onActivityResult method:

   TrueSDK.getInstance().onActivityResultObtained( this,resultCode, data);

8. In your selected Activity

   • Either make the Activity implement ITrueCallback or create an instance. This interface has 2 methods: onSuccesProfileShared(TrueProfile) and onFailureProfileShared(TrueError)

       private final ITrueCallback sdkCallback = new ITrueCallback() {
       
        @Override
        public void onSuccessProfileShared(@NonNull final TrueProfile trueProfile) {
    
    	// This method is invoked when the truecaller app is installed on the device and the user gives his
    	// consent to share his truecaller profile 
    	
    	Log.d( TAG, "Verified Successfully : " + trueProfile.firstName );
        }
   
        @Override
        public void onFailureProfileShared(@NonNull final TrueError trueError) {
    	// This method is invoked when some error occurs or if an invalid request for verification is made 
    
    	Log.d( TAG, "onFailureProfileShared: " + trueError.getErrorType() );
        }
   
    };
    

   Write all the relevant logic in onSuccesProfileShared(TrueProfile) for displaying the information you have just received and onFailureProfileShared(TrueError) for handling the error and notify the user.

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

   TrueSDK.getInstance().getUserProfile() 

10. (Optional) Truecaller SDK gives you the capability to customize the profile dialog in multiple Indian languages ( Refer list of supported languages here ). To do so, add the following lines before calling the "getUserProfile()" method as mentioned in the above step -

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

    Note : In case the input locale is not supported, the profile will by default be shown in English language

11. (Optional) You can set a unique requestID for every profile request with TrueSDK.getInstance().setRequestNonce(customHash);

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

Advanced Steps

A. Server side Truecaller Profile authenticity check

Truecaller SDK already verifies the authenticity of the response before forwarding it to your app. However, if you wish to additionally check the authenticity of the response at your end, you can do so. For details on the verification flow and sample code snippets, please refer the following link :

https://github.com/truecaller/backend-sdk-validation

B. Request-Response correlation check

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

1. You can use your own custom request identifier via the TrueClient with TrueSDK.getInstance().setRequestNonce(customHash);
2. In ITrueCallback.onSuccesProfileShared(TrueProfile) verify that the previously generated identifier matches the one in TrueProfile.requestNonce.

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

C. Generating App Key for Release Build

Different app builds ( debug / release ) have different SHA1 fingerprints and hence would have different & unique app keys, as a single app key corresponds to a particular combination of package name and SHA1. You need to manage your debug / release builds by creating separate keys.

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

In this scenario, you need to note down the new SHA1 of your app from the Google Play Developer Console and then use this to generate a corresponding new "appKey" from the Truecaller Developer Portal. Use this new key in your app config and then upload the build on play store

Supported languages for profile customization

Truecaller SDK provides developers flexibility to customize the user verification profile screen in multiple Indian languages. Please refer below for the list of all supported languages.

 - English
 - Hindi
 - Marathi
 - Telugu
 - Malayalam
 - Urdu
 - Punjabi
 - Tamil
 - Bengali
 - Kannada