Manual Installation

1. Download the project zip file from the release section

2. Unzip the file

3. Copy the TruecallerSDK project files into your project ( TrueSDK directory, TrueSDKTests directory and TrueSDK.xcodeproj )

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

5. Add the TruecallerSDK framework ( from Products output of TrueSDK.xcodeproj ) into the Embedded Binaries section of the General tab of your target.

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:

$ gem install cocoapods

You can create your Podfile using the command ( in case you do not already have it ):

$ pod init

To integrate TruecallerSDK into your Xcode project using CocoaPods, specify it in your Podfile :

platform :ios, '8.0'
use_frameworks!

target 'TargetName' do
pod 'TrueSDK'
end

Then, run the following command:

$ pod install

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.

#import <TrueSDK/TrueSDK.h>

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:

if ([[TCTrueSDK sharedManager] isSupported]) {
    [[TCTrueSDK sharedManager] setupWithAppKey:<#YOUR_APP_KEY#> appLink:<#YOUR_APP_LINK#>];
}

Use the entire associated domain link provided by Truecaller for YOUR_APP_LINK. For example: https://si44524554ef8e45b5aa83ced4e96d5xxx.truecallerdevs.com (including https://).

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.

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
    return [[TCTrueSDK sharedManager] application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
}

4. Set the class where you want to receive TruecallerSDK events (the profile or errors) a TCTrueSDKDelegate

#import <UIKit/UIKit.h>
#import <TrueSDK/TrueSDK.h>

@interface ViewController : UIViewController <TCTrueSDKDelegate>

@end

5. Implement the two TCTrueSDKDelegate methods

- (void)didReceiveTrueProfile:(nonnull TCTrueProfile *)profile {
    //Custom code
}
- (void)didFailToReceiveTrueProfileWithError:(nonnull TCError *)error {
    //Custom code
}

The profile object is of type TCTrueProfile (written in Objective C) which offers the following user data:

typedef NS_ENUM(NSUInteger, TCTrueSDKGender) {
    TCTrueSDKGenderNotSpecified = 0, //
    TCTrueSDKGenderMale, //
    TCTrueSDKGenderFemale, //
};

/*!
 * @class TCTrueProfile
 * @brief The True Profile info returned.
 */

@interface TCTrueProfile : NSObject <NSCoding>

/*! @property firstName @brief User's first name */
@property (nonatomic, strong, nullable, readonly) NSString *firstName;
/*! @property lastName @brief User's last name */
@property (nonatomic, strong, nullable, readonly) NSString *lastName;
/*! @property phoneNumber @brief User's phone number */
@property (nonatomic, strong, nullable, readonly) NSString *phoneNumber;
/*! @property countryCode @brief User's country code */
@property (nonatomic, strong, nullable, readonly) NSString *countryCode;
/*! @property street @brief User's street address */
@property (nonatomic, strong, nullable, readonly) NSString *street;
/*! @property city @brief User's city */
@property (nonatomic, strong, nullable, readonly) NSString *city;
/*! @property zipCode @brief User's zip code */
@property (nonatomic, strong, nullable, readonly) NSString *zipCode;
/*! @property facebookID @brief User's facebook id */
@property (nonatomic, strong, nullable, readonly) NSString *facebookID;
/*! @property twitterID @brief User's twitter id */
@property (nonatomic, strong, nullable, readonly) NSString *twitterID;
/*! @property email @brief User's email */
@property (nonatomic, strong, nullable, readonly) NSString *email;
/*! @property url @brief User's Truecaller profile url */
@property (nonatomic, strong, nullable, readonly) NSString *url;
/*! @property avatarURL @brief User's avatar url */
@property (nonatomic, strong, nullable, readonly) NSString *avatarURL;
/*! @property jobTitle @brief User's job title */
@property (nonatomic, strong, nullable, readonly) NSString *jobTitle;
/*! @property companyName @brief User's company name */
@property (nonatomic, strong, nullable, readonly) NSString *companyName;
/*! @property gender @brief User's gender */
@property (nonatomic, assign, readonly) TCTrueSDKGender gender;
/*! @property isVerified @brief User's account special verification status */
@property (nonatomic, assign, readonly) BOOL isVerified;
/*! @property isAmbassador @brief Is the user a Truecaller ambasador */
@property (nonatomic, assign, readonly) BOOL isAmbassador;

6. Set the delegate property of the [TCTrueSDK sharedManager]. Make sure you do this before you request the True Profile.

[TCTrueSDK sharedManager].delegate = self;

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:

self.button.buttonStyle = TCButtonStyleBlue;
self.button.buttonCornersStyle = TCButtonCornersStyleRounded;

b. If you prefer to do it yourself, you can use the method requestTrueProfile.

[[TCTrueSDK sharedManager] requestTrueProfile];

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.

Swift 2.3 :

import TrueSDK

Swift 3+ :

import TrueSDK

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 :

//Setup TruecallerSDK
if TCTrueSDK.sharedManager().isSupported() {
    TCTrueSDK.sharedManager().setupWithAppKey(<#YOUR_APP_KEY#>, appLink:  <#YOUR_APP_LINK#>)
}

Swift 3+ :

//Setup TruecallerSDK
if TCTrueSDK.sharedManager().isSupported() {
    TCTrueSDK.sharedManager().setup(withAppKey: <#YOUR_APP_KEY#>, appLink: <#YOUR_APP_LINK#>)
}

Use the entire associated domain link provided by Truecaller for YOUR_APP_LINK. For example: https://si44524554ef8e45b5aa83ced4e96d5xxx.truecallerdevs.com (including https://).

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 :

func application(application: UIApplication, continueUserActivity userActivity: NSUserActivity, restorationHandler: ([AnyObject]?) -> Void) -> Bool {
    return TCTrueSDK.sharedManager().application(application, continueUserActivity: userActivity, restorationHandler: restorationHandler)
}

Swift 3+ :

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Swift.Void) -> Bool {
    return TCTrueSDK.sharedManager().application(application, continue: userActivity, restorationHandler: restorationHandler)
}

Swift 5 :

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    return TCTrueSDK.sharedManager().application(application, continue: userActivity, restorationHandler: restorationHandler as? ([Any]?) -> Void)
}

For apps using SceneDelegate instead of AppDelegate :

func scene(_ scene: UIScene,
                        continue userActivity: NSUserActivity) {
        TCTrueSDK.sharedManager().scene(scene, continue: userActivity)
    }

4. Set the class where you want to receive TruecallerSDK events (the profile or errors) a TCTrueSDKDelegate

Swift 2.3 :

class HostViewController: UIViewController, TCTrueSDKDelegate {

Swift 3+ :

class HostViewController: UIViewController, TCTrueSDKDelegate {

5. Implement the two TCTrueSDKDelegate methods

Swift 2.3 :

func didFailToReceiveTrueProfileWithError(error: TCError) {
    //Custom code here
}
func didReceiveTrueProfile(profile: TCTrueProfile) {
    //Custom code here
}

Swift 3+ :

func didFailToReceiveTrueProfileWithError(_ error: TCError) {
    //Custom code here
}
func didReceive(_ profile: TCTrueProfile) {
    //Custom code here
}

The profile object is of type TCTrueProfile (written in Objective C) which offers the following user data:

typedef NS_ENUM(NSUInteger, TCTrueSDKGender) {
    TCTrueSDKGenderNotSpecified = 0, //
    TCTrueSDKGenderMale, //
    TCTrueSDKGenderFemale, //
};

/*!
 * @class TCTrueProfile
 * @brief The True Profile info returned.
 */

@interface TCTrueProfile : NSObject <NSCoding>

/*! @property firstName @brief User's first name */
@property (nonatomic, strong, nullable, readonly) NSString *firstName;
/*! @property lastName @brief User's last name */
@property (nonatomic, strong, nullable, readonly) NSString *lastName;
/*! @property phoneNumber @brief User's phone number */
@property (nonatomic, strong, nullable, readonly) NSString *phoneNumber;
/*! @property countryCode @brief User's country code */
@property (nonatomic, strong, nullable, readonly) NSString *countryCode;
/*! @property street @brief User's street address */
@property (nonatomic, strong, nullable, readonly) NSString *street;
/*! @property city @brief User's city */
@property (nonatomic, strong, nullable, readonly) NSString *city;
/*! @property zipCode @brief User's zip code */
@property (nonatomic, strong, nullable, readonly) NSString *zipCode;
/*! @property facebookID @brief User's facebook id */
@property (nonatomic, strong, nullable, readonly) NSString *facebookID;
/*! @property twitterID @brief User's twitter id */
@property (nonatomic, strong, nullable, readonly) NSString *twitterID;
/*! @property email @brief User's email */
@property (nonatomic, strong, nullable, readonly) NSString *email;
/*! @property url @brief User's Truecaller profile url */
@property (nonatomic, strong, nullable, readonly) NSString *url;
/*! @property avatarURL @brief User's avatar url */
@property (nonatomic, strong, nullable, readonly) NSString *avatarURL;
/*! @property jobTitle @brief User's job title */
@property (nonatomic, strong, nullable, readonly) NSString *jobTitle;
/*! @property companyName @brief User's company name */
@property (nonatomic, strong, nullable, readonly) NSString *companyName;
/*! @property gender @brief User's gender */
@property (nonatomic, assign, readonly) TCTrueSDKGender gender;
/*! @property isVerified @brief User's account special verification status */
@property (nonatomic, assign, readonly) BOOL isVerified;
/*! @property isAmbassador @brief Is the user a Truecaller ambasador */
@property (nonatomic, assign, readonly) BOOL isAmbassador;

6. Set the delegate property of the TCTrueSDK.sharedManager(). Make sure you do this before you request the True Profile.

Swift 2.3 :

TCTrueSDK.sharedManager().delegate = self

Swift 3+ :

TCTrueSDK.sharedManager().delegate = self

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 :

self.button.buttonStyle = TCButtonStyleBlue
self.button.buttonCornersStyle = TCButtonCornersStyleRounded

Swift 3+ :

self.button.buttonStyle = TCButtonStyle.blue.rawValue
self.button.buttonCornersStyle = TCButtonCornersStyle.rounded.rawValue

b. If you prefer to do it yourself, you can use the method requestTrueProfile.

Swift 2.3 :

TCTrueSDK.sharedManager().requestTrueProfile()

Swift 3+ :

TCTrueSDK.sharedManager().requestTrueProfile()

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 to handle the redirection between Truecaller app and your app. The process involves 4 steps, as defined below :

1. User taps the “Sign up with Truecaller” option on your app

2. Universal link opens Truecaller app

3. 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 , you need to host an AASA file under the url .

Example of a sample AASA File to open your app for URL:

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

How is the OS is notified about Associated Domains

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.

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;

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>];

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

Add the entry truesdk under LSApplicationQueriesSchemes in into your Info.plist file

<key>LSApplicationQueriesSchemes</key>
<array>
<string>truesdk</string>
</array>

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.

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.

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.