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.

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. If you set up CleverTap in your app, CleverTap uses the manifest entries instead.

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 Set up CleverTap in your app if your app sends push notifications, calls CleverTap APIs directly, or tracks the first app screen.

Set up CleverTap in your app

Set up CleverTap in your app if you do any of the following:

• Send CleverTap push notifications to your app.
• Call CleverTap APIs directly from your app, for example Native Display or App Inbox.
• Track the first app screen in CleverTap.

RudderStack creates the CleverTap destination only after the RudderStack SDK fetches the source configuration. Until then, no CleverTap instance exists. CleverTap can drop a push notification that arrives while the app is closed. CleverTap also misses the first screen.

Follow these steps:

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. Use the same account as in your destination settings. If you set a region in the destination settings, 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 you set a region in the destination settings -->
    <meta-data android:name="CLEVERTAP_REGION" android:value="YOUR_REGION" />
</application>

3. Register CleverTap’s activity tracking and create the CleverTap instance in your Application class. Do both before you initialize the RudderStack SDK:

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.
        CleverTapAPI.getDefaultInstance(this)

        analytics = Analytics(
            configuration = Configuration(
                writeKey = "WRITE_KEY",
                application = this,
                dataPlaneUrl = "DATA_PLANE_URL",
            )
        )
        analytics.add(CleverTapIntegration())
    }
}

• 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, CleverTap starts with no account, and RudderStack cannot create the CleverTap destination.
• 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)
}

When RudderStack creates the destination later, the integration reuses your CleverTap instance:

• CleverTap keeps the credentials it started with, from the manifest entries. The credentials from the destination settings have no effect.
• CleverTap registers its activity tracking only once. The register call of the integration has no effect. CleverTap records each event only once.

Call CleverTap APIs

Get the CleverTap instance anywhere in your app with CleverTapAPI.getDefaultInstance(context). 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)

Important considerations

• Keep the Account ID and Account Token in the destination settings. Without them, the integration does not create the destination.
• When you set up CleverTap in your app, the manifest entries are the source of the CleverTap credentials. To change the account, change the manifest entries and release a new version of the app. If you do not set up CleverTap in your app, the destination settings are the source.
• If you disable the CleverTap destination in the RudderStack dashboard, RudderStack stops sending events to CleverTap. CleverTap still runs in your app and still shows push notifications.

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

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 Set up CleverTap in your app in the Android (Kotlin) tab of Adding device mode integration. 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 of Set up CleverTap in your app. That section is in the Android (Kotlin) tab of Adding device mode integration.

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