CleverTap

Follow these steps to add CleverTap to your Swift project using Swift Package Manager:

1. In Xcode, select File > Add Package Dependencies….

2. Enter the below package repository URL in the search bar:

https://github.com/rudderlabs/integration-swift-clevertap/

3. Select the latest version and the target to which you want to add the package.
4. Click Add Package.

Alternatively, you can add the dependency to your Package.swift file, as shown:

dependencies: [
    .package(url: "https://github.com/rudderlabs/integration-swift-clevertap.git", from: "<latest_integration_version>")
]

Usage

1. Import the SDK and the integration:

import RudderStackAnalytics
import RudderIntegrationCleverTap

2. Add CleverTapIntegration to your analytics instance:

// Initialize RudderStack Analytics
let analytics = Analytics(
    configuration: Configuration(
        writeKey: "<WRITE_KEY>",
        dataPlaneUrl: "<DATA_PLANE_URL>"
    )
)

// Add CleverTap Integration
analytics.add(plugin: CleverTapIntegration())

The Swift integration initializes the CleverTap iOS SDK from your RudderStack dashboard settings when you enable device mode. Configure Account ID, Account Token, and Region in the destination settings before adding the plugin to your app. Server-side CleverTap API requests use the Passcode setting. To set up CleverTap in your app instead, see Use your own CleverTap instance.

The CleverTap integration requires a minimum SDK version (minSdk) of 23.

Follow these steps to add CleverTap to your Kotlin project:

1. In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle.kts or <project>/<app-module>/build.gradle), add the following dependencies:

dependencies {
  // ...

  // Add Rudder Kotlin and CleverTap integration SDKs:
  implementation("com.rudderstack.sdk.kotlin:android:<latest-version>")
  implementation("com.rudderstack.integration.kotlin:clevertap:<latest-version>")
}

The integration supports the CleverTap Android SDK versions in the range [8.4.1, 9.0.0). The CleverTap integration 2.0.0 and later requires the Android (Kotlin) SDK 2.0.0 or later.

2. Add the following permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

3. Add the SDK initialization and the CleverTapIntegration in your Application class:

import android.app.Application
import com.rudderstack.sdk.kotlin.android.Analytics
import com.rudderstack.sdk.kotlin.android.Configuration
import com.rudderstack.integration.kotlin.clevertap.CleverTapIntegration

class MyApplication : Application() {
    lateinit var analytics: Analytics

    override fun onCreate() {
        super.onCreate()
        analytics = Analytics(
            configuration = Configuration(
                writeKey = "WRITE_KEY",
                application = this,
                dataPlaneUrl = "DATA_PLANE_URL",
            )
        )

        analytics.add(CleverTapIntegration())
    }
}

The integration initializes the CleverTap SDK with the Account ID, Account Token, and Region values from your destination settings. To set up CleverTap in your app instead, see Use your own CleverTap instance.

Breaking changes

To upgrade, raise your minSdk to 23, move to the Android (Kotlin) SDK 2.0.0 or later, and follow the steps in Use your own CleverTap instance if your app sends push notifications, calls CleverTap APIs directly, or tracks the first app screen.

To add CleverTap to your React Native project:

1. Add the RudderStack-CleverTap module to your app using:

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

2. Run pod install inside the ios directory of your project adding @rudderstack/rudder-integration-clevertap-react-native to your project.

3. Import the module you added above and add it to your SDK initialization code as shown below:

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)

To add CleverTap to your Android project and enable functionalities like push notifications, follow these steps:

1. Open your project level build.gradle file, and add the following:

buildscript {
  repositories {
    mavenCentral()
  }
}

allprojects {
  repositories {
    mavenCentral()
  }
}

2. Ensure that android.useAndroidX is set to true in your gradle.properties file. Add the following under the dependencies section:

// 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'

3. Initialize the RudderStack SDK in the Application class’s onCreate() method as shown:

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

Follow these steps to add CleverTap to your iOS project:

1. Go your Podfile and add the Rudder-CleverTap extension as shown below:

pod 'Rudder-CleverTap'

2. After adding the dependency followed by pod install , you can add the imports to your AppDelegate.m file:

#import "RudderCleverTapFactory.h"

3. Change the initialization of your RudderClient as shown:

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

You can use your own CleverTap instance in the CleverTap Android (Kotlin) integration v2.1.0 and above.

1. Add the CleverTap Android SDK to your module (app-level) Gradle file. Use a version in the range [8.4.1, 9.0.0):

This step does not increase your app size. The CleverTap integration already includes the CleverTap Android SDK as a transitive dependency, so the SDK is already packaged in your app.

dependencies {
  // ...
  implementation("com.clevertap.android:clevertap-android-sdk:<version>")
}

2. Add your CleverTap account ID and account token to the application tag of your AndroidManifest.xml file. If your account uses a region, also add CLEVERTAP_REGION.

<application>
    <meta-data android:name="CLEVERTAP_ACCOUNT_ID" android:value="YOUR_ACCOUNT_ID" />
    <meta-data android:name="CLEVERTAP_TOKEN" android:value="YOUR_ACCOUNT_TOKEN" />
    <!-- Only if your account uses a region -->
    <meta-data android:name="CLEVERTAP_REGION" android:value="YOUR_REGION" />
</application>

3. In your Application class, register CleverTap’s activity tracking and create the CleverTap instance. Do both before you initialize the RudderStack SDK. Then pass the instance to the integration:

import android.app.Application
import com.clevertap.android.sdk.ActivityLifecycleCallback
import com.clevertap.android.sdk.CleverTapAPI
import com.rudderstack.integration.kotlin.clevertap.CleverTapIntegration
import com.rudderstack.sdk.kotlin.android.Analytics
import com.rudderstack.sdk.kotlin.android.Configuration

class MyApplication : Application() {
    lateinit var analytics: Analytics

    override fun onCreate() {
        // Lets CleverTap track the first screen, notification clicks, and deep links.
        ActivityLifecycleCallback.register(this)
        super.onCreate()

        // Creates the CleverTap instance from the manifest entries.
        val cleverTap = CleverTapAPI.getDefaultInstance(this)

        analytics = Analytics(
            configuration = Configuration(
                writeKey = "WRITE_KEY",
                application = this,
                dataPlaneUrl = "DATA_PLANE_URL",
            )
        )
        cleverTap?.let { analytics.add(CleverTapIntegration(it)) }
    }
}

Important considerations

• Do not call ActivityLifecycleCallback.register or getDefaultInstance without the manifest entries from step 2. CleverTap reads its credentials only once, when it starts. Without the manifest entries, getDefaultInstance returns no instance.
• Create the CleverTap instance on the main thread, in Application.onCreate. Do not create it on a background thread or executor. When a push notification starts a closed app, the CleverTap instance must exist before its push handler runs.

4. In each activity that a notification can open, forward the notification click and the deep link from onNewIntent:

import android.content.Intent
import com.clevertap.android.sdk.CleverTapAPI

// In your activity
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    val cleverTap = CleverTapAPI.getDefaultInstance(this)
    cleverTap?.pushNotificationClickedEvent(intent.extras)
    cleverTap?.pushDeepLink(intent.data)
}

If you pass an instance that you created with CleverTapInstanceConfig, call these methods on that instance. getDefaultInstance returns only the default instance.

The CleverTap integration v2.0.0 has no constructor that takes an instance. With v2.0.0, follow steps 1 to 4, but add CleverTapIntegration() in step 3. The integration then reuses your default CleverTap instance:

• CleverTap keeps the credentials it started with, from the manifest entries. The credentials from the destination settings have no effect, but they must still hold valid values. Without them, the integration does not create the destination.
• CleverTap registers its activity tracking only once. The register call of the integration has no effect.

Call CleverTap APIs

Get the CleverTap instance anywhere in your app with CleverTapAPI.getDefaultInstance(context). If you pass an instance that you created with CleverTapInstanceConfig, use that instance instead. For example, to use Native Display:

import com.clevertap.android.sdk.CleverTapAPI

val cleverTap = CleverTapAPI.getDefaultInstance(context)

cleverTap?.setDisplayUnitListener { units ->
    // Render the display units.
}

// unitId: the ID of a display unit, from CleverTapDisplayUnit.unitID
val units = cleverTap?.allDisplayUnits
val unit = cleverTap?.getDisplayUnitForId(unitId)
cleverTap?.pushDisplayUnitViewedEventForID(unitId)
cleverTap?.pushDisplayUnitClickedEventForID(unitId)

You can use your own CleverTap instance in the CleverTap iOS (Swift) integration v2.0.0 and above. Note that this integration requires the iOS (Swift) SDK v2.0.0 or above.

1. Add the CleverTap iOS SDK to your app target with Swift Package Manager. Use the package https://github.com/CleverTap/clevertap-ios-sdk.git, the product CleverTapSDK, and a version in the range [7.8.1, 8.0.0).
2. Add your CleverTap account ID and account token to your Info.plist file, with the keys CleverTapAccountID and CleverTapToken. If your account uses a region, also add CleverTapRegion.
3. In application(_:didFinishLaunchingWithOptions:) of your app delegate, set up CleverTap. Then pass the instance to the integration:

import CleverTapSDK
import RudderIntegrationCleverTap

// Sets up CleverTap from the Info.plist entries
CleverTap.autoIntegrate()

// Pass your CleverTap instance to the integration
if let cleverTap = CleverTap.sharedInstance() {
  analytics.add(plugin: CleverTapIntegration(cleverTap: cleverTap))
}

In Objective-C, use [[RSSCleverTapIntegration alloc] initWithCleverTap:cleverTap].

Use the JavaScript SDK’s device mode integration for web push. RudderStack loads CleverTap’s Web SDK; your website hosts the service worker and requests notification permission through CleverTap’s API.

Configure web push

1. Connect your JavaScript source to CleverTap and enable Use device mode to send events in the Connection settings. Use the Account ID and Region for the CleverTap project where you configure web push.

2. In CleverTap, open Settings > Engage > Channels > Web Push. Generate and upload your VAPID keys, then enable each browser channel you support. For Chrome, enable Chrome Web Push. See Generating VAPID keys for instructions. Keep the private key out of your website code.

Saving VAPID keys doesn’t activate a browser channel. Chrome Web Push must be enabled for Chrome to receive its push configuration and public key.

3. For the queued soft prompt example below, enable Soft Prompt > Card Popup in CleverTap’s Web Push settings. See Soft prompt setup.

Host the service worker

Download clevertap_sw.js and host it at your website’s document root:

https://www.example.com/clevertap_sw.js

This URL must return JavaScript, not your app’s HTML page. In React, Next.js, or Vite, you can usually place the file in public/clevertap_sw.js.

The worker’s entry file must be served from your website’s origin. If you already have a service worker, follow Integration with existing service worker file and use its path as serviceWorkerPath in the examples below.

Initialize the SDK

Initialize the CleverTap global and queues in your page’s <head> before the JavaScript SDK installation snippet:

<script>
  window.clevertap = window.clevertap || {};
  window.clevertap.event = window.clevertap.event || [];
  window.clevertap.profile = window.clevertap.profile || [];
  window.clevertap.onUserLogin = window.clevertap.onUserLogin || [];
  window.clevertap.notifications = window.clevertap.notifications || [];
  window.clevertap.privacy = window.clevertap.privacy || [];
</script>

Don’t set window.clevertap.account. RudderStack replaces it with the Account ID from your destination settings and ignores any account set on the page. If the page sets a different account, RudderStack also removes the page’s region, targetDomain, and token, and uses the Region from your destination settings.

The integration supports one CleverTap account per page. Don’t load CleverTap’s SDK separately: if it’s already loaded when RudderStack initializes the destination, RudderStack replaces it.

Install and initialize RudderStack once with your source write key and data plane URL. For single-page apps, use shared client-side startup code. You don’t need a separate CleverTap installation snippet.

Queue a permission request

Call the following from your page or app after a meaningful action, such as completing a purchase:

window.clevertap.notifications.push({
  titleText: "Receive order updates?",
  bodyText: "Get notifications about your orders.",
  okButtonText: "Enable",
  rejectButtonText: "Later",
  skipDialog: false,
  serviceWorkerPath: "/clevertap_sw.js",
});

You can queue this request before CleverTap loads without waiting for rudderanalytics.ready(). The integration preserves the existing global and queued calls, except the account; CleverTap processes the request through its initialization flow.

Once CleverTap loads, the same API calls go directly to its SDK.

Queue one permission request per interaction. Queuing doesn’t bypass your destination or consent settings: a request isn’t processed if the destination doesn’t load. Continue using rudderanalytics.identify() for signed-in users and rudderanalytics.track() for analytics events.

Use SDK readiness for a direct prompt

Use rudderanalytics.ready() when your page needs the SDK’s readiness signal or an initialized CleverTap instance. This callback waits for RudderStack and its device mode destinations to initialize; queued calls don’t require it.

For example, enable a notification button in the callback, then request the native browser prompt when the user clicks the button:

<button id="enable-web-push" disabled>Enable notifications</button>
<script>
  const pushButton = document.getElementById("enable-web-push");

  // Run after your existing RudderStack initialization.
  rudderanalytics.ready(() => {
    const ct = window.clevertap;
    if (!ct || ct.logout === undefined || !ct.notifications) return;

    pushButton.disabled = false;
    pushButton.addEventListener("click", () => {
      ct.notifications.push({
        skipDialog: true,
        serviceWorkerPath: "/clevertap_sw.js",
      });
    });
  });
</script>

Keep the native permission request in the click handler. Browsers may require a fresh user interaction, which a queued request or a ready() callback doesn’t preserve. The soft prompt provides that interaction after the SDK loads.

Verify web push

1. Open your HTTPS website in a regular browser window. For local desktop Chrome testing, http://localhost is supported. Chrome treats localhost as a secure context, and CleverTap’s SDK allows it over HTTP. See Service Worker API.
2. Trigger the permission request and accept the soft prompt and browser permission. CleverTap registers the service worker during subscription; loading its SDK alone doesn’t register the worker.
3. Confirm that notification permission is granted, the service worker is active, and a push subscription exists. Then send a test Web Push campaign from CleverTap to the subscribed browser or user profile.

For iOS/iPadOS, configure a web app manifest and have users add your website to their Home Screen before requesting permission. See iOS/iPadOS web push configurations.

Web push is not supported in private browsing or embedded app browsers.

Troubleshoot web push

The iOS (Swift) CleverTap device mode integration does not handle push notification registration, push notification forwarding, device token forwarding, or in-app message setup.

To use CleverTap push notifications or in-app messages in a Swift app, configure them directly with the CleverTap iOS SDK and the Apple notification APIs.

First, complete the Android (Kotlin) steps in Use your own CleverTap instance. Then follow these steps to send push notifications to your app through CleverTap:

1. Register your app for push notifications in the CleverTap dashboard under Settings > Channels > Mobile Push > Android. Provide your Firebase Cloud Messaging credentials.
2. Register your app in the Firebase console, download the google-services.json file, and copy it to the app folder of your project.
3. Add the Google services plugin to your root-level Gradle file:

plugins {
  // ...
  id("com.google.gms.google-services") version "<latest-version>" apply false
}

4. In your module (app-level) Gradle file, apply the plugin and add the Firebase Cloud Messaging dependency:

plugins {
  // ...
  id("com.google.gms.google-services")
}

dependencies {
  // ...
  implementation("com.google.firebase:firebase-messaging:<latest-version>")
}

For Firebase Cloud Messaging push delivery, declare CleverTap’s messaging service in the application tag of your AndroidManifest.xml file:

<service
    android:name="com.clevertap.android.sdk.pushnotification.fcm.FcmMessageListenerService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

5. Create a notification channel in your Application class, after you create the CleverTap instance:

CleverTapAPI.createNotificationChannel(
    applicationContext,
    "YourChannelId",
    "Your Channel Name",
    "Your Channel Description",
    NotificationManager.IMPORTANCE_MAX,
    true
)

6. Request the POST_NOTIFICATIONS runtime permission if your app targets Android 13 or above. The CleverTap SDK declares the permission, but your app must request it from the user.

Notification clicks and deep links

CleverTap reads the notification click details and the deep link from the activity intent. To forward a click that reaches an open activity through onNewIntent, see step 4 in the Android (Kotlin) tab of Use your own CleverTap instance.

You can also forward the details through the integration. Keep a reference to the integration. The integration ignores these calls until RudderStack creates the destination:

// In Application.onCreate
val cleverTapIntegration = CleverTapIntegration()
analytics.add(cleverTapIntegration)

// In the activity's onNewIntent
cleverTapIntegration.pushNotificationClickedEvent(intent.extras)
cleverTapIntegration.pushDeepLink(intent.data)

In-app messages

CleverTap uses its own activity tracking to display in-app messages. You do not need extra setup. You do not need to set android:name to com.clevertap.android.sdk.Application in your AndroidManifest.xml file.

1. Open the android folder of your React Native app and follow the steps listed in the Android tab of this section.
2. Open the ios folder of your React Native app and follow the steps listed in the iOS tab of this section.

1. Register push notifications for Android devices on your CleverTap dashboard either by uploading your FCM credentials or any other supported credentials by navigating to Settings > Channels > Mobile Push > Android. Add the following dependency in your project level build.gradle file inside the buildscript:

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

2. Add the following dependencies and plugin to your app level build.gradle file:

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'

3. Place the google-services.json downloaded from the Firebase console into the root folder of your app. Add your CLEVERTAP_ACCOUNT_ID , CLEVERTAP_TOKEN & FcmMessageListenerService to the application tag of your app’s AndroidManifest.xml:

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

4. Create a notification channel anywhere in your application using the following block of code. You can then use this channel Id while creating any campaign in your CleverTap dashboard.

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

For push notifications and In-app messages to function correctly, CleverTap needs to know the Application status as early as possible. You can either set android:name in your AndroidManifest.xml tag to com.clevertap.android.sdk.Application. If you have a custom Application class, call ActivityLifecycleCallback.register(this); before super.onCreate().

To learn more about push notifications in CleverTap, see the CleverTap documentation.

1. Navigate to Target > Signing & Capabilities in Xcode.
2. Enable Background Modes/Remote notifications by navigating to Targets > Your App > Capabilities > Background Modes and checking Remote notifications.
3. Navigate to Settings > Channels > Mobile Push > iOS.
4. Register push notifications for the iOS devices on your CleverTap dashboard either by uploading your Auth Key or APNS push certificate.
5. Add the following code in your app just after initializing iOS (Obj-C) SDKiOS (Obj-C) refers to the legacy RudderStack iOS SDK. Note that it will be deprecated soon.
   
   For new implementations, use the iOS (Swift) SDK instead. to register push notifications.

#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];
        });
  }
}];

6. Add these handlers for the tokens and push notifications:

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