CleverTap

Send your event data from RudderStack to 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.

Getting started

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

Connection ModeWebMobileServer
Device modeSupportedSupported-
Cloud modeSupportedSupportedSupported
info

In a 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.

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.
  • OneTrust Cookie Categories: This setting lets you associate OneTrust cookie consent groups to CleverTap.
  • Use device mode to send events: Enable this option to send events in device mode.
info
All server-side destination requests require either an anonymousId or a userId in the payload.

Adding device mode integration

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.

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

RudderStack maps the following user traits to the CleverTap attributes:

RudderStackCleverTap
nameName
birthdayDOB
avatarPhoto
genderGender
phonePhone
emailEmail
employedEmployed
educationEducation
marriedMarried
customerTypeCustomer Type

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.

info

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:

OptionData typeNotes
optOutBooleanDefaults to false. Set to true if the user opts out of sharing their data.
useIPBooleanDefaults to false. Set to true if the user agrees to share their IP data.
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.

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

info
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

RudderStackCleverTap
checkout_idCharged ID
revenueAmount
productsItems

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

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

Using CleverTap objectId and identity for mapping

info
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:
RudderStackRudderStackCleverTapCleverTap
anonymousId present?userId present?objectIdidentity
YesYesanonymousIduserId
YesNoanonymousId-
NoYesCleverTap-generated UUIDuserId
  • For track events:
RudderStackRudderStackCleverTapCleverTap
anonymousId present?userId present?Tracking withValue
YesYesobjectIdanonymousId
YesNoobjectIdanonymousId
NoYesidentityuserId

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):

RudderStackCleverTap
userId or anonymousIdidentity
info

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.

Device token upload using cloud mode

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

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

Questions? Contact us by email or on Slack