Campaign Actions

Understand Digia Engage campaign actions: what each action does, how action flows run, and how to own Deep link, Open URL, and Custom KV in your app.

An action is what happens when a user taps a button, card, or other interactive element in a Digia Engage campaign. A single element can run one action or an ordered list of them.

Actions belong to the Digia Engage core SDK. Whichever CEP delivers the campaign — CleverTap, MoEngage, WebEngage, or a custom plugin — only decides who sees the experience and when. The core SDK decides what the action does inside your app.

Actions behave the same way on every stack — React Native, Android, iOS, and Flutter. Code examples are shown per language for convenience, but the vocabulary, the flow semantics, and the handler contract are identical everywhere.

Campaign authors pick actions in the Digia Engage Dashboard. You never write the wire JSON by hand. The canonical action names on this page are what you'll see when inspecting a campaign payload or an SDK log — they're a reading aid, not something you author.

---

1. How an action flow runs

An interactive element carries an ordered list of actions. The SDK runs them one at a time, in order, and moves to the next when the current one completes.

• Order is preserved. Action 1 runs, then action 2, and so on.

• A failure is logged, and the flow continues. If the SDK observes an action fail, it logs it and still runs the remaining actions.

• Variables resolve at tap time. Campaign variables such as {{ product_id }} are interpolated when the user taps, in URL and deep-link targets, Share and Copy text, and Custom KV keys and values.

• Put Hide last. When something must happen before the surface closes, place Hide at the end of the flow.

A missing variable resolves to its configured fallback or an empty string. Treat every interpolated value as untrusted input: validate identifiers and URLs in your handlers before acting on them.

The handler timing contract

A few actions can be owned by your app (see section 7). Your handler runs as part of the tap's flow, so keep the ordering-sensitive work — navigating, validating, handing off to a service — in the handler itself. If you kick off longer-running background work, run it on your own async primitive (a coroutine, Task, Future, or promise) and own its result and errors. Don't rely on that background work finishing before the next authored action runs; instead, sequence with Hide last.

---

2. Action catalog

Every action a campaign can run, and whether your app can own it:

Dashboard action	Canonical type	What it does	App handler
Open URL / Deep link	Action.openUrl	Routes to a screen or opens a web target	Optional
Hide / Dismiss	Action.dismiss	Closes the current campaign surface	—
Next	Action.next	Advances a multi-step experience	—
Previous	Action.previous	Returns to the previous step	—
Share	Action.share	Opens the system share sheet	—
Copy to clipboard	Action.copyToClipBoard	Copies text to the clipboard	—
Request app review	Action.requestReview	Asks the store for its in-app review prompt	—
Custom KV	Action.customKV	Sends a key–value payload to your app	Required

The dashboard may emit a surface-specific canonical name for Hide — such as Action.dismissDialog or Action.hideBottomSheet. These all express the same "dismiss the current surface" intent.

---

3. Open URL and Deep link

Open URL and Deep link are two modes of the same Action.openUrl. The SDK decides which mode to use from the action's launchMode, not from whether the target starts with https:// or a custom scheme.

launchMode	Mode	Behavior
platformDefault or omitted	Deep link	Let the system or app route the target
externalApplication	Open URL	Open in an external app, normally the browser
inAppBrowser	Open URL	Open in an in-app browser

A custom-scheme deep link looks like:

yourapp://products/123?source=engage

Deep link is for in-app navigation. Provide a deepLink handler when your app should own routing; it receives the target string and fully owns the action. Without a handler, the SDK asks the system to open the target.

Open URL is for web destinations. Provide an openURL handler when your app should choose how web links are presented; it receives only the URL, so it also chooses the presentation. Without a handler, the SDK opens the URL with default platform behavior.

See section 7 for how to register these handlers.

Host project setup

Deep links resolve through the native platform, so register your scheme in both host projects regardless of which framework your app is built with:

• Android — add a matching intent filter to AndroidManifest.xml (custom scheme or App Link).

• iOS — add a URL type in Info.plist, or configure an associated domain for a universal link.

Don't rely on a link action to close the campaign. Add Hide as the last action when the surface should close after navigation.

---

4. Hide and Dismiss

Hide closes the current campaign surface — a bottom sheet, dialog, or other dismissible experience. Use it as the final step when the flow must do something else first, such as navigate, share, or run a Custom KV command.

---

5. Next and Previous

Next advances a multi-step experience such as a Guide; Previous returns to the preceding step. The experience defines its own boundary behavior — for example, Next on the final step can complete or dismiss the experience.

These actions only make sense on a surface that actually has multiple steps.

---

6. Share and Copy to clipboard

Action.share opens the system share sheet with the configured message, after variable interpolation. Action.copyToClipBoard copies the configured message to the clipboard, also after interpolation.

The canonical spelling is Action.copyToClipBoard. Older payloads using the copy alias remain readable, but don't author copy_to_clipboard — it isn't a canonical action name.

---

7. App-owned actions

Three actions can be handled by your app instead of by default SDK behavior:

• Deep link — take over in-app navigation.

• Open URL — choose how web links are presented.

• Custom KV — run any app behavior that no built-in action expresses. This action always requires a handler.

A registered handler fully owns its action: the SDK does not run its own built-in behavior afterward. Handlers receive only the link target or the Custom KV payload — no campaign context, and no "suppress default" return value. If the SDK observes a handler fail, it logs the failure and continues with the next authored action.

Register handlers

Register handlers once during initialization.

React Native

await Digia.initialize({
  apiKey: 'YOUR_ACCESS_KEY',
  actionHandlers: {
    customKV: (payload) => handleCampaignCommand(payload),
    deepLink: (url) => appRouter.open(url),
    openURL: (url) => void trustedBrowser.open(url),
  },
});

Android

Digia.initialize(
    context = applicationContext,
    config = DigiaConfig(
        apiKey = "YOUR_ACCESS_KEY",
        actionHandlers = DigiaActionHandlers(
            customKV = { payload -> handleCampaignCommand(payload) },
            deepLink = { url -> appRouter.open(url) },
            openURL = { url -> trustedBrowser.open(url) },
        ),
    ),
)

iOS (Swift)

try await Digia.initialize(
    DigiaConfig(
        apiKey: "YOUR_ACCESS_KEY",
        actionHandlers: DigiaActionHandlers(
            customKV: { payload in handleCampaignCommand(payload) },
            deepLink: { url in appRouter.open(url) },
            openURL: { url in trustedBrowser.open(url) }
        )
    )
)

Flutter

await Digia.initialize(
  DigiaConfig(
    apiKey: 'YOUR_ACCESS_KEY',
    actionHandlers: DigiaActionHandlers(
      customKV: (payload) async => handleCampaignCommand(payload),
      deepLink: (url) async => appRouter.open(url),
      openURL: (url) async => trustedBrowser.open(url),
    ),
  ),
);

You can replace or clear any handler at runtime. Passing a null handler restores the SDK's default link behavior. Register a Custom KV handler before publishing a campaign that uses Custom KV, or those taps have nothing to run.

React Native

Digia.setCustomKVHandler(customKVHandlerOrNull);
Digia.setDeepLinkHandler(deepLinkHandlerOrNull);
Digia.setOpenURLHandler(openURLHandlerOrNull);

Android

Digia.setCustomKVHandler(customKVHandlerOrNull)
Digia.setDeepLinkHandler(deepLinkHandlerOrNull)
Digia.setOpenURLHandler(openURLHandlerOrNull)

iOS (Swift)

Digia.setCustomKVHandler(customKVHandlerOrNil)
Digia.setDeepLinkHandler(deepLinkHandlerOrNil)
Digia.setOpenURLHandler(openURLHandlerOrNil)

Flutter

Digia.setCustomKVHandler(customKVHandlerOrNull);
Digia.setDeepLinkHandler(deepLinkHandlerOrNull);
Digia.setOpenURLHandler(openURLHandlerOrNull);

The same handlers apply across every campaign surface. Register them at app scope so a tap always has a live handler; clear a temporary handler when the screen that owned it goes away.

---

8. Custom KV

Action.customKV sends a string-to-string payload to your app. It's the supported extension point for anything the built-in actions don't express. Non-string values in the payload are discarded during parsing, so design for a flat string map.

Reach for Custom KV to:

• open an app feature that has no stable deep link;

• apply a coupon or select a product in app state;

• start an app-owned workflow such as sign-in, checkout, or support;

• call an app service after validating the payload;

• record a distinct business outcome that campaign lifecycle analytics don't already capture.

For ordinary navigation, prefer Deep link; for web destinations, prefer Open URL. Reserve Custom KV for behavior those two can't express.

Use a versioned command schema

Configure a small, stable payload in the dashboard:

{
  "action": "open_product",
  "version": "1",
  "product_id": "{{ product_id }}",
  "source": "engage_campaign"
}

action names an allowlisted command; version lets your app evolve the contract without guessing which payload shape it received. Keep both stable.

Handle Custom KV in the app

Dispatch on action through an explicit allowlist, validate every field, and ignore unknown commands and versions.

React Native

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

function handleCampaignCommand(payload: Record<string, string>): void {
  if (payload.version !== '1') return;

  switch (payload.action) {
    case 'open_product': {
      const productId = payload.product_id?.trim();
      if (!productId) return;
      navigationRef.navigate('ProductDetails', { productId });
      return;
    }
    case 'apply_coupon': {
      const coupon = payload.coupon?.trim();
      if (!coupon) return;
      void cartService.applyCoupon(coupon).catch(reportActionError);
      return;
    }
    default:
      console.warn('Unknown Engage action', payload.action);
  }
}

await Digia.initialize({
  apiKey: 'YOUR_ACCESS_KEY',
  actionHandlers: {
    customKV: handleCampaignCommand,
  },
});

Android

private fun handleCampaignCommand(payload: Map<String, String>) {
    if (payload["version"] != "1") return

    when (payload["action"]) {
        "open_product" -> {
            val productId = payload["product_id"]?.trim().orEmpty()
            if (productId.isEmpty()) return
            appRouter.openProduct(productId)
        }
        "apply_coupon" -> {
            val coupon = payload["coupon"]?.trim().orEmpty()
            if (coupon.isEmpty()) return
            appScope.launch {
                runCatching { cartService.applyCoupon(coupon) }
                    .onFailure(::reportActionError)
            }
        }
        else -> Log.w("EngageAction", "Unknown action: ${payload["action"]}")
    }
}

Digia.initialize(
    context = applicationContext,
    config = DigiaConfig(
        apiKey = "YOUR_ACCESS_KEY",
        actionHandlers = DigiaActionHandlers(
            customKV = ::handleCampaignCommand,
        ),
    ),
)

iOS (Swift)

@MainActor
private func handleCampaignCommand(_ payload: [String: String]) {
    guard payload["version"] == "1" else { return }

    switch payload["action"] {
    case "open_product":
        guard let productID = payload["product_id"]?.trimmingCharacters(in: .whitespaces),
              !productID.isEmpty else { return }
        appRouter.openProduct(productID)

    case "apply_coupon":
        guard let coupon = payload["coupon"]?.trimmingCharacters(in: .whitespaces),
              !coupon.isEmpty else { return }
        Task {
            do {
                try await cartService.applyCoupon(coupon)
            } catch {
                reportActionError(error)
            }
        }

    default:
        print("Unknown Engage action: \(payload["action"] ?? "<missing>")")
    }
}

try await Digia.initialize(
    DigiaConfig(
        apiKey: "YOUR_ACCESS_KEY",
        actionHandlers: DigiaActionHandlers(
            customKV: { payload in handleCampaignCommand(payload) }
        )
    )
)

Flutter

import 'package:flutter/foundation.dart';
import 'package:digia_engage/digia_engage.dart';

Future<void> handleCampaignCommand(Map<String, String> payload) async {
  if (payload['version'] != '1') return;

  switch (payload['action']) {
    case 'open_product':
      final productId = payload['product_id']?.trim();
      if (productId == null || productId.isEmpty) return;
      await navigatorKey.currentState?.pushNamed(
        '/product',
        arguments: productId,
      );
      return;
    case 'apply_coupon':
      final coupon = payload['coupon']?.trim();
      if (coupon == null || coupon.isEmpty) return;
      await cartService.applyCoupon(coupon);
      return;
    default:
      debugPrint('Unknown Engage action: ${payload['action']}');
  }
}

await Digia.initialize(
  DigiaConfig(
    apiKey: 'YOUR_ACCESS_KEY',
    actionHandlers: DigiaActionHandlers(
      customKV: handleCampaignCommand,
    ),
  ),
);

Custom KV best practices

• Allowlist commands. Dispatch through an explicit table or switch. Never use payload data to select arbitrary code, classes, methods, routes, or URLs.

• Version the contract. Keep action and version stable, and reject unknown versions safely.

• Validate every field. Treat campaign data and interpolated variables as external input.

• Keep payloads small and string-only. Pass identifiers and intent, not whole domain objects.

• Never include secrets or sensitive personal data. Payloads can surface in dashboards, logs, and diagnostic reports.

• Make destructive commands safe to repeat. Debounce repeated taps and use idempotency for charges, submissions, or mutations.

• Own recovery. A registered handler suppresses SDK fallback, so log failures and present any user-facing recovery yourself.

• Put Hide last. Validate or start your work before the surface dismisses.

• Avoid duplicate analytics. Digia Engage already records campaign lifecycle events. Emit an app event only for a distinct business outcome.

---

9. Request app review

Action.requestReview asks the platform to present its in-app review prompt.

The platform controls eligibility and quota, and returns no rating or completion result. The SDK cannot guarantee that a prompt appeared. Treat it as best-effort — never make business-critical behavior depend on the prompt being shown.

---

10. Test before publishing

Test an action-heavy campaign on every target surface your app uses.

• Verify each authored action produces the expected result.

• Test deep links from a cold start and while the app is already active.

• Confirm missing or malformed variables fail safely.

• Verify Open URL and Deep link behavior both with and without your handlers.

• Confirm Custom KV ignores unknown commands and versions.

• Ensure repeated taps can't repeat a destructive operation.

• Verify Hide runs at the intended point in the flow.

• Treat Request app review as best-effort, not a guaranteed prompt.

Related pages

• Core Concepts

• Developer Integrations

• User Guides

• CleverTap Integration

• MoEngage Integration

• WebEngage Integration