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.

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

Connection compatibility

Destination info
Status: Generally Available Supported sources: Android, iOS , Web, Unity, AMP , Cloud, Warehouse, React Native , Flutter, Cordova, Shopify Refer to it as CLEVERTAP in the Integrations object.

Connection modes
Source	Cloud mode	Device mode	Hybrid mode
AMP
Android
Cloud
Cordova
Flutter
iOS
React Native
Shopify
Unity
Warehouse
Web

Supported message types
Source	Identify	Page	Track	Screen	Group	Alias
Cloud mode
Supported sources
Device mode
Android
iOS
React Native
Web

In the web device mode integration, that is, using the JavaScript SDK as a source, RudderStack loads the CleverTap native SDK 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.

Get started

Once you have confirmed that the source platform supports sending events to CleverTap, follow these steps:

1. From your RudderStack dashboard, add a source. Then, from the list of destinations, select CleverTap.
2. Assign a name to the destination and click Continue.

Connection settings

To successfully set up 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 your CleverTap dashboard by going to Settings > 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: Select your CleverTap region.
• Client-side Events Filtering: Specify which events should be blocked or allowed to flow through to CleverTap. For more information on this setting, see the Client-side Events Filtering guide.
• Consent management provider: Configure the consent management settings for the specified source by choosing the consent management provider from the dropdown. If you choose Custom, make sure to pass the custom consent data to SDK.
• Use device mode to send events: Enable this option to send events in 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)

Identify

The identify call lets you associate a user with their actions and capture relevant traits about them. This information includes userId and other user information like name, email, etc.

RudderStack requires either userId or email to send identify events to CleverTap.

RudderStack maps the following user traits to the CleverTap attributes:

RudderStack sends all other traits 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, along with the associated user traits.

Note that:

• If a user already exists, the new values will be updated for that user. RudderStack automatically maps the userId (or anoymousId) to CleverTap’s identity attribute.
• The profile properties MSG-email, MSG-push, MSG-sms and MSG-whatsapp are used to set the Do Not Disturb (DND) status for the user. They are always true by default, unless you explicitly set them to false. For 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 in the back end to map the user’s location. 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>"
  }]
}

Track

The track call lets you capture user events along with the properties associated with them. The user is associated with userId or anonymousId by default.

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.

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 it 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",
    },
  ],
})

Order Completed is a free-flowing event. If you set extra fields like discount, coupon, currency, etc., RudderStack automatically maps them to the Charged event properties.

Page

The page call lets you record your website’s page views with any additional relevant information about the viewed page.

RudderStack sends a page 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 lets you record whenever your user views their mobile screen, with any additional relevant information about the screen.

A sample screen call is shown:

[[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: <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.

Alias

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

A sample alias call is shown below:

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

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

This section is applicable when sending events in cloud mode.

CleverTap uniquely identifies each user with two main identifiers, namely objectId and identity. When you enable the Use CleverTap ObjectId for Mapping option in the dashboard, RudderStack uses both objectId and identity and expects the following mapping:

• For identify events:

• For track events:

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

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 user activity details. 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 userId identifier (in case of RudderStack) which maps to CleverTap’s identity attribute.

One way to solve this problem is to track users only in cases where a userId is present. To do so, disable the Enable tracking for anonymous users option in the RudderStack dashboard. Alternatively, you can turn on 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.

Upload device token in 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 uses CleverTap’s Upload Device Tokens 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, enable the Use CleverTap ObjectId for Mapping option in the dashboard as RudderStack needs the objectId to upload the device token.

You can also define the token type irrespective of your operating system by sending your choice of device token via the event’s integrations object. The supported token types are listed below:

• chrome
• fcm
• gcm
• apns
• wns
• mpns

A sample integrations object is shown below:

integrations: {
  All: true,
  CleverTap: {
    deviceTokenType: 'apns',
  },
}

For the chrome device token type, you can also send the chromeKeys object within the integrations object, as shown:

 integrations: {
   All: true,
   CleverTap: {
     deviceTokenType: 'chrome',
     chromeKeys: {
       p256dh: '<value>',
       auth: '<value>'
     },
   },
 },

See the CleverTap documentation on uploading device tokens for more details.

Questions? Contact us by email or on Slack