# Engage Mobile SDK APIとイベントリファレンス

このページは、モバイルIn-AppメッセージングとHosted Pagesで使用するプレビュー版Engage Mobile SDKのAPIをまとめたリファレンスです。SDKが生成するイベント、アプリやメッセージコンテンツから送信するイベントも説明します。

プレビュー
iOSおよびAndroidのEngage Mobile SDKはプレビューです。一般提供前に、メソッド名、シグネチャ、ペイロードフィールド、パッケージ配布方法、イベントスキーマが変更される場合があります。使用するSDKバージョンに付属するリリース別のAPI契約を使用してください。

## APIの概要

| 目的 | iOS | Android |
|  --- | --- | --- |
| Core SDKの初期化 | `TreasureData.initializeWithApiKey` | `TreasureData.initializeSharedInstance` |
| Engageレンダリングの登録 | `TDEngage.install()` | 不要（`td-android-sdk`に内包） |
| メッセージ取得のトリガー | `trackImmediately` | `trackImmediately` |
| ページコンテキストの提供 | `profileContext` | `setProfileContext` / `setProfileValue` |
| アプリ所有URLの表示 | `openUrl(_:context:)` | `openUrl(url, context)` |
| Pushトークン登録 | `registerDeviceToken` | `registerDeviceToken` |
| アプリ所有リンクとアクションの処理 | `linkHandler`、`bridgeDelegate` | `setBridgeListener`（`TDEngageBridgeListener`）、`setLinkHandler` |
| 古い表示の抑制 | プレビュー版`inAppPresentationGate` | ホスト側の画面状態処理（プレビュー） |


## 起動時に使用するメソッド

### Core SDKを初期化する

アプリ起動時にCore SDKを一度初期化し、イベントとPersonalizationの送信先を設定します。

#### 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();
```

モバイルIn-Appのレンダリングは`td-android-sdk`に内包されています。AndroidにはiOSの`TDEngage.install()`に相当するレンダリングのインストール手順はありません。

依存関係と対応プラットフォームのバージョンは、SDKアーティファクトに付属するリリース別の導入手順を使用してください。ソースリポジトリURLをインストール依存関係として使用しないでください。

### `enableAutoAppendUniqId`

計測をインストール単位に関連付ける場合は、起動時にこのメソッドを呼び出します。トリガーイベントとSDKが生成する計測レコードに適用されます。

## メッセージトリガー

### `trackImmediately`

ユーザーがトラッキング対象の画面や、モバイルIn-Appキャンペーンをトリガーできるイベントに到達したときに使用します。

```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`はトリガーイベントを送信し、Realtime Personalizationからオファーを取得します。キャンペーンに一致しなければ、何も表示されません。`addEvent`と`uploadEvents`は通常イベントを送信しますが、Mobile In-App表示をトリガーしません。

SDKがメッセージを表示したかをアプリで記録する必要がある場合は、利用可能なコールバック形式を使用します。

## P13Nレスポンスを処理してメッセージを選択する

Realtime Personalizationは複数のオファーを返す場合があります。SDKはサポート対象のModal、Banner、またはHosted Pagesを1件選択し、不完全または未対応の候補をスキップします。

レスポンス形式はサービスが生成します。生のレスポンスフィールドはプレビュー版の内部情報として扱い、オファーマップを解析したり同率時の選択順に依存したりせず、SDKのレスポンス処理と表示APIを使用してください。

### 表示に関する制約

SDKは一度に1件のIn-Appエクスペリエンスだけを表示します。別のIn-Appエクスペリエンスが表示中に新しい候補を受信した場合、SDKは新しい候補をスキップし、その表示についてキャンペーン計測イベントを作成しません。SDKはクライアント側のFrequency capを適用しません。Frequency、優先順位、ターゲティング、A/Bの判定はRealtime Personalizationが行い、SDKは受信したレスポンス内の候補から選択するだけです。

## Profile Context

Profile Contextを使用すると、SDKはJSON化可能な値をModal、Banner、Hosted Pagesのコンテンツへ`window.TDContext`として注入します。

| プラットフォーム | API |
|  --- | --- |
| 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はイベント識別子の代わりにはなりません。APIキー、Personalization token、パスワード、不要な個人データを含めないでください。サインイン中のユーザーが変わったら、コンテキストをクリアまたは置き換えます。

## Hosted PagesとURL API

### `openUrl`

Push payloadなど、アプリがすでにURLを持っている場合に使用します。

```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
);
```

`openUrl`による直接表示はキャンペーンオファーではありません。キャンペーンIDがないため、キャンペーンの`impression`、`click`、`dismiss`イベントは作成されません。

### Hosted Pagesコンテンツ

キャンペーン配信されたHosted Pagesは、SDKがサポート対象のオファーを受け取るとSDKが処理します。生成されたレスポンスのフィールドに依存せず、ドキュメントに記載されたSDK APIを使用してください。

## リンクとカスタムアクション

### iOS

- `linkHandler`はアプリ所有のURL Schemeを処理し、アプリが処理したかどうかをBooleanで返します。
- `bridgeDelegate`は`TDEngageBridgeDelegate`を通じて`TDBridge.invoke`を受け取ります。
- `inAppPresentationGate`は、非同期レスポンスの到着前に画面が変わった場合、古い表示を抑制できます。


### Android

- `TreasureData.setLinkHandler`はアプリ所有のURL遷移を受け取ります。
- `TreasureData.setBridgeListener`は`TDEngageBridgeListener`を通じてカスタム`invoke`アクションを受け取ります。
- URL、アクション名、ログイン状態、権限、パラメーターをアプリで検証してください。


アプリ固有のアクションの認可はSDKが代わりに行いません。コールバックが必要な期間、Delegateを保持してください。

## Pushトークン登録

アプリがAPNsまたはFCMトークンを取得した後、`registerDeviceToken`を使用します。

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

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

通知権限、Push受信、通知表示、通知タップの処理はアプリが担当します。プレビュー版レコードスキーマは[Mobile Pushのデバイストークン登録](/products/marketing-cloud/engage-studio/channels/mobile-push/device-token-registration)を参照してください。

## イベント定義

SDKが扱うイベントには、3つの名前空間があります。用途を混同しないでください。

- `event`: アプリまたはデバイスが開始するレコードを識別します。
- `event_name`: SDKが生成するキャンペーン計測レコードを識別します。
- `td_ios_event` / `td_android_event`: オプションのCore SDKライフサイクル・課金レコードを識別します。


### キャンペーン計測イベント

キャンペーン計測レコードは、`engage_inapp_{workspace_id}.events`へ送信されます。`workspace_id`からデータベース名を生成しますが、レコードのカラムには含まれません。

すべてのキャンペーン計測レコードには次のフィールドが含まれます。

| フィールド | 説明 |
|  --- | --- |
| `message_id` | Personalizationオファー内のキャンペーンメッセージID。 |
| `event_name` | `impression`、`click`、`dismiss`のいずれか。 |
| `message_type` | `modal`、`banner`、`lp`のいずれか。 |


#### `impression`

キャンペーン配信されたメッセージを表示した直後に作成されます。ホストされたページの読み込み完了を待ちません。アクション固有のフィールドは追加されません。

#### `click`

対応するリンクまたはBridgeアクションを使用したときに作成されます。

| フィールド | 説明 |
|  --- | --- |
| `action_type` | `href`、`openUrl`、`invoke`のいずれか。 |
| `action_value` | 遷移先URLまたは`invoke`のアクション名。 |
| `action_params` | `invoke`のパラメーターをJSON文字列化した値。シリアライズできる場合だけ付与されます。 |


通常のHTTP(S)リンクと外部の`_blank`リンクは`action_type: "href"`、アプリ所有URLは`openUrl`、Bridgeアクションは`invoke`になります。

#### `dismiss`

キャンペーンエクスペリエンスを閉じたときに作成されます。

| フィールド | 説明 |
|  --- | --- |
| `dismiss_method` | `content`、`td_close_button`、`td_overlay`、`td_link`など。ホストページが追加のラベルを指定する場合もあります。 |


HTTP以外のリンクまたはBridgeの`openUrl`アクションでは、`click`に加えて`dismiss_method: "td_link"`の`dismiss`が作成される場合があります。

### 計測に使うCore SDKエンリッチ

これはMobile In-App固有のイベント定義ではなく、一般的なCore SDKフィールドです。キャンペーン計測レコードには、Core SDKのエンリッチ処理を適用できます。

| フィールド | 説明 |
|  --- | --- |
| `time` | デフォルトでローカル時刻のUnix epoch秒を付与します。 |
| `td_uuid` | `enableAutoAppendUniqId()`を有効にした場合に付与します。 |
| `td_app_ver`、`td_app_ver_num` | アプリ情報の自動付与を有効にした場合に付与します。 |
| `td_locale_country`、`td_locale_lang` | ロケール情報の自動付与を有効にした場合に付与します。 |
| `td_device`、`td_model`、`td_os_ver`、`td_os_type` | デバイス情報の自動付与を有効にした場合に付与します。Androidでは`td_board`、`td_brand`、`td_display`も付与できます。 |
| `record_uuid` | イベント単位UUIDの自動付与を有効にした場合に付与します。 |
| `td_maid` | 広告IDの自動付与を有効にし、取得できた場合に付与します。 |
| `td_session_id` | SDKのセッションを明示的に開始している間に付与します。 |


IPトラッキングを有効にした場合、`td_ip`はサーバー側で付与されます。クライアントのイベントマップには含まれません。

`trackImmediately`はエンリッチ済みのトリガーレコードをローカルイベントバッファを経由せずにPersonalizationエンドポイントへ直接送信します。キャンペーン計測レコードは`addEvent`を使用します。

### アプリまたはコンテンツが開始するイベント

#### `trackImmediately`

アプリが渡すイベントマップでPersonalizationの評価を開始します。フィールド名と値は、アプリとキャンペーンの契約で定義します。

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

SDKは`purchase`、`add_to_cart`、`search`などのビジネスイベントを自動生成しません。キャンペーンで使用する場合は、アプリから明示的に送信してください。

#### `TDBridge.track`

メッセージコンテンツはBridgeを通じて任意のイベントを送信できます。最新のEngage実装では、アプリのデフォルトデータベースとテーブルへ通常のイベントレコードとして送信します。SDKが生成する`click`計測イベントとは異なります。

ターゲティングやレポートに使用する前に、イベント名とすべての値を検証してください。

### デバイストークンイベント

アプリがAPNsまたはFCMトークンを取得した後、次のレコードを登録できます。

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

`td_push_provider`は`apns`または`fcm`です。トークンの取得とAPI呼び出しはアプリが担当し、SDKは通知権限を要求したりトークンを自動検出したりしません。既存の`token_register` / `fcm_token`サンプルスキーマとは別のレコードです。

### SDKが生成しないイベント

次の操作だけではキャンペーン計測イベントは作成されません。

- アプリからの直接`openUrl`呼び出し
- キャンペーンに一致するレスポンスがない場合
- 別のメッセージが表示中で候補がスキップされた場合
- ホスト側の画面状態ゲートによって表示が拒否された場合
- アプリが別途送信しないPush配信・受信・タップイベント


Core SDKのライフサイクルイベントとAndroidの課金イベントはオプション機能であり、Mobile In-Appキャンペーン計測イベントとは異なります。

## 計測のオプトアウト

キャンペーン計測はCore SDKのカスタムイベント経路を使用します。アプリで`disableCustomEvent()`を呼び出すと、`impression`、`click`、`dismiss`などのレコードが破棄される場合があります。キャンペーン計測を有効にする前に、アプリの同意ポリシーを適用してください。

## API利用ルール

- Engage APIを呼び出す前にCore SDKを一度初期化します。
- iOSでは最初のトリガーイベント前に`TDEngage.install()`を呼び出します。Androidではレンダリングが`td-android-sdk`に内包されており、インストール手順は不要です。
- キャンペーンをトリガーする場合は`trackImmediately`を使用します。表示が必要な場面で`addEvent`を使用しないでください。
- APIキーとPersonalization tokenをメッセージコンテンツやProfile Contextに含めません。
- Hosted Pagesコンテンツ、Bridgeアクション名、アクションパラメーターを信頼できない入力として扱います。
- プレビューアーティファクトに付属するiOS / Androidのリリース別API契約を使用します。


## 関連ドキュメント

- [モバイルIn-Appメッセージング](/ja/products/marketing-cloud/engage-studio/channels/mobile-inapp)
- [モバイルIn-Appメッセージングのセットアップ](/ja/products/marketing-cloud/engage-studio/channels/mobile-inapp/setup-and-prerequisites)
- [モバイルIn-Appメッセージを作成する](/ja/products/marketing-cloud/engage-studio/channels/mobile-inapp/create-an-in-app-message)
- [メッセージタイプと表示設定](/ja/products/marketing-cloud/engage-studio/channels/mobile-inapp/message-types-and-appearance)
- [Hosted Pages](/ja/products/marketing-cloud/engage-studio/channels/mobile-inapp/rich-landing)
- [モバイルIn-Appの計測](/ja/products/marketing-cloud/engage-studio/channels/mobile-inapp/measurement)
- [モバイルIn-Appのトラブルシューティング](/ja/products/marketing-cloud/engage-studio/channels/mobile-inapp/troubleshooting)
- [Mobile Pushのデバイストークン登録](/products/marketing-cloud/engage-studio/channels/mobile-push/device-token-registration)