Skip to main content
CleverTapChange your setup in the sidebar

Digia Clevertap Integration

The Digia CleverTap plugin intercepts CleverTap In-App and CleverTap Native Display campaign payloads and pipes them directly into Digia's rendering engine. When a campaign triggers, the plugin maps the incoming payload to your custom UI designs built in the Digia Engage Dashboard, instantly rendering a 100% native experience on the device—no WebViews required. Supported experience types include bottom sheets, dialogs, inline banners, tooltips, and spotlights.

info

Prefer a quick visual walkthrough first? Watch How to Integrate Digia Engage and CleverTap for Campaigns.

This guide walks you through the end-to-end integration process—covering SDK installation, plugin initialization, and how to map your dashboard campaigns to Digia's native components.

Prerequisites​

Before integrating, ensure you have:

  • Digia Access Key: Log in to the Digia Engage Dashboard, open your project, and copy your key from Settings → App Settings.
  • Active Dashboard Account: Ensure you have an active CleverTap workspace with access to your App/Account IDs.
  • CleverTap SDK: Installed and initialized (see Flutter, Android, iOS, or React Native Quick Start).

Minimum Supported Versions​

Install​

Note: We assume the core CleverTap SDK is already installed and initialized as part of your standard app setup (see Prerequisites). The snippets below only cover adding the Digia plugin packages.

Install the Digia packages:

npm install @digia-engage/core@2.22.0 @digia-engage/clevertap@2.5.0

Initialize Digia with CleverTap​

Set up Digia and register the CleverTap plugin during app startup.

JS setup

import { useEffect } from 'react';
import CleverTap from 'clevertap-react-native';
import { Digia } from '@digia-engage/core';
import { DigiaCleverTapPlugin, createCleverTapClient } from '@digia-engage/clevertap';

export function RootApp() {
  useEffect(() => {
    (async () => {
      // 1. CleverTap SDK — must be initialized as a prerequisite.

      // 2. Initialize Digia once at startup.
      await Digia.initialize({
        apiKey: 'YOUR_ACCESS_KEY',
      });

      // 3. Register the Digia CleverTap plugin.
      Digia.register(
        new DigiaCleverTapPlugin({
          cleverTap: createCleverTapClient(CleverTap),
        })
      );

      // 4. Wire screen tracking to your navigation library.
      // Call Digia.setCurrentScreen(routeName) on every navigation change so
      // screen-triggered campaigns fire on the correct screen.
    })().catch(console.error);
  }, []);

  return <AppNavigator />;
}

Android native setup

Important: Even in a React Native app, the CleverTap SDK requires Activity lifecycle registration on the Android side. Without it, all In-App campaigns (including App Launch triggers), push notification click callbacks from the killed state, and session tracking will not work. See the CleverTap React Native Android integration guide.

  • Extending CleverTapApplication — registration is handled automatically. No extra call needed.
  • Not extending CleverTapApplication — call ActivityLifecycleCallback.register(this) manually in MainApplication.onCreate(), before super.onCreate():
import com.clevertap.android.sdk.ActivityLifecycleCallback
import com.clevertap.react.CleverTapRnAPI

class MainApplication : ReactApplication {
    override fun onCreate() {
        ActivityLifecycleCallback.register(this) // must be before super.onCreate()
        super.onCreate()
        CleverTapRnAPI.initReactNativeIntegration(this) // must be after super.onCreate()
        // ...
    }
}

Also required: CleverTapRnAPI.initReactNativeIntegration(this) must be called after super.onCreate(). Without it, push notification click callbacks will not fire when the app is in the killed state (ClevertapPushNotificationClicked event will be lost).

iOS native setup

Important: Even in a React Native app, CleverTap.autoIntegrate() must be called in your native AppDelegate before the React bridge initializes. Without it, CleverTap cannot intercept push notifications, deep links, or app launch events on iOS — meaning App Launch triggered campaigns, push notification handling, and In-App display will not work. See the CleverTap React Native iOS integration guide.

// AppDelegate.swift
import CleverTapSDK
import CleverTapReact

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        CleverTap.autoIntegrate()
        CleverTapReactManager.sharedInstance()?.applicationDidLaunch(options: launchOptions)
        // ...
        return true
    }
}

Advanced Config Options (React Native)​

Digia.initialize() accepts additional fields that control SDK behaviour:

await Digia.initialize({
  apiKey: 'YOUR_ACCESS_KEY',
  environment: 'production',   // 'production' | 'sandbox' — defaults to 'production'
  logLevel: 'error',           // 'none' | 'error' | 'verbose' — defaults to 'error'
  actionHandlers: {
    // Own how specific campaign actions are handled. A registered handler
    // fully replaces the SDK's default behavior for that action.
    customKV: (payload) => {/* run an app-owned key-value command */},
    deepLink: (url) => {/* navigate in-app */},
    openURL: (url) => {/* present a web URL */},
  },
  linking: {
    inAppBrowser: defaultInAppBrowser, // Required for open_url with presentation: 'in_app'
  },
});

For full details on action types, deep link URL format, action handlers, and the in-app browser adapter — see Campaign Actions. These apply to all CEP integrations, not just CleverTap.

How Digia Maps to CleverTap Campaigns​

If you haven't read How It Works in the overview, start there. The section below covers only what is CleverTap-specific.

In short: CleverTap decides who sees a campaign and when. Digia decides what is rendered. The two are linked by a digia_campaign_key you set in the CleverTap dashboard — the Digia plugin reads that key, resolves it against its local cache, and renders the right experience natively.

The table below shows how each Digia experience type maps to a CleverTap campaign type and which SDK component handles it on the app side:

Experience TypeDigia ComponentCleverTap Campaign TypeDescription
NudgeDigiaHostIn-App (Custom Code Template)Receives the DigiaTemplate payload and renders overlay experiences (bottom sheets, dialogs) above app content.
GuideDigiaAnchor + DigiaHostIn-App (Custom Code Template)Step-by-step tooltip/spotlight flows anchored to specific UI elements. Each step targets a registered anchorKey.
SurveyDigiaHostIn-App (Custom Code Template)Multi-step survey flows rendered as overlays.
InlineDigiaSlotNative DisplayReceives placement key/value pairs and renders inline content (banners, cards) within the app layout.

Here is the end-to-end flow for an In-App campaign (Nudge, Guide, or Survey):

The Campaign Contract​

Whatever the experience type, a Digia-powered CleverTap campaign always carries the same two things:

  • digia_campaign_key (required) — the key of the Digia campaign to render. This alone determines the experience type (nudge, guide, survey, or inline) and its design; nothing about the UI lives in the CleverTap payload.
  • variables (optional) — a JSON object of runtime values interpolated into the campaign at render time (for example a coupon code or the user's name).

CleverTap is the one CEP that delivers this contract through two different campaign types, depending on the experience:

Delivery channelUsed forWhere you set the contractPrerequisite
In-App (Custom Code Template)Nudge, Guide, SurveyAs fields on the DigiaTemplate templateDigiaTemplate must be synced once — see Sync DigiaTemplate to Dashboard
Native DisplayInlineAs a custom key-value pairNone

The per-experience sections below show exactly where to enter digia_campaign_key and variables for each case.

Sync DigiaTemplate to Dashboard​

Required before creating any In-App campaign. DigiaTemplate must be synced to your CleverTap project before you can create Nudge or Survey campaigns. This is a one-time step per CleverTap project, performed once from a test device.

CleverTap Custom Code In-App Templates are developer-defined presentation units registered with the CleverTap SDK that replace the built-in In-App formats (banners, interstitials, etc.) with fully custom rendering logic. Instead of CleverTap rendering the UI itself, the SDK invokes your registered template handler with the campaign payload — your code decides what to render.

The Digia CleverTap plugin ships a custom code template named DigiaTemplate that acts as this handler. When CleverTap triggers an In-App campaign built on DigiaTemplate, the plugin reads the digia_campaign_key from the payload, looks up the matching Digia campaign, and delegates rendering to Digia's runtime.

Step 1 — Identify the user on the debug device​

Call the CleverTap user login method in your debug build to associate the device with a known user.

import CleverTap from 'clevertap-react-native';

CleverTap.onUserLogin({
  Identity: 'user-123',
  Email: '[email protected]',
  Name: 'Jane Doe',
});

Step 2 — Mark that user as a test profile​

In the CleverTap dashboard, mark only the user from Step 1 as a test profile. See Mark a User Profile as a Test Profile in the CleverTap docs.

Step 3 — Open the app on the test device​

No code changes needed. The Digia plugin registers DigiaTemplate with CleverTap automatically at startup. Simply launch the app on the device where the user from Step 1 is already identified — CleverTap will sync the template definition to your project in the background.

Step 4 — Confirm the template is synced​

Open In-App → Templates in the CleverTap dashboard and confirm DigiaTemplate appears there before creating any In-App campaign.

DigiaTemplate in the CleverTap dashboard
DigiaTemplate in the CleverTap dashboard
Inside DigiaTemplate
Inside DigiaTemplate

Setting Up Nudges​

Add the Nudge Container​

Wrap your app root so overlay campaigns can render above app content.

import React from 'react';
import { View } from 'react-native';
import { DigiaHost } from '@digia-engage/core';
import { Stack } from 'expo-router';

export default function RootLayout() {
  return (
    <View style={{ flex: 1 }}>
      {/* Mounts JS guide overlays + native nudge/survey overlay */}
      <DigiaHost />
      <Stack />
    </View>
  );
}

Trigger a Nudge from CleverTap​

Create an In-App campaign in CleverTap using DigiaTemplate. In the campaign template, fill in the following fields:

FieldRequiredExample valueDescription
digia_campaign_keyYespromo_offer_sheetThe campaign key copied from the Digia Engage Dashboard. Must match exactly (case-sensitive).
variablesNo{"coupon":"SAVE20"}Runtime variables to interpolate into the campaign. Enter as a raw JSON string — see note below.

variables format: Enter the value as a plain JSON string directly in the CleverTap field. Do not wrap it in outer quotes or escape the inner quotes. The plugin JSON-decodes the string automatically. An invalid JSON value is silently ignored and the campaign renders without variable substitution.

Static variables — hardcoded values set at campaign creation time:

{
  "coupon": "SAVE20",
  "offer_title": "Limited Offer"
}

CleverTap personalization variables — CleverTap resolves {{Profile.*}} placeholders at send time using the recipient's user profile, before the value reaches the Digia plugin:

{
  "user_name": "{{Profile.Name}}",
  "account_type": "{{Profile.accounttype | default:\"standard\"}}"
}

See CleverTap Personalization for the full list of supported {{Profile.*}} and {{Campaign.*}} variables.

Setting Up Inline Widgets​

DigiaSlot is a composable/widget that renders Digia-powered content inline within your screen layout. Each slot is identified by a placementKey — a string that must match the slot key configured on the inline campaign in the Digia dashboard. When a Native Display campaign whose digia_campaign_key maps to an inline Digia campaign is active, the SDK resolves the campaign and renders it inside the matching slot. If no campaign is active for a slot, it collapses to zero height.

Add an Inline Slot​

Place DigiaSlot where you want Native Display content rendered inline.

import React from 'react';
import { ScrollView } from 'react-native';
import { DigiaSlotView } from '@digia-engage/core';

export function HomeScreen() {
  return (
    <ScrollView>
      {/* Auto-sizes to match native content height. Pass style={{ height: N }} to pin a fixed height. */}
      <DigiaSlotView placementKey="home_hero_banner" />

      <ProductCarousel />

      <DigiaSlotView placementKey="product_offers" />

      <RecommendationList />
    </ScrollView>
  );
}

Serve Inline Content from CleverTap​

Inline campaigns are delivered the same way as nudges — through a Native Display campaign carrying a digia_campaign_key. Build the inline campaign in the Digia dashboard (it defines which slot / placementKey it renders into), then set digia_campaign_key to the Digia campaign key from that campaign:

{
  "digia_campaign_key": "home_hero_banner_campaign"
}
FieldRequiredDescription
digia_campaign_keyYesThe Digia campaign key of an inline campaign copied from your Digia dashboard. The campaign defines which slot key it renders into.

The app-side DigiaSlot / DigiaSlotView placementKey must match the slot key configured on that campaign in the Digia dashboard.

info

Inline content stays loaded once a campaign renders it — it doesn't clear when the user's context changes. To clear it (for example on logout), see Managing Inline Content.

Setting Up Guide Anchors​

DigiaAnchor registers a UI element as a named anchor for tooltip and spotlight Guide campaigns. When a Guide campaign runs, the SDK looks up the anchorKey to position the tooltip bubble or spotlight cutout relative to that element.

Wrap any element you want to anchor and give it a unique anchorKey. The key must match exactly what is configured for that step in the Digia dashboard Guide campaign.

import { DigiaAnchorView } from '@digia-engage/core';

// Anywhere in your screen component:
<DigiaAnchorView anchorKey="buy_now_button">
  <BuyNowButton />
</DigiaAnchorView>

Note: If the anchor is not mounted when a Guide campaign fires, the SDK logs an anchor_not_on_screen health event and skips that step. Ensure the anchor is on screen before navigating to the Guide step.

To connect a Native Display campaign to your Digia Guide, you must tell CleverTap which Digia campaign to render. In the Digia dashboard, copy the Digia campaign key assigned to your Guide campaign. Then, in the CleverTap Native Display campaign, add a Custom key-value pair with the key set to digia_campaign_key and the value set to the copied key.

Note: The digia_campaign_key value must exactly match the Digia campaign key from the dashboard. If they differ, the plugin cannot resolve the campaign and nothing renders.

Setting Up Surveys​

Surveys are multi-step questionnaire flows you design in the Digia dashboard and render as overlays in the nudge host — no extra app-side widget is required beyond the nudge container. A survey is just another campaign type: create it in Digia, then trigger it from CleverTap using DigiaTemplate, exactly like a nudge.

  1. Build the survey campaign in the Digia Engage Dashboard and copy its Digia campaign key.
  2. Ensure your app mounts the nudge container — DigiaHost at the app root (all platforms).
  3. Create a CleverTap In-App campaign using DigiaTemplate and set digia_campaign_key to the survey's Digia campaign key.
FieldRequiredExample valueDescription
digia_campaign_keyYesnps_q3_surveyThe Digia campaign key of the survey campaign copied from your Digia dashboard.

The survey renders over your app content and reports completion back through the plugin's analytics events.

Test Your Integration​

Follow these steps to verify end-to-end functionality before releasing:

  1. Verify initialization order — Digia.initialize completes, then Digia.register(DigiaCleverTapPlugin()), before runApp / first activity.
  2. Verify host placement — DigiaHost must be in MaterialApp.builder (Flutter), the root Composable (Android Compose), or the root SwiftUI wrapper (iOS). For React Native, mount <DigiaHost /> once at the app root.
  3. Sync DigiaTemplate — run in debug mode as a CleverTap test user (see Sync DigiaTemplate to Dashboard).
  4. Create a test campaign — create an In-App campaign using DigiaTemplate and trigger it immediately for your test device.
  5. Verify inline slots — place DigiaSlot / DigiaSlotView on a visible screen, create a Native Display campaign with matching placement keys, and confirm content renders.
  6. Verify screen tracking — navigate between screens and confirm that screen-triggered campaigns fire on the correct screen (use DigiaNavigatorObserver on Flutter, Digia.setCurrentScreen(...) or digiaScreen("...") in Android View/XML apps, route/screen change hooks calling Digia.setCurrentScreen(...) on Swift, and navigation listeners calling Digia.setCurrentScreen(...) on React Native). See Reporting the Current Screen for per-stack and per-router wiring, and Screen Targeting to scope campaigns to specific screens.

Troubleshooting​

Campaign not rendering​

  • Confirm initialization order — Digia.initialize(...) then Digia.register(DigiaCleverTapPlugin()).
  • Android only: Confirm CleverTapAPI.getDefaultInstance(this) is called before Digia.register(...).
  • iOS (Swift): Confirm CleverTap.autoIntegrate() runs at app start and Info.plist includes CleverTapAccountID / CleverTapToken.
  • React Native: Confirm Digia.initialize(...) and Digia.register(new DigiaCleverTapPlugin(...)) are called once during app startup.
  • Ensure DigiaHost is mounted at the app root.
  • React Native: Ensure <DigiaHost /> is mounted once at app root, and app.json contains CleverTap plugin credentials.
  • Verify campaign eligibility and trigger conditions in the CleverTap dashboard.

Inline content not showing​

  • Confirm Native Display payload includes placement key/value pairs.
  • Ensure placement key in payload matches DigiaSlot('placement_key') or DigiaSlotView app:placementKey.
  • Verify the slot exists on the currently visible screen.
  • React Native: DigiaSlotView auto-sizes to match native content height. If it still appears collapsed, confirm the Native Display campaign is active and the placementKey matches. To pin a fixed height, pass style={{ height: 180 }}.

Screen-triggered campaign not firing​

  • Add DigiaNavigatorObserver() to navigatorObservers (Flutter).
  • Call Digia.setCurrentScreen(...) on navigation changes (Android Compose: navController.addOnDestinationChangedListener).
  • Android XML / Views: Call digiaScreen("screen_name") from Activity.onResume() or Fragment.onResume().
  • For unnamed routes, call Digia.setCurrentScreen('screen_name') manually.
  • iOS (Swift): On tab/route changes, call Digia.setCurrentScreen("screen_name") from your navigation layer.
  • React Native: Wire navigation change events (React Navigation / Expo Router) to Digia.setCurrentScreen(routeName).

CleverTap default instance is null (Android)​

  • Ensure ActivityLifecycleCallback.register(this) and CleverTapAPI.getDefaultInstance(this) are called before Digia.register(DigiaCleverTapPlugin(applicationContext)).
  • Verify CleverTap credentials are correctly set in AndroidManifest.xml per CleverTap Android Quick Start.

Official CleverTap References​