# Engage Mobile SDK API and Event Reference

This page is the single reference for the preview Engage Mobile SDK APIs used by Mobile In-App Messaging and Hosted Pages. It also defines the events that the SDK creates or receives through the app and message content.

Preview
The iOS and Android Engage Mobile SDKs are in preview. Method names, signatures, payload fields, package distribution, and event schemas may change before general availability. Use the release-specific artifact instructions and API contract that accompany your SDK version.

## API Surface at a Glance

| Purpose | iOS | Android |
|  --- | --- | --- |
| Initialize Core SDK | `TreasureData.initializeWithApiKey` | `TreasureData.initializeSharedInstance` |
| Register Engage rendering | `TDEngage.install()` | Not required (bundled in `td-android-sdk`) |
| Trigger message retrieval | `trackImmediately` | `trackImmediately` |
| Provide page context | `profileContext` | `setProfileContext` / `setProfileValue` |
| Display an app-owned URL | `openUrl(_:context:)` | `openUrl(url, context)` |
| Register a Push token | `registerDeviceToken` | `registerDeviceToken` |
| Handle app-owned links and actions | `linkHandler`, `bridgeDelegate` | `setBridgeListener` (`TDEngageBridgeListener`), `setLinkHandler` |
| Suppress stale presentation | `inAppPresentationGate` (preview) | Host screen-state handling (preview) |


## Required Startup Methods

### Initialize the Core SDK

Initialize the Core SDK once during app startup, then configure the event and Personalization destinations.

#### iOS

```swift
import TreasureData
import TreasureDataEngage

TreasureData.initializeWithApiKey(
    "<WRITE_ONLY_API_KEY>",
    apiEndpoint: "https://<region>.records.in.treasuredata.com"
)

let td = TreasureData.sharedInstance()
td.defaultDatabase = "<DATABASE>"
td.defaultTable = "<EVENT_TABLE>"
td.personalizationEndpoint = "https://p13n-api.treasuredata.com"
td.personalizationToken = "<PERSONALIZATION_TOKEN>"
td.enableAutoAppendUniqId()

TDEngage.install()
```

#### Android

```java
TreasureData.initializeSharedInstance(
    application,
    "<WRITE_ONLY_API_KEY>",
    "https://<region>.records.in.treasuredata.com"
);

TreasureData td = TreasureData.sharedInstance();
td.setDefaultDatabase("<DATABASE>");
td.setDefaultTable("<EVENT_TABLE>");
td.setPersonalizationEndpoint("https://p13n-api.treasuredata.com");
td.setPersonalizationToken("<PERSONALIZATION_TOKEN>");
td.enableAutoAppendUniqId();
```

Mobile In-App rendering is part of `td-android-sdk`; Android has no rendering install step equivalent to the iOS `TDEngage.install()`.

Use the SDK artifact's release-specific installation instructions for dependencies and supported platform versions. Do not use a source repository URL as an installation dependency.

### `enableAutoAppendUniqId`

Call this once at startup when measurement must be associated with an installation. It applies to trigger events and SDK-generated measurement records.

## Message Trigger

### `trackImmediately`

Use `trackImmediately` when the customer reaches a screen or performs an event that can trigger a Mobile In-App campaign.

```swift
td.trackImmediately([
    "event": "pageview",
    "screen_name": "home"
])
```

```java
Map<String, Object> event = new HashMap<>();
event.put("event", "pageview");
event.put("screen_name", "home");
TreasureData.sharedInstance().trackImmediately(event);
```

`trackImmediately` sends the trigger event and requests an offer from Realtime Personalization. If no campaign matches, nothing is displayed. `addEvent` and `uploadEvents` send ordinary events and do not trigger Mobile In-App display.

Use the callback overload where available when the app needs to record whether the SDK displayed a message.

## Handle P13N Responses and Select a Message

Realtime Personalization can return more than one offer. The SDK selects one supported displayable Modal, Banner, or Hosted Pages experience and skips incomplete or unsupported candidates.

The service generates the response format. Treat raw response fields as internal preview details and use the SDK response and rendering APIs instead of parsing offer maps or depending on tie-breaking behavior.

### Display Constraints

The SDK displays one in-app experience at a time. If an in-app experience is already displayed when another candidate is received, the SDK skips the new candidate and does not create a campaign measurement event for the skipped display. The SDK does not apply a client-side frequency cap. Frequency, priority, targeting, and A/B decisions are handled by Realtime Personalization; the SDK selects only among candidates in the response it receives.

## Profile Context

Use profile context to provide JSON-serializable values that the SDK injects into Modal, Banner, and Hosted Pages content as `window.TDContext`.

| Platform | APIs |
|  --- | --- |
| iOS | `profileContext`, `setProfileValue`, `removeProfileValue`, `clearProfileContext` |
| Android | `setProfileContext`, `setProfileValue` |


```swift
td.profileContext = [
    "member_tier": "gold",
    "points": 1200
]
```

```java
Map<String, Object> context = new HashMap<>();
context.put("member_tier", "gold");
context.put("points", 1200);
TreasureData.sharedInstance().setProfileContext(context);
```

Profile context is not a substitute for event identity. Do not place API keys, Personalization tokens, passwords, or unnecessary personal data in it. Clear or replace it when the signed-in customer changes.

## Hosted Pages and URL APIs

### `openUrl`

Use `openUrl` when the app already has a URL, such as a URL extracted from a Push payload.

```swift
TreasureData.sharedInstance().openUrl(
    URL(string: "https://example.com/coupon")!,
    context: ["coupon_id": "abc123"]
)
```

```java
Map<String, Object> context = new HashMap<>();
context.put("coupon_id", "abc123");

TreasureData.sharedInstance().openUrl(
    "https://example.com/coupon",
    context
);
```

A direct `openUrl` display is not a campaign offer. It has no campaign identity and does not create campaign `impression`, `click`, or `dismiss` events.

### Hosted Pages Content

The SDK handles a campaign-delivered Hosted Pages experience when it receives a supported offer. Use the documented SDK APIs rather than depending on fields in the generated response.

## Links and Custom Actions

### iOS

- `linkHandler` claims app-owned URL schemes and returns a Boolean indicating whether the app handled the URL.
- `bridgeDelegate` receives `TDBridge.invoke` requests through `TDEngageBridgeDelegate`.
- `inAppPresentationGate` can suppress a stale presentation when the screen changed before an asynchronous response arrived.


### Android

- `TreasureData.setLinkHandler` receives app-owned URL navigation.
- `TreasureData.setBridgeListener` receives custom `invoke` actions through `TDEngageBridgeListener`.
- The app must validate URLs, action names, login state, permissions, and parameters.


The SDK does not authorize app-specific actions on behalf of the app. Keep delegates alive for as long as callbacks are needed.

## Push Token Registration

Use `registerDeviceToken` after the app obtains an APNs or FCM token.

```swift
TreasureData.sharedInstance().registerDeviceToken(
    token,
    provider: .apns,
    table: "device_tokens"
)
```

```java
TreasureData.sharedInstance().registerDeviceToken(
    token,
    TDPushProvider.FCM,
    "device_tokens"
);
```

The app remains responsible for notification permission, Push receipt, notification display, and notification-tap handling. See [Mobile Push Device Token Registration](/products/marketing-cloud/engage-studio/channels/mobile-push/device-token-registration) for the preview record schema.

## Event Definitions

The SDK uses three event namespaces. Do not use them interchangeably:

- `event` identifies an app- or device-initiated record.
- `event_name` identifies an SDK-generated campaign measurement record.
- `td_ios_event` or `td_android_event` identifies an optional core SDK lifecycle or purchase record.


### Campaign Measurement Events

Campaign measurement records are sent to the `engage_inapp_{workspace_id}.events` destination. The SDK derives the database name from the offer's `workspace_id`; `workspace_id` is not a field in the record.

Every campaign measurement record contains:

| Field | Description |
|  --- | --- |
| `message_id` | ID of the campaign message in the Personalization offer. |
| `event_name` | `impression`, `click`, or `dismiss`. |
| `message_type` | `modal`, `banner`, or `lp`. |


#### `impression`

The SDK creates `impression` after it successfully presents a campaign-delivered message. It does not wait for the hosted page to finish loading. No action-specific fields are added.

#### `click`

The SDK creates `click` when a supported link or bridge action is used.

| Field | Description |
|  --- | --- |
| `action_type` | `href`, `openUrl`, or `invoke`. |
| `action_value` | The destination URL or the `invoke` action name. |
| `action_params` | A JSON string for an `invoke` action when the parameters can be serialized. |


A normal HTTP(S) link and an external `_blank` link use `action_type: "href"`. An app-owned URL uses `openUrl`; a bridge action uses `invoke`.

#### `dismiss`

The SDK creates `dismiss` when the campaign experience closes.

| Field | Description |
|  --- | --- |
| `dismiss_method` | For example, `content`, `td_close_button`, `td_overlay`, or `td_link`. A hosted page can provide an additional label. |


A non-HTTP link or a bridge `openUrl` action can create both a click and a `dismiss` with `dismiss_method: "td_link"`.

### Core SDK Enrichment for Measurement

These are general Core SDK fields, not Mobile In-App-specific event definitions. Campaign measurement records can use the Core SDK event enrichment pipeline:

| Field | Description |
|  --- | --- |
| `time` | Added by default as a local Unix timestamp in seconds. |
| `td_uuid` | Added when `enableAutoAppendUniqId()` is enabled. |
| `td_app_ver`, `td_app_ver_num` | Added when app information is enabled. |
| `td_locale_country`, `td_locale_lang` | Added when locale information is enabled. |
| `td_device`, `td_model`, `td_os_ver`, `td_os_type` | Added when device information is enabled. Android can also add `td_board`, `td_brand`, and `td_display`. |
| `record_uuid` | Added when per-record UUID enrichment is enabled. |
| `td_maid` | Added when advertising identifier enrichment is enabled and an identifier is available. |
| `td_session_id` | Added while an explicit SDK session is active. |


IP tracking adds `td_ip` on the server side when the Core SDK IP tracking option is enabled; it is not part of the client event map.

`trackImmediately` sends an enriched trigger record directly to the Personalization endpoint instead of passing through the local event buffer. Campaign measurement records use `addEvent`.

### App- or Content-Initiated Events

#### `trackImmediately`

The app supplies the event map that starts Personalization evaluation. The field names and values are part of the app's campaign contract.

```json
{
  "event": "pageview",
  "screen_name": "home"
}
```

The SDK does not automatically create `purchase`, `add_to_cart`, `search`, or other business events. The app must send those events explicitly if a campaign uses them.

#### `TDBridge.track`

Message content can send an arbitrary event through the bridge. The latest Engage implementation routes the event to the app's configured default database and table as a normal event record. This is distinct from the SDK-generated `click` measurement event.

Validate the event name and every value before using the event for targeting or reporting.

### Device Token Event

After the app obtains an APNs or FCM token, it can register the token with the following record:

```json
{
  "td_device_token": "<TOKEN>",
  "td_push_provider": "fcm"
}
```

`td_push_provider` is `apns` or `fcm`. The app obtains the token and calls the API; the SDK does not request notification permission or discover the token automatically. The token record is separate from the existing `token_register` / `fcm_token` sample schema in the Mobile Push documentation.

### Events Not Created by the SDK

The SDK does not create campaign measurement events for:

- A direct app call to `openUrl`.
- A response with no matching campaign.
- A candidate skipped because another message is already visible.
- A presentation rejected by the host screen-state gate.
- A Push delivery, receipt, or tap unless the app sends a separate event.


Core SDK lifecycle and Android purchase events are separate opt-in features; they are not Mobile In-App campaign measurement events.

## Measurement Opt-Out

Campaign measurement uses the Core SDK custom-event path. If the app disables custom events with `disableCustomEvent()`, `impression`, `click`, `dismiss`, and other records sent through that path can be dropped. Apply the app's consent policy before enabling the campaign measurement flow.

## API Usage Rules

- Initialize the Core SDK once before calling Engage APIs.
- On iOS, call `TDEngage.install()` before the first trigger event. On Android, rendering is bundled in `td-android-sdk` and needs no install step.
- Use `trackImmediately` for campaign-triggering events; do not use `addEvent` when display is required.
- Keep API keys and Personalization tokens outside message content and profile context.
- Treat Hosted Pages content, Bridge action names, and action parameters as untrusted input.
- Use the release-specific iOS and Android API contract supplied with the preview artifact.


## Related Documentation

- [Mobile In-App Messaging](/products/marketing-cloud/engage-studio/channels/mobile-inapp)
- [Set Up Mobile In-App Messaging](/products/marketing-cloud/engage-studio/channels/mobile-inapp/setup-and-prerequisites)
- [Create a Mobile In-App Message](/products/marketing-cloud/engage-studio/channels/mobile-inapp/create-an-in-app-message)
- [Message Types and Appearance](/products/marketing-cloud/engage-studio/channels/mobile-inapp/message-types-and-appearance)
- [Hosted Pages](/products/marketing-cloud/engage-studio/channels/mobile-inapp/rich-landing)
- [Mobile In-App Measurement](/products/marketing-cloud/engage-studio/channels/mobile-inapp/measurement)
- [Mobile In-App Troubleshooting](/products/marketing-cloud/engage-studio/channels/mobile-inapp/troubleshooting)
- [Mobile Push Device Token Registration](/products/marketing-cloud/engage-studio/channels/mobile-push/device-token-registration)