CleverTap

CleverTap is a popular customer engagement and retention platform. Its in-app analytics and marketing capabilities allow you to get real-time insights into your customers and build valuable, long-term relationships with them. With CleverTap, you can easily gain insights into your users’ actions and how they are using your product. You can also segment users based on their behavior and run targeted campaigns to boost user engagement and retention metrics.

Find the open source transformer code for this destination in the GitHub repository.

Getting started

RudderStack supports sending event data to CleverTap via the following connection modes:

In a web device mode integration, that is, using our JavaScript SDK as a source, the CleverTap native SDK is loaded from thehttps://d2r1yp2w7bby2u.cloudfront.net domain. Based on your website’s content security policy, you may need to allowlist this domain to load the CleverTap SDK.

Once you have confirmed that the platform supports sending events to CleverTap, perform the steps below:

• From your RudderStack dashboard, add the source and CleverTap as a destination.

Connection settings

To configure CleverTap as a destination, you will need to configure the following settings:

• Account ID: Your account ID is a unique ID generated for your account. It can be found in your account Settings as your Project ID.
• Passcode: Your account passcode is a unique code generated for your account. It can be found in the Settings as Passcode.
• Enable track for anonymous user: Enable this option to track anonymous users in CleverTap.
• Use CleverTap ObjectId for Mapping: Enable this option to use both CleverTap objectId along with identity for mapping events from RudderStack to CleverTap.
• Region: Server Only: This is your dedicated CleverTap region.
• Use Native SDK to send Events: Enable this option if you want to send events using device mode.

All server-side destination requests require either an anonymousId or a userId in the payload.

Adding device mode integration

buildscript {
  repositories {
    mavenCentral()
  }
}

allprojects {
  repositories {
    mavenCentral()
  }
}

// ruddder core sdk
implementation 'com.rudderstack.android.sdk:core:1.+'
// rudder-clevertap integration
implementation 'com.rudderstack.android.integration:clevertap:1.+'
// clevertap native sdk
implementation 'com.clevertap.android:clevertap-android-sdk:4.+'
// if you don't have Gson included already
implementation 'com.google.code.gson:gson:2.8.6'

// initialize Rudder SDK
val rudderClient =
    RudderClient.getInstance(
        this,
        WRITE_KEY,
        RudderConfig.Builder()
            .withDataPlaneUrl(DATA_PLANE_URL)
            .withFactory(CleverTapIntegrationFactory.FACTORY)
            .build()
    )

pod 'Rudder-CleverTap'

#import "RudderCleverTapFactory.h"

RudderConfigBuilder *builder = [[RudderConfigBuilder alloc] init];
[builder withDataPlaneUrl:DATA_PLANE_URL];
[builder withFactory:[RudderCleverTapFactory instance]];
[RudderClient getInstance:WRITE_KEY config:[builder build]];

npm install @rudderstack/rudder-integration-clevertap-react-native
## OR ##
yarn add @rudderstack/rudder-integration-clevertap-react-native

import rudderClient from "@rudderstack/rudder-sdk-react-native"
import clevertap from "@rudderstack/rudder-integration-clevertap-react-native"

const config = {
  dataPlaneUrl: DATA_PLANE_URL,
  trackAppLifecycleEvents: true,
  withFactories: [clevertap],
}
rudderClient.setup(WRITE_KEY, config)

Configuring push notifications and in-app messages

Follow these steps to configure CleverTap push notifications for your desired platform.

dependencies {
  classpath 'com.google.gms:google-services:4.3.5'
}

dependencies {
  // for push notifications
  implementation 'com.clevertap.android:clevertap-android-sdk:4.0.0'
  implementation 'com.google.firebase:firebase-messaging:20.2.4'
}
apply plugin: 'com.google.gms.google-services'

<meta-data android:name="CLEVERTAP_ACCOUNT_ID" android:value="XXX-XXX-XXXX"></meta-data>
<meta-data android:name="CLEVERTAP_TOKEN" android:value="XXX-XXX"></meta-data>
<service android:name="com.clevertap.android.sdk.pushnotification.fcm.FcmMessageListenerService">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT"></action>
</intent-filter>
</service>

CleverTapAPI.createNotificationChannel(
    getApplicationContext(),
    "yourChannelId",
    "Your Channel Name",
    "Your Channel Description",
    NotificationManager.IMPORTANCE_MAX,
    true
)

#import <usernotifications>

// register for push notifications
UNUserNotificationCenter* center = [UNUserNotificationCenter currentNotificationCenter];
center.delegate = self;
[center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge)
completionHandler:^(BOOL granted, NSError * _Nullable error) {
  if (granted) {
    dispatch_async(dispatch_get_main_queue(), ^(void) {
        [[UIApplication sharedApplication] registerForRemoteNotifications];
        });
  }
}];

#import "RudderCleverTapIntegration.h"

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  [[RudderCleverTapIntegration alloc] registeredForRemoteNotificationsWithDeviceToken:deviceToken];
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  [[RudderCleverTapIntegration alloc] receivedRemoteNotification:userInfo];
  completionHandler(UIBackgroundFetchResultNoData);
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
  completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
  [[RudderCleverTapIntegration alloc] receivedRemoteNotification:response.notification.request.content.userInfo];
}

Using CleverTap objectId and identity for mapping (cloud mode only)

CleverTap uniquely identifies each user with two main identifiers, namely objectId and identity. When the Use CleverTap ObjectId for Mapping option is enabled in the dashboard, both objectId and identity are used for mapping.

When the Use CleverTap ObjectId for Mapping setting is disabled in the dashboard, RudderStack expects the the following mapping for identifying users and tracking events (track/page/screen):

When the Use CleverTap ObjectId for Mapping setting is enabled in the dashboard, the following mapping is expected:

• For identify events:

• For track events:

Why use CleverTap objectId for mapping?

When you track an unidentified user in CleverTap, a user profile is created with minimal details, along with the details of the user’s activity. When the same user is then identified with a userId without the Use CleverTap ObjectId for Mapping option enabled, RudderStack creates another profile for the user with the identifier userId (in case of RudderStack) which maps to identity (in case of CleverTap).

One way to solve this problem is to track users only in cases where a userId is present. To do so, you can disable the Enable tracking for anonymous users option in the RudderStack dashboard. Alternatively, you can enable the Use CleverTap ObjectId for Mapping option in the dashboard which allows you to track the anonymous users and when they are later identified, merge their anonymousId with their userId.

Device token upload using cloud mode

This section is applicable for the Android and iOS sources when sending events via cloud mode.

When the device token is present in context.device.token in identify calls, RudderStack will use the CleverTap Device Token Upload API to upload the device token for the identified user. For Android, RudderStack sets the token type as fcm. For iOS, it is set as apns.

To use this feature you should have enabled the Use CleverTap ObjectId for Mapping option in the dashboard, as RudderStack needs the objectId to upload the device token.

Page

The page call allows you to record information whenever a user sees a web page, along with its associated properties.

When you send a page event , RudderStack sends that event to CleverTap as a “Web Page Viewed Page Name event.

An example of a page call is shown below:

rudderanalytics.page("Cart", "Cart Viewed", {
  path: "/cart",
  referrer: "test.com",
  search: "term",
  title: "test_item",
  url: "http://test.in",
})

CleverTap does not support nested objects or arrays for custom attributes in the page events. Hence, RudderStack converts the nested objects or arrays into strings before sending them to CleverTap.

Screen

The screen method allows you to record whenever a user sees the mobile screen, along with any associated optional properties. This call is similar to the page call, but is exclusive to your mobile device.

A sample screen call looks like the following code snippet:

[[RSClient sharedInstance] screen:@"Sample Screen Name"
        properties:@{@"prop_key" : @"prop_value"}];

In the above snippet, RudderStack captures all information related to the screen being viewed, along with any additional info associated with that screen view event. In CleverTap, the above screen call will be shown as - “Screen Viewed: Sample Screen Name “ along with the properties.

CleverTap does not support nested objects or arrays for custom attributes in the screen events. Hence, RudderStack converts the nested objects or arrays into strings before sending them to CleverTap.

Track

The track call allows you to capture any action that the user might perform, along with the properties associated with that action. Each action is considered to be an event. It is similar to screen event, and the user is by default associated with userId or anonymousId.

A sample track call looks like the following:

rudderanalytics.track("Checked Out", {
  Clicked_Rush_delivery_Button: true,
  total_value: 2000,
  revenue: 2000,
})

In the above snippet, RudderStack captures the information related to the Checked Out event, along with any additional info about that event - in this case the details of the Checked out event.

To set a specific value to the screen or track type event, you need to pass the event related property in the properties field.

CleverTap does not support nested objects or arrays for custom attributes in the track events. Hence, RudderStack converts the nested objects or arrays into strings before sending them to CleverTap.

Order Completed

When you track an event with the name Order Completed using the using the RudderStack Ecommerce Events tracking, RudderStack maps that event to CleverTap’s Charged event.

A number of RudderStack’s specific fields map to CleverTap’s standard Charged event fields

A sample Order Completed event looks like the following:

rudderanalytics.track("Order Completed", {
  checkout_id: "12345",
  order_id: "1234",
  affiliation: "Apple Store",
  "Payment mode": "Credit Card",
  total: 20,
  revenue: 15.0,
  shipping: 22,
  tax: 1,
  discount: 1.5,
  coupon: "Games",
  currency: "USD",
  products: [
    {
      product_id: "123",
      sku: "G-32",
      name: "Monopoly",
      price: 14,
      quantity: 1,
      category: "Games",
      url: "https://www.website.com/product/path",
      image_url: "https://www.website.com/product/path.jpg",
    },
    {
      product_id: "345",
      sku: "F-32",
      name: "UNO",
      price: 3.45,
      quantity: 2,
      category: "Games",
    },
    {
      product_id: "125",
      sku: "S-32",
      name: "Ludo",
      price: 14,
      quantity: 7,
      category: "Games",
      brand: "Ludo King",
    },
  ],
})

The Order Completed ecommerce event is a free-flowing event. If you are setting extra fields, for example: discount, coupon, currency, etc., these will be automatically set to Charged event properties.

Identify

The identify call lets you associate a user with their actions and capture relevant traits about them. This information includes unique userid as well as any optional information such as name, email, etc.

Passing one of userId or email is required for identify calls to CleverTap.

A number of RudderStack’s special traits map to CleverTap’s standard user profile fields, as shown in the table below. You will be required to pass the key on the left into RudderStack and RudderStack will transform it to the key on the right before sending to CleverTap.

All other traits will be sent to CleverTap as custom attributes.

A sample identify call looks like the following:

rudderanalytics.identify("userid", {
  name: "Name Surname",
  email: "name@website.com",
  phone: "phone",
  birthday: "birthday",
  gender: "M",
  avatar: "link to image",
  title: "Owner",
  organization: "Company",
  city: "Tokyo",
  region: "ABC",
  country: "JP",
  zip: "100-0001",
  Flagged: false,
  Residence: "Shibuya",
  MSG-email: false
});

In the above snippet, RudderStack captures relevant information about the user such as the email and phone, as well as the associated traits of that user.

If a user already exists, the new values will be updated for that user. RudderStack automatically maps the userId (or anoymousId) to CleverTap user’s identity.

CleverTap does not support nested objects or arrays for custom attributes in the identify events. Hence, RudderStack converts the nested objects or arrays into strings before sending them to CleverTap.

Profile properties MSG-email, MSG-push, MSG-sms and MSG-whatsapp are used to set the Do-Not-Disturb status for the user. Unless these are explicitly set to false, they are always true.

Example: To disable push notifications for a user, set MSG-push to false

Privacy options

When loading the RudderStack SDK, you can set the following options in the CLEVERTAP integrations object:

rudderanalytics.load(
            "WRITE_KEY",
            "DATAPLANE_URL",
            {
                configUrl: "https://api.rudderlabs.com", logLevel: "DEBUG", integrations: {
                    CLEVERTAP: {
                        optOut: true,
                        useIP: true,
                    }
                }
            }
        );

CleverTap does a reverse lookup on the IP of the incoming request on the back end to map the location of the user. Under GDPR laws, user consent is required to initiate this lookup. Use the useIP flag in the web SDK to provide that consent.

If useIP is set to true, the city/country information will populate on the Profile page of the CleverTap dashboard. If set to false, then this data won’t be populated, and the city/country information will be shown as Unknown, Unknown.

See the CleverTap documentation for more information.

Deleting a user

You can delete a user in CleverTap using the Suppression with Delete regulation of the RudderStack User Suppression API.

To delete a user, you must specify their userId in the event. Additionally, you can specify a custom identifier (optional) in the event.

A sample regulation request body for deleting a user in CleverTap is shown below:

{
  "regulationType": "suppress_with_delete",
  "destinationIds": [
    "2FIKkByqn37FhzczP23eZmURciA"
  ],
  "users": [{
    "userId": "1hKOmRA4GRlm",
    "<customKey>": "<customValue>"
  }]
}

Alias

The alias call lets you merge different identities of a known user.

A sample alias call is shown below:

rudderanalytics.alias("newUserId","userId");

Questions? Contact us by email or on Slack