# 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 Digia Studio, instantly rendering a 100% native experience on the device—no WebViews required.
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.
## 1. Prerequisites
Before integrating, ensure you have:
* **Digia Access Key**: Log in to [Digia Studio](https://app.digia.tech), 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](https://developer.clevertap.com/docs/flutter-quick-start-guide), [Android](https://developer.clevertap.com/docs/android-quick-start-guide), [iOS](https://developer.clevertap.com/docs/ios-quickstart-guide), or [React Native](https://developer.clevertap.com/docs/react-native-quick-start-guide) Quick Start).
### Minimum Supported Versions
| Platform | Environment | Minimum Dependencies |
| ---------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flutter** |
|
***
## 2. Install
> **Note:** We assume the core CleverTap SDK is already installed and initialized as part of your standard app setup (see [Prerequisites](#1-prerequisites)). The snippets below only cover adding the Digia plugin packages.
{% tabs %}
{% tab title="Flutter" %}
Add the Digia packages using the `flutter pub add` command:
```bash
flutter pub add digia_engage digia_engage_clevertap
```
{% endtab %}
{% tab title="Android" %}
Add dependencies in app `build.gradle.kts`:
```kotlin
dependencies {
implementation("tech.digia:engage:1.0.0-beta.03")
implementation("tech.digia:engage-clevertap:1.0.0-beta.02")
}
```
Sync the project (Gradle sync).
{% endtab %}
{% tab title="iOS (Swift)" %}
Add packages using **Xcode → File → Add Package Dependencies** (or in `Package.swift`):
```swift
dependencies: [
.package(url: "https://github.com/Digia-Technology-Private-Limited/digia_engage_iOS.git", exact: "1.0.0-beta.1"),
.package(url: "https://github.com/Digia-Technology-Private-Limited/digia_engage_clevertap_iOS.git", exact: "1.0.0-beta.1"),
],
```
Then add these products to your app target dependencies:
* `DigiaEngage`
* `DigiaEngageCleverTap`
{% endtab %}
{% tab title="React Native" %}
Install the Digia packages:
```bash
npm install @digia-engage/core@1.0.0-beta.4 @digia-engage/clevertap@1.0.0-beta.2
```
{% endtab %}
{% endtabs %}
***
## 3. Initialize Digia with CleverTap
Initialize Digia **after** CleverTap SDK and **before** plugin registration.
{% tabs %}
{% tab title="Flutter" %}
```dart
import 'package:digia_engage/digia_engage.dart';
import 'package:digia_engage_clevertap/digia_engage_clevertap.dart';
import 'package:flutter/material.dart';
Future main() async {
WidgetsFlutterBinding.ensureInitialized();
// 1. CleverTap SDK — initialized as a prerequisite.
// 2. Initialize Digia before registering any CEP plugin.
await Digia.initialize(
DigiaConfig(apiKey: 'YOUR_ACCESS_KEY'),
);
// 3. Register the Digia CleverTap plugin.
Digia.register(DigiaCleverTapPlugin());
runApp(const MyApp());
}
```
{% endtab %}
{% tab title="Android" %}
```kotlin
import android.app.Application
import com.clevertap.android.sdk.ActivityLifecycleCallback
import com.digia.engage.Digia
import com.digia.engage.DigiaConfig
import com.digia.engage.clevertap.DigiaCleverTapPlugin
class MyApplication : Application() {
override fun onCreate() {
// 1. In custom Application class, CleverTap recommends registering activity lifecycle callback before super.onCreate().
// Read: https://developer.clevertap.com/docs/flutter-quick-start-guide#set-up-androids-application-class
ActivityLifecycleCallback.register(this)
super.onCreate()
// 2. Initialize Digia before registering any CEP plugin.
Digia.initialize(
context = applicationContext,
config = DigiaConfig(apiKey = "YOUR_ACCESS_KEY"),
)
// 3. Register the Digia CleverTap plugin. Context is required to resolve the CleverTap default instance.
Digia.register(DigiaCleverTapPlugin(applicationContext))
}
}
```
{% endtab %}
{% tab title="iOS (Swift)" %}
```swift
import SwiftUI
import DigiaEngage
import DigiaEngageCleverTap
@main
struct MyApp: App {
init() {
// 1. CleverTap SDK — initialized as a prerequisite.
CleverTap.autoIntegrate()
// 2. Initialize Digia before registering any CEP plugin.
Task {
do {
try await Digia.initialize(DigiaConfig(apiKey: "YOUR_ACCESS_KEY"))
// 3. Register the Digia CleverTap plugin.
Digia.register(DigiaCleverTapPlugin())
} catch { }
}
}
var body: some Scene {
WindowGroup {
RootView()
}
}
}
```
{% endtab %}
{% tab title="React Native" %}
```tsx
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),
})
);
})().catch(console.error);
}, []);
return ;
}
```
{% endtab %}
{% endtabs %}
***
## 4. How Digia Maps to CleverTap Campaigns
| Experience Type | Digia Component | CleverTap Campaign Type | Description |
| --------------- | --------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Nudge** | `DigiaHost` | In-App (Custom Code Template) | Receives the `DigiaTemplate` payload and renders overlay experiences (bottom sheets, dialogs) above app content. |
| **Inline** | `DigiaSlot` | Native Display | Receives placement key/value pairs and renders inline content (banners, cards) within the app layout. |
{% @mermaid/diagram content="flowchart TD
Trigger\[CleverTap Campaign Trigger]
SDK\[CleverTap SDK]
Plugin\[Digia CleverTap Plugin]
Runtime\[digia\_engage runtime]
UI\[Campaign UI native widgets from Digia Studio]
```
Trigger --> SDK
SDK -- "In-App callback / Native Display callback" --> Plugin
Plugin -- "maps payload -> InAppPayload" --> Runtime
Runtime -- "SHOW_BOTTOM_SHEET / SHOW_DIALOG -> DigiaHost renders overlay" --> UI
Runtime -- "DigiaSlot -> DigiaSlot renders inline" --> UI" %}
```
***
## 5. Setting Up Nudges
### Custom Code Templates: What They Are and Why They're Needed
[CleverTap Custom Code In-App Templates](https://developer.clevertap.com/docs/flutter-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 receives the payload, maps it to a `SHOW_BOTTOM_SHEET` or `SHOW_DIALOG` command, and delegates rendering to Digia's runtime. **Without syncing this template to your CleverTap dashboard, it will not appear as an option when creating In-App campaigns.**
### Custom Code Templates: Sync to Dashboard
This is a one-time, per-project step performed from a test device. Once synced, `DigiaTemplate` is available for all campaign creation in that CleverTap project.
1. **Identify user** with CleverTap SDK: `CleverTapPlugin.onUserLogin(profile)` (e.g. `{'Identity': userId, 'Email': email}`). See [medihub\_flutter](https://github.com/Digia-Technology-Private-Limited/medihub_flutter) `lib/core/services/analytics_service.dart` for an example.
2. **Mark as test user** in the CleverTap dashboard.
3. **Run app in debug mode** with Digia Engage + CleverTap plugin. `DigiaCleverTapPlugin.syncCustomTemplates()` is called automatically in debug builds; `DigiaTemplate` appears in the CleverTap dashboard under **In-App → Templates**.
4. **Create In-App campaigns** using `DigiaTemplate`.
DigiaTemplate in the CleverTap dashboard
See [CleverTap Flutter Custom Code In-App Templates](https://developer.clevertap.com/docs/flutter-custom-code-in-app-templates) and [CleverTap Android Custom Code In-App Templates](https://developer.clevertap.com/docs/android-custom-code-in-app-templates).
{% embed url="" %}
### Add the Nudge Container
Wrap your app root so overlay campaigns can render above app content. See [Digia Engage - Flutter SDK](https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/engagement/digia-engage-flutter.md) or [Digia Engage - Android SDK](https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/engagement/digia-engage-android.md) for full setup.
{% tabs %}
{% tab title="Flutter" %}
```dart
import 'package:digia_engage/digia_engage.dart';
import 'package:flutter/material.dart';
MaterialApp(
navigatorKey: DigiaHost.navigatorKey,
navigatorObservers: [DigiaNavigatorObserver()],
builder: (context, child) => DigiaHost(
child: child!,
),
home: const HomeScreen(),
)
```
{% endtab %}
{% tab title="Android (Jetpack Compose)" %}
```kotlin
import com.digia.engage.DigiaHost
DigiaHost {
AppNavHost()
}
```
{% endtab %}
{% tab title="Android (XML Layout)" %}
For XML-based Android layouts, use `DigiaHostView` as a full-screen overlay in your root layout. This is the View-system wrapper around `DigiaHost`, so you do not need Compose code in your `Activity` or `Fragment`.
```xml
```
Or programmatically in your Activity:
```kotlin
import com.digia.engage.DigiaHostView
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
val rootLayout = findViewById(R.id.root_layout)
val digiaHost = DigiaHostView(this)
rootLayout.addView(
digiaHost,
FrameLayout.LayoutParams(
FrameLayout.LayoutParams.MATCH_PARENT,
FrameLayout.LayoutParams.MATCH_PARENT,
)
)
}
```
For screen-triggered campaigns in View/XML flows, report the active screen from `onResume()`:
```kotlin
import com.digia.engage.digiaScreen
class HomeActivity : AppCompatActivity() {
override fun onResume() {
super.onResume()
digiaScreen("home")
}
}
```
{% endtab %}
{% tab title="iOS (Swift)" %}
```swift
import SwiftUI
import DigiaEngage
struct RootContainerView: View {
var body: some View {
DigiaHost {
AppRootView()
}
}
}
```
{% endtab %}
{% tab title="React Native" %}
```tsx
import React from 'react';
import { StyleSheet, View } from 'react-native';
import { DigiaHostView } from '@digia-engage/core';
import { Stack } from 'expo-router';
export default function RootLayout() {
return (
{/* Host overlay for bottom sheets/dialogs above the app UI */}
);
}
const styles = StyleSheet.create({
root: { flex: 1 },
});
```
{% endtab %}
{% endtabs %}
### Trigger a Nudge from CleverTap
Create an In-App campaign in CleverTap using `DigiaTemplate`. In the campaign template, fill in the following fields:
| Field | Required | Example value | Description |
| ---------- | -------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `command` | Yes | `SHOW_BOTTOM_SHEET` | `SHOW_BOTTOM_SHEET` or `SHOW_DIALOG`. |
| `viewId` | Yes | `promo_offer_sheet` | Digia page slug. See [Finding Slugs](https://docs.digia.tech/studio-workspace/builder-tool/finding-slugs). |
| `screenId` | No | `home` | Screen on which to show the nudge. Leave blank to show on all screens. |
| `args` | No | `{"coupon":"SAVE20"}` | Enter as a raw JSON string in the text field. Available in Digia page logic at runtime. |
> **`args` format:** Enter the value as plain JSON text directly in the field — e.g., `{"coupon":"SAVE20"}`. Do not wrap it in outer quotes. The plugin JSON-decodes the string automatically.
SHOW_BOTTOM_SHEET — bottom sheet nudge
SHOW_DIALOG — dialog nudge
***
## 6. 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 key configured in the CleverTap Native Display campaign. When a Native Display campaign is active, Digia resolves the component to display for each placement key and renders it inside the 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.
{% tabs %}
{% tab title="Flutter" %}
```dart
import 'package:digia_engage/digia_engage.dart';
import 'package:flutter/material.dart';
class HomeScreen extends StatelessWidget {
const HomeScreen({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Home')),
body: ListView(
children: const [
// Renders a Digia-powered banner campaign at the top of the feed.
// placementKey must match the key in the CleverTap Native Display campaign.
DigiaSlot('home_hero_banner'),
SizedBox(height: 16),
ProductCarousel(),
SizedBox(height: 16),
// Renders an inline offer card between content sections.
DigiaSlot('product_offers'),
SizedBox(height: 16),
RecommendationList(),
],
),
);
}
}
```
{% endtab %}
{% tab title="Android (Jetpack Compose)" %}
```kotlin
import com.digia.engage.DigiaSlot
// placementKey must match key in CleverTap Native Display campaign config
Column {
DigiaSlot(placementKey = "home_hero_banner")
DigiaSlot(placementKey = "product_offers")
}
```
{% endtab %}
{% tab title="Android (XML Layout)" %}
For View/XML layouts, use `DigiaSlotView`. It wraps the Compose `DigiaSlot` API and reads `app:placementKey` from XML.
```xml
```
Or set the placement programmatically after inflation:
```kotlin
import com.digia.engage.DigiaSlotView
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_home)
findViewById(R.id.homeHeroBanner).placementKey = "home_hero_banner"
findViewById(R.id.productOffers).placementKey = "product_offers"
}
```
`DigiaSlotView` requires a `DigiaHostView` (or a Compose `DigiaHost`) in the same window so the Digia rendering engine is already mounted before the slot renders.
{% endtab %}
{% tab title="iOS (Swift)" %}
```swift
import SwiftUI
import DigiaEngage
struct HomeScreen: View {
var body: some View {
ScrollView {
VStack(spacing: 16) {
DigiaSlot(placementKey: "home_hero_banner")
ProductCarousel()
DigiaSlot(placementKey: "product_offers")
RecommendationList()
}
.padding()
}
}
}
```
{% endtab %}
{% tab title="React Native" %}
```tsx
import React from 'react';
import { ScrollView } from 'react-native';
import { DigiaSlotView } from '@digia-engage/core';
export function HomeScreen() {
return (
);
}
```
{% endtab %}
{% endtabs %}
### Serve Inline Content from CleverTap
For Native Display campaigns, map placement keys to Digia component IDs in campaign custom data:
```json
{
"home_hero_banner": "home_hero_banner-v2N8",
}
```
| Field | Required | Description |
| ----------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------- |
| `` -> `` | Native Display inline | Key must match `DigiaSlot` / `DigiaSlotView` placement key; value is Digia component/page slug. |
See [Finding Slugs](https://docs.digia.tech/studio-workspace/builder-tool/finding-slugs) for slug lookup.
{% embed url="" %}
***
## 7. 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 Android View/XML apps, `DigiaHostView` should be mounted once as the last full-screen child of the root `ViewGroup`. For React Native, `DigiaHostView` is to be used.
3. **Sync `DigiaTemplate`** — run in debug mode as a CleverTap test user (see [Custom Templates: Sync to Dashboard](#custom-templates-sync-to-dashboard)).
4. **Create a test campaign** — create an In-App campaign using `DigiaTemplate` with a known `viewId` 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).
### Health Check
Use `plugin.healthCheck()` to verify plugin wiring. The report shape is platform-specific, but always includes `isHealthy` plus diagnostic metadata.
{% tabs %}
{% tab title="Flutter" %}
```dart
final plugin = DigiaCleverTapPlugin();
Digia.register(plugin);
// Later, for testing:
final report = plugin.healthCheck();
if (!report.isHealthy) {
debugPrint('Plugin issue: ${report.issue}');
debugPrint('Resolution: ${report.resolution}');
}
```
{% endtab %}
{% tab title="Android (Jetpack Compose)" %}
```kotlin
val plugin = DigiaCleverTapPlugin(applicationContext)
Digia.register(plugin)
// Later, for testing:
val report = plugin.healthCheck()
if (!report.isHealthy) {
Log.w("Digia", "Plugin issue: ${report.issue} - ${report.resolution}")
}
```
{% endtab %}
{% tab title="iOS (Swift)" %}
```swift
let plugin = DigiaCleverTapPlugin()
Digia.register(plugin)
// Later, for testing:
let report = plugin.healthCheck()
if !report.isHealthy {
print("Plugin issue: \(report.issue)")
print("Resolution: \(report.resolution)")
}
```
{% endtab %}
{% tab title="React Native" %}
```tsx
import CleverTap from 'clevertap-react-native';
import { Digia } from '@digia-engage/core';
import { DigiaCleverTapPlugin, createCleverTapClient } from '@digia-engage/clevertap';
const plugin = new DigiaCleverTapPlugin({
cleverTap: createCleverTapClient(CleverTap),
});
Digia.register(plugin);
// Later, for testing:
const report = plugin.healthCheck();
if (!report.isHealthy) {
console.warn('Plugin health check failed', report.metadata);
}
```
{% endtab %}
{% endtabs %}
***
## 8. Troubleshooting
Reference open-source example apps for integration patterns:
* [medihub\_flutter](https://github.com/Digia-Technology-Private-Limited/medihub_flutter)
* [medihub\_android](https://github.com/Digia-Technology-Private-Limited/medihub_android)
* [medihub\_swift](https://github.com/Digia-Technology-Private-Limited/medihub_swift)
* [medihub\_rn](https://github.com/Digia-Technology-Private-Limited/medihub_rn)
### 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 in `MaterialApp.builder` (Flutter), the root Composable (Android Compose), or `DigiaHostView` is mounted as the last full-screen child in your Android View/XML root layout.
* **React Native**: Ensure `DigiaHostView` is mounted once at app root on Android and `app.json` contains CleverTap plugin credentials.
* Check `viewId` exactly matches the published Digia page slug (case-sensitive). See [Finding Slugs](https://docs.digia.tech/studio-workspace/builder-tool/finding-slugs).
* 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.
* **Android XML**: Ensure a `DigiaHostView` is mounted in the same window before `DigiaSlotView` renders.
* **React Native**: Ensure `DigiaSlotView` has an explicit height/size in `style`, otherwise nothing is visible.
### 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](https://developer.clevertap.com/docs/android-quick-start-guide).
***
## Official CleverTap References
* [Flutter SDK](https://developer.clevertap.com/docs/flutter-sdk)
* [Flutter In-App](https://developer.clevertap.com/docs/flutter-in-app)
* [Flutter Custom Code In-App Templates](https://developer.clevertap.com/docs/flutter-custom-code-in-app-templates)
* [Android Quick Start](https://developer.clevertap.com/docs/android-quick-start-guide)
* [Android In-App Notifications](https://developer.clevertap.com/docs/android-in-app-notifications)
* [Android Native Display](https://developer.clevertap.com/docs/android-native-display)
* [Android Custom Code In-App Templates](https://developer.clevertap.com/docs/android-custom-code-in-app-templates)
* [iOS Quick Start](https://developer.clevertap.com/docs/ios-quickstart-guide)
* [iOS Custom Code In-App Templates](https://developer.clevertap.com/docs/ios-custom-code-in-app-templates)
* [React Native Quick Start Guide](https://developer.clevertap.com/docs/react-native-quick-start-guide)
* [React Native Custom Code In-App Templates](https://developer.clevertap.com/docs/react-native-custom-code-in-app-templates)
