Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Manual Installation
Download the project zip file from the release section
Unzip the file
Copy the TruecallerSDK project files into your project ( TrueSDK directory, TrueSDKTests directory and TrueSDK.xcodeproj )
Drag and drop TrueSDK.xcodeproj into your project ( i.e. add it as a subproject to your main project ). Embedding it this way will not require any additional script to be run.
Add the TruecallerSDK framework ( from Products output of TrueSDK.xcodeproj ) into the Embedded Binaries section of the General tab of your target.
NOTE: We recommend using the CocoaPods integration.
Installation with CocoaPods
CocoaPods is a dependency manager which automates and simplifies the process of using 3rd party libraries.
You can install it with the following command:
You can create your Podfile using the command ( in case you do not already have it ):
To integrate TruecallerSDK into your Xcode project using CocoaPods, specify it in your Podfile
:
Then, run the following command:
To ensure the authenticity of interactions between your app and Truecaller, you need to generate an app key [ partner key ] and app link from Truecaller developer account ( ) by adding your App Name, Bundle Id and prefix.
To generate a new app key for your iOS app, go to the 'MANAGE APPS' section on the developer account dashboard and click on 'CREATE APP'. Select 'iOS' in the App type and continue to enter your app details.
You can find your App Id in the "Apple Development Portal". If you do not have App Id yet, then open Project -> Capabilities -> Enable Associated Domains. New app id will be automatically created by Xcode.
Once you input your app details and create the app, you will be able to see the "App Key" and "App Link" values for your app. You need to include these values in your project to authorise all the verification requests.
To ensure the authenticity of interactions between your app and Truecaller, you need to generate an app key [ partner key ] and app link from Truecaller developer account ( ) by adding your App Name, Bundle Id and prefix.
To generate a new app key for your iOS app, go to the 'MANAGE APPS' section on the developer account dashboard and click on 'CREATE APP'. Select 'iOS' in the App type and continue to enter your app details.
You can find your App Id in the "Apple Development Portal". If you do not have App Id yet, then open Project -> Capabilities -> Enable Associated Domains. New app id will be automatically created by Xcode.
Once you input your app details and create the app, you will be able to see the "App Key" and "App Link" values for your app. You need to include these values in your project to authorise all the verification requests.
1. Import the TruecallerSDK framework in the class where you want to initialize it (for example AppDelegate) and in the class that you want to receive the profile response. Usually, this will be the ViewController responsible for displaying the True Profile info.
2. Check if the current device supports the use of TruecallerSDK and (if so) setup TruecallerSDK. We recommend this to be done in the application:didFinishLaunchingWithOptions:
Use the entire associated domain link provided by Truecaller for YOUR_APP_LINK. For example: https://si44524554ef8e45b5aa83ced4e96d5xxx.truecallerdevs.com
(including https://).
Important: Make sure you type the YOUR_APP_KEY and YOUR_APP_LINK fields correctly. If you mistype the YOUR_APP_LINK field, the permission screen in Truecaller will be shown and immediatelly dismissed. In this case, the SDK will not be able to send a corresponding error back to your app.
3. In AppDelegate implement the method application:continueUserActivity:restorationHandler: and call the corresponding method of the [TCTrueSDK sharedManager]. If the method returns false that means the activity need not be addressed by TruecallerSDK and you can handle it as desired.
4. Set the class where you want to receive TruecallerSDK events (the profile or errors) a TCTrueSDKDelegate
5. Implement the two TCTrueSDKDelegate methods
The profile object is of type TCTrueProfile (written in Objective C) which offers the following user data:
6. Set the delegate property of the [TCTrueSDK sharedManager]. Make sure you do this before you request the True Profile.
7. Requesting the True Profile data can be done automatically or manually (either in code or in the Interface Builder):
a. The TCProfileRequestButton does the True Profile Request automatically. To use the predefined buttons you need to set the Button Type to Custom and set auto-layout constraints for the button. You can then choose the True button style and corners style of the button in code or in Interface Builder using TCProfileRequestButton property buttonStyle and buttonCornersStyle:
b. If you prefer to do it yourself, you can use the method requestTrueProfile.
Important: Do not use both approaches a. and b. at the same time. Doing so will request the Truecaller profile 2 times in a row. You do not need to call requestTrueProfile if you use TCProfileRequestButton. This button includes the request in itself.
1. Import the TruecallerSDK framework in the class where you want to initialize it (for example AppDelegate) and in the class that you want to receive the profile response. Usually, this will be the ViewController responsible for displaying the True Profile info.
Swift 2.3 :
Swift 3+ :
2. Check if the current device supports the use of TruecallerSDK and (if so) setup TruecallerSDK. We recommend this to be done in the application:didFinishLaunchingWithOptions:
Swift 2.3 :
Swift 3+ :
Use the entire associated domain link provided by Truecaller for YOUR_APP_LINK. For example: https://si44524554ef8e45b5aa83ced4e96d5xxx.truecallerdevs.com
(including https://).
Important: Make sure you type the YOUR_APP_KEY and YOUR_APP_LINK fields correctly. If you mistype the YOUR_APP_LINK field, the permission screen in Truecaller will be shown and immediatelly dismissed. In this case, the SDK will not be able to send a corresponding error back to your app.
3. In AppDelegate implement the method application(application: continue userActivity: restorationHandler:) -> Bool and call the corresponding method of TCTrueSDK.sharedManager(). If the method returns false that means the activity need not be addressed by TruecallerSDK and you can handle it as desired.
Swift 2.3 :
Swift 3+ :
Swift 5 :
For apps using SceneDelegate instead of AppDelegate :
4. Set the class where you want to receive TruecallerSDK events (the profile or errors) a TCTrueSDKDelegate
Swift 2.3 :
Swift 3+ :
5. Implement the two TCTrueSDKDelegate methods
Swift 2.3 :
Swift 3+ :
The profile object is of type TCTrueProfile (written in Objective C) which offers the following user data:
6. Set the delegate property of the TCTrueSDK.sharedManager(). Make sure you do this before you request the True Profile.
Swift 2.3 :
Swift 3+ :
7. Requesting the True Profile data can be done automatically or manually (either in code or in the Interface Builder):
a. The TCProfileRequestButton does the True Profile Request automatically. To use the predefined buttons you need to set the Button Type to Custom and set auto-layout constraints for the button. You can then choose the True button style and corners style of the button in code or in Interface Builder using TCProfileRequestButton property buttonStyle and buttonCornersStyle:
Swift 2.3 :
Swift 3+ :
b. If you prefer to do it yourself, you can use the method requestTrueProfile.
Swift 2.3 :
Swift 3+ :
Important: Do not use both approaches a. and b. at the same time. Doing so will request the Truecaller profile 2 times in a row. You do not need to call requestTrueProfile if you use TCProfileRequestButton. This button includes the request in itself.
TruecallerSDK provides two optional delegate methods to check the authenticity of the profile you receive. Note that TruecallerSDK readily offers a simplified way to request and receive a user profile via required delegate methods and verifies the content before forwarding it your app.
Server side Truecaller Profile authenticity check
The delegate method didReceiveTrueProfileResponse: will return a TCTrueProfileResponse instance. Inside TCTrueProfileResponse class there are 3 important fields, payload, signature and signatureAlgorithm. Payload is a Base64 encoding of the json object containing all profile info of the user. Signature contains the payload's signature. You can forward these fields along with the signing algorithm back to your backend and verify the authenticity of the information by doing the following:
Fetch Truecaller public keys using this api: (we recommend you cache these keys for future use and refresh the cache only if you cannot verify the signature);
Loop through the public keys and try to verify the signature and payload.
Request-Response correlation check
Every request created with TruecallerSDK has a unique identifier namely 'requestNonce'. 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:
Get the request nonce at willRequestProfileWithNonce: method
In didReceiveTrueProfileResponse: verify that the previously retrieved identifier matches the one in TCTrueProfileResponse.requestNonce.
To find the Prefix, go to the member center on and look at "Certificates, Identifiers & Profiles", click "Identifiers", then "App IDs" in the section under "Identifiers". Find your app, click on it, and there you will be able to see the Prefix value ( Refer image below ).
To find the Prefix, go to the member center on and look at "Certificates, Identifiers & Profiles", click "Identifiers", then "App IDs" in the section under "Identifiers". Find your app, click on it, and there you will be able to see the Prefix value ( Refer image below ).
Once verificationState is TCVerificationState.otpInitiated and the user has entered the OTP, first name and last name(optional), you can complete the verification process by calling the following method :
Swift: TCTrueSDK.sharedManager().verifySecurityCode(<#OTP>, andUpdateFirstname: <#FIRST_NAME>, lastName:<#LAST_NAME>)
Objective C
[[TCTrueSDK sharedManager] verifySecurityCode:<#OTP> andUpdateFirstname:<#FIRST_NAME> lastName:<#LAST_NAME>];
Please note that the first name and last name values to be passed in the above method call need to follow the below mentioned rules :
The strings need to contain 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 null )
After you call the above method, your delegate method verificationStatusChanged() with verification status as TCVerificationState.verificationComplete is called and the user profile is received in delegate method
Objective C: - (void)didReceiveTrueProfile:(nonnull TCTrueProfile *)profile
Swift: func didReceive(_ profile: TCTrueProfile)
Whenever you get verification status as TCVerificationState.verificationComplete, SDK will share an additional access token with your application which can be accessed using the accessTokenForOTPVerification() method. You can use this access token to validate the authenticity of the verification flow by making an API call from your server to Truecaller's server. For details on this part, please refer here.
Swift: TCTrueSDK.sharedManager().accessTokenForOTPVerification()
Objective C : [[TCTrueSDK sharedManager] accessTokenForOTPVerification];
This section defines the steps that can be used to trigger verification of non Truecaller app users which will be powered via Truecaller's SMS based OTP ( Currently available only for India )
On the Mobile number entry screen set the below delegates :
Swift:
TCTrueSDK.sharedManager().delegate = self TCTrueSDK.sharedManager().viewDelegate = self
Objective C:
[TCTrueSDK sharedManager].delegate = self; [TCTrueSDK sharedManager].viewDelegate = self;
viewDelegate needs to be set on the mobile number entry screen i.e. OTP flow (not required for Truecaller one tap flow for Truecaller users verification).
Initiate the verification for the user by calling the following method:
Swift:
TCTrueSDK.sharedManager().requestVerification(forPhone: <#PHONE_NUMBER_STRING>,countryCode: <#DEFAULT_COUNTRY_CODE>)
Objective C: [[TCTrueSDK sharedManager] requestVerificationForPhone:<#PHONE_NUMBER_STRING> countryCode:<#DEFAULT_COUNTRY_CODE>];
the first parameter (PHONE_NUMBER_STRING) is the 10-digit mobile number
the second parameter is the country code (DEFAULT_COUNTRY_CODE) of the mobile number for which the verification needs to be triggered(“IN” for India)
Once you initiate the verification using the above requestVerification() method, the below delegate method will be called along with the verification state.
Swift: func verificationStatusChanged(to verificationState: TCVerificationState)
Objective C: (void)verificationStatusChangedTo:(TCVerificationState)verificationState;
verificationStatusChanged() delegate method is called under any of the following scenarios :
When OTP is successfully triggered for the input mobile number. In this case, you will get the verificationState as TCVerificationState.otpInitiated
When the verification is successful for a particular number. In this case, you will get the verificationState as TCVerificationState.verificationComplete
When the user is already verified on that particular device. In this case, you will get the verificationState as TCVerificationState.verifiedBefore
Possible Verification states (TCVerificationState) :
When verificationState is TCVerificationState.otpInitiated, you will also receive an additional parameter for the time to live i.e TTL (in seconds) which can be fetched using:- Swift TCTrueSDK.sharedManager().tokenTtl()
Objective C [[TCTrueSDK sharedManager] tokenTtl];
This value determines the 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.
Once the OTP is initiated, allow the user to enter the OTP, first name and last name.
When the verification status is TCVerificationStateVerifiedBefore or TCVerificationStateVerificationComplete, 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:
Swift TCTrueSDK.sharedManager().accessTokenForOTPVerification()
Objective C [[TCTrueSDK sharedManager] accessTokenForOTPVerification];
After fetching the access token, you may perform the server side validation by referring to the steps mentioned in the later part of the documentation here. Below mentioned didFailToReceiveTrueProfileWithError() method will be called when some error has occurred while verifying the provided mobile number. You will receive the appropriate error message from TCError using TCError.getErrorCode(). For details of different possible error types you may encounter, please refer to the next section
Swift
func didFailToReceiveTrueProfileWithError(_ error: TCError)
Objective C
- (void)didFailToReceiveTrueProfileWithError:(nonnull TCError *)error
Please refer to this section in case you face issues during the app redirection from your app to Truecaller app or vice versa, during the verification flow.
Truecaller SDK uses universal links to handle the redirection between Truecaller app and your app. The process involves 4 steps, as defined below :
User taps the “Sign up with Truecaller” option on your app
Universal link opens Truecaller app
User taps “Continue” button on the Truecaller verification screenD. Universal links opens your app
How Universal Links works
Associated domains are used to notify the OS that these are the universal links supported by Truecaller SDK.
On tapping a URL or when the app calls openURL request, the OS will check if any of those apps have an associated domain related to the URL which is being opened.
If there is one, the OS tries to check for AASA ( apple-app-site-association ) files related to the domain and if the file consists of the path, it opens the app and transfers control to the app.
If any of the above is missing ( the AASA or the path), it will redirect the url to Safari.
What are associated domains
We need to host a file named AASA ( apple-app-site-association ), which has all the URLs or URL extensions, which can be used to open the app.
For example: If you have your app named "xyz" and you need to open your app on tapping a url https://xyz.com/register , you need to host an AASA file under the url https://xyz.com/apple-app-site-association.
Example of a sample AASA File to open your app for URL: https://xyz.com/register
We already cover the steps for creating and hosting the AASA file for you on registering your app in truecallerdevs.com.
You can check if the AASA for your app is available at: YOUR_APPLINK( provided by Truecaller )/.well-known/apple-app-site-association
It should look like: https://si44524554ef8e45b5aa83ced4e96d5xxx.truecallerdevs.com/.well-known/apple-app-site-association P.S : change the italic part to your app link.
How is the OS is notified about Associated Domains
Apple documentation on associated domains can be found here. Once you enable the associated domain capability for your app id, you can add associated domains entitlements with the necessary app links and web credentials. This is one of the steps in Truecaller SDK integration.
The OS on first installation of your app will try hitting these URLs for ./well-known/apple-app-site-association endpoints and if there is a file at the endpoint, it is downloaded to the OS. If the file is downloaded without any error, all the urls you specified will take the user to the app and if not, you will be redirected to Safari browser as if trying to open a normal URL. If there is an error in downloading the AASA file, we as the SDK or your app will not be manually able to download the file and hence it will keep on redirecting to safari. There is a three hour window of retry for AASA files depending on different status codes, that is the OS will retry downloading the AASA file after 3 hours and if it succeeds, all the redirections to your app works properly.
What to do if you face the safari redirection issue while testing the Truecaller iOS SDK integration with your app ?
If you encounter the safari redirection issue while integrating the Truecaller SDK with your iOS app, that probably means there’s some issue in downloading the AASA file for either your application or for the Truecaller app on your device. In such a scenario, you should try uninstalling and reinstalling your app build as well as Truecaller app from the device you are testing on, and re-try the flow after sometime. Usually, it may take a few hours ( as mentioned in the above section ) for the retry mechanism to kick in and download the updated AASA file on the device. Once that is successful, the flow should work absolutely fine.
Add the entry truesdk under LSApplicationQueriesSchemes in into your Info.plist file
Add the associated domain provided by Truecaller (for example applinks:si44524554ef8e45b5aa83ced4e96d5xxx.truecallerdevs.com) in Your project -> Capabilities > Associated Domains. The prefix 'applinks:' is needed for universal links to function properly.
Important: Replace the 'https://' part from the provided app link with "applinks:". ie https://si44524554ef8e45b5aa83ced4e96d5xxx.truecallerdevs.com
should become applinks:si44524554ef8e45b5aa83ced4e96d5xxx.truecallerdevs.com
while adding to entitlements.
(Note that there is no http:// or https:// prefix when setting up the applinks:)
Starting with SDK version 0.1.7, when redirection from Truecaller app to partner app fails (due to Universal Link failure) an error message is passed from Truecaller app using url scheme with following error details:
error code: 19 error description: "Cannot open app because Universal Link failed".
Starting with SDK version 0.1.7, It is mandatory to register urlScheme in your project, in the below format: truecallersdk-<#YOUR_APP_KEY> e.g if your app key is I7ViZ490028736bba408881687123b4cec49f, url scheme to be registered is truecallersdk-I7ViZ490028736bba408881687123b4cec49f
Please note that if you are using an older version of Truecaller SDK, an error message will be shown in the Truecaller app asking the user to manually navigate back to the partner app.
State
Description
TCVerificationStateOTPInitiated
Returned when OTP is successfully initiated by Truecaller
TCVerificationStateOTPReceived
Returned when OTP is successfully registered by the partner to Truecaller.
TCVerificationStateVerificationComplete
OTP verification successful at Truecaller
TCVerificationStateVerifiedBefore
The user has already been signed in from this device
In case of error, didFailToReceiveTrueProfileWithError: will return an object of type TCError (a subclass of NSError). You can get the error code by invoking the method getErrorCode on the TCError object. The list of possible TCTrueSDKErrorCode values can be found in the API documentation.
Error Code
Description
1
App Key is Missing. The App Key is a mandatory field. It is provided to you by Truecaller.
2
App Link is Missing. The App Link is a mandatory field. It is provided to you by Truecaller.
3
The user has decided to cancel (abort) the operation of providing TrueProfile info to your app.
4
The user has not signed in using the Truecaller app yet.
5
The SDK version is old and not compatible with the Truecaller app.
6
The Truecaller app version is old and not compatible with the SDK version.
7
Current version of iOS is not supported.
8
Truecaller App is Not Installed. The Truecaller app is not installed.
9
Network Error occurred in network communication or no network connectivity
10
Truecaller internal error.
11
The user has not been authorized by Truecaller servers.
12
The credentials cannot be verified. Internal error.
13
The Profile content is not valid. Internal error.
14
Bad request. Internal error.
15
Verification Failed because the response signature could not be verified. Internal error.
16
The request's nonce does not match the nonce in response. Internal error.
17
View delegate is Nil or not set.
18
Invalid first name or last name.
19
Cannot open app because Universal Link failed
20
Please add Url Scheme to plist