CleverTap provides an iOS SDK that enables app developers to track, segment, and engage their users.

This guide will show you how to install the CleverTap SDK, track your first user event, and see this information within the CleverTap dashboard in less than ten minutes.

Step 1: Install SDK

To use the CleverTap iOS SDK, you have two options. You can install it with CocoaPods or manually install it by including the SDK source code in your Xcode project.

Option A - Install using CocoaPods (Recommended)

Add the CleverTap SDK to your Podfile as shown below.

pod "CleverTap-iOS-SDK"

Once you have updated your Podfile run pod install in your terminal to automatically download and install the SDK in your project.

Option B - Manual Install

Step 1: Download and unzip the CleverTap SDK

Step 2: Drag the CleverTapSDK.xcodeproj inside your project under the main project file

Step 3: Embed the framework. Select your app.xcodeproj file. Under "General", add the CleverTapSDK framework as an embedded binary

Step 2: Add CleverTap Credentials

To associate your iOS app with your CleverTap account, you will need to add your CleverTap credentials in the Info.plist file in your application.

Navigate to the Info.plist file in your project navigator.

First, create a key called CleverTapAccountID with type string.
Second, create a key called CleverTapToken with type string.

Insert the Account ID and Account Token values from your CleverTap account. These values are available on the Settings page. To navigate to the Settings page, log into your CleverTap account, click on the gear icon on the top right navigation, and select Settings dashboard.

Step 3: Installation Steps for Swift

For a project written in Swift, you are required to follow the below. If you are using Objective-C, please continue to step 4.

Starting with v3.1.4, the SDK includes a modulemap, allowing you to import the SDK as a module rather than using a bridging header. See the example implementation here.

If you are unable to do that you can use a bridging header instead. In that case:

• Add the example bridging-header.h (rename to YOUR-PROJECT-NAME-Bridging-Header.h, if you like) to your project.
• Add the path to that bridging-header.h in the Objective-C Bridging Header section of your project Build Settings.

Alternatively, you can also append the contents of the bridging-header.h to your existing Bridging Header file.

Step 4: SDK Integration

Import CleverTap.h to your AppDelegate.h file.

Import CleverTap.h into every class where you plan to record user events. For example, in the application below, we will record user events in the ViewController class by importing CleverTap.h in the ViewController.h file.

In your AppDelegate.m file, add [CleverTap autoIntegrate] within the application:didfinishlaunchingwithoptions: method. This creates an instance of the CleverTap class used to track app launches, receive in-app notifications, and enable deep-link tracking.

- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    [CleverTap autoIntegrate];
    ...
}

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject:AnyObject]?) -> Bool {
    ...
    CleverTap.autoIntegrate()
    ...
}

Step 5: Run Your Application

Build and run your application.

Navigate to your CleverTap dashboard. If you successfully integrated the CleverTap SDK, you will see a new active user.

Step 6: Add Information to a User Profile

A User Profile is automatically created in CleverTap for each user launching your application.

Initially, the User Profile starts out as anonymous, which means the profile does not contain any identifiable information about the user. You can enrich the profile with pre-defined attributes from the CleverTap data model, such as name and email. You can also add custom attributes that you define to extend the CleverTap data model.

Sending user profile information to CleverTap using our iOS SDK requires two steps. First, you have to build a NSDictionary object with the profile properties. Second, you have to call the SDK's profilePush method and pass the NSDictionary object you created as a parameter. The example below shows how to do this in Objective-C and Swift.

NSDictionary *profile = @{
                              //Update pre-defined profile properties
                              @"Name": @"Jack Montana",
                              @"Email": @"jack.montana@gmail.com",
                              //Update custom profile properties
                              @"Plan Type": @"Silver",
                              @"Favorite Food": @"Pizza"
                              };
    
[[CleverTap sharedInstance] profilePush:profile];

let profile: Dictionary<String, AnyObject> = [
    //Update pre-defined profile properties
    "Name": "Jack Montana",
    "Email": "jack.montana@gmail.com",
    //Update custom profile properties
    "Plan type": "Silver",
    "Favorite Food": "Pizza"
]

CleverTap.sharedInstance()?.profilePush(profile)

Here is how to update the user profile information within the viewDidLoad method.

When the profilePush method is called, the user profile information will be sent to CleverTap.

Let's see how this information appears within the CleverTap dashboard. Log into the dashboard, and then click on the Find People button under the Segment tab. In the By Identity box, enter the email you set on the user profile record, and then click the Find button.

If CleverTap finds a user profile with this email, you will be taken to that user record. On that page, we'll see name and email as pre-defined fields, and plan type and favorite food as custom fields.

Step 7: Track Custom Events

Once you integrate the CleverTap SDK, we automatically start tracking events, such as App Launch and Notification Viewed. In addition to the default events tracked by CleverTap, you can also track custom events.

To send custom events to CleverTap using our iOS SDK, you will have to call the recordEvent method with the name of the custom event you want to track. The example below shows how to do this in both Objective-C and Swift.

[[CleverTap sharedInstance] recordEvent:@"Product Viewed"];

CleverTap.sharedInstance()?.recordEvent("Product viewed")

Here is how to record the custom event within the viewDidLoad method.

Let's look at the same user profile in CleverTap from step 6. Click on the Activity button within the user profile record. This will show a list of activities associated with the user profile. If the custom event was successfully sent from your application to CleverTap, you will see it in this list.

Next Steps

Congrats on successfully integrating CleverTap into your iOS application!

You are now automatically tracking user events like app launches, and associating that information with profiles for each of your users. You also learned how to add information to a user profile and how to track custom events.

In the next iOS guide, you will learn more advanced options for tracking custom events and enriching user profiles.