# iOS開発者ガイド

ベータ機能
Mobile Pushは現在ベータ版です。機能、API、実装の詳細は正式リリース前に変更される可能性があります。

## 概要

このガイドでは、Treasure Data iOS SDKを使用してiOSアプリにEngage Studio Mobile Push通知を統合するための実装要件を提供します。開発チームは次の機能を実装する必要があります:

1. **APNs/FCM連携**: Apple Push Notification ServiceとFirebase Cloud Messaging経由でプッシュ通知を受信
2. **トークン管理**: デバイストークンをTreasure Dataに登録および更新
3. **リッチ通知**: Notification Service Extensionを使用して画像付き通知を表示
4. **イベントトラッキング**: Treasure Data SDKを使用してユーザーインタラクション(配信、開封、削除、リンク)をトラッキング
5. **自動データアップロード**: Treasure Data SDKがイベントのTreasure Dataへのアップロードを自動的に処理


サンプル実装が利用可能
本番環境対応の完全なサンプルアプリケーションがGitHubで公開されています:

**[Treasure Data Mobile Push - iOSサンプル](https://github.com/treasure-data/engage-push-notification-sample/tree/main/ios)**

サンプルに含まれる内容:

- FCMとTreasure Data SDK連携を含む完全なAppDelegate実装
- リッチメディア用のNotification Service Extension
- Treasure Data SDKを使用したイベントトラッキング
- ディープリンクとWebリンク処理


リポジトリをクローンして実装の参考にしてください。

## ネイティブSDKプレビュー: デバイストークン登録

プレビュー版Mobile SDKには、APNsまたはFCMのデバイストークンをTreasure AIへ送信する`registerDeviceToken`が含まれています。トークンの取得、通知権限のリクエスト、通知の受信・表示、通知タップの処理はアプリが引き続き担当します。SDK APIとプレビュー版レコードスキーマについては、[デバイストークン登録](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/device-token-registration)を参照してください。

PushとHosted Pages
Push payloadにURLが含まれている場合、アプリからSDKへ渡してHosted Pagesを表示できます。SDKは現在、APNsまたはFCMの受信サービスを管理しません。

## 必要要件

| コンポーネント | 要件 |
|  --- | --- |
| **最小iOSバージョン** | iOS 15.0以降 |
| **言語** | Swift (推奨) またはObjective-C |
| **必要なフレームワーク** | - Firebase Messaging SDK 12.7.0+
- Treasure Data iOS SDK 1.2.1+
- UserNotificationsフレームワーク
- SafariServices (Webリンク処理用)

 |
| **Xcodeバージョン** | Xcode 16.2以降 |
| **トラッキングイベント** | `delivery`, `open`, `dismiss`, `deeplink_open`, `link_open`, `token_register` |


## アーキテクチャ概要

iOSアプリ実装は以下のコンポーネントで構成されます:

### 1. AppDelegate設定

**目的:** FirebaseとTreasure Data SDKを初期化し通知デリゲートを設定する

**主な責務:**

- Firebase SDKを初期化
- endpointとdatabaseの設定でTreasure Data SDKを初期化
- 通知センターのデリゲートを設定
- ユーザーから通知パーミッションをリクエスト
- リモート通知に登録
- フォアグラウンドとバックグラウンドで通知イベントを処理


**参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/ios)の`AppDelegate.swift`を参照してください

### 2. Notification Service Extension

**目的:** 通知に画像をダウンロードして添付する

**主な責務:**

- 表示前に通知を受信
- ペイロードから`image`を抽出
- リモートURLから画像をダウンロード
- UNNotificationAttachmentを作成
- 通知コンテンツに添付ファイルを追加


**参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/ios)の`NotificationService.swift`を参照してください

### 3. イベントトラッキング

**目的:** Treasure Data SDKでイベントトラッキングを管理する

**主な責務:**

- Treasure Data SDKでプッシュ通知イベントを記録
- `AppDelegate`で`delivery`、`open`、`dismiss`を記録し、`TrackingService`でlinkイベントを記録
- イベントをFCM tokenとユーザーIDに関連付け
- イベントデータの形式を管理


**参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/ios)の`AppDelegate.swift`と`TrackingService.swift`を参照してください

### 4. Deep Link Handler

**目的:** 通知からのdeep linkを処理する

**主な責務:**

- SceneDelegateまたはAppDelegate経由でdeep link URLを受信
- URL schemeとpathを解析
- deep linkに応じて画面に遷移
- SafariでWeb URLを開く
- deep linkのイベントを記録


**参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/ios)の`SceneDelegate.swift`を参照してください

## プロジェクトセットアップ

### ステップ1: XcodeGenでXcodeプロジェクトを生成

サンプルアプリではXcodeGenを使用します。XcodeGenをインストールします:

```bash
brew install xcodegen
```

Xcodeプロジェクトを生成します:

```bash
cd ios
xcodegen generate
```

### ステップ2: FirebaseとTreasure Data SDKを追加

サンプルはSwift Package Managerで依存関係を管理します。依存関係は`project.yml`に定義されています:

**Firebase iOS SDK** (12.7.0+):

- `FirebaseMessaging`
- `FirebaseAnalytics`


**Treasure Data iOS SDK** (1.2.1+):

- イベント記録とデータアップロード用SDK


生成したXcodeプロジェクトを開くと依存関係が解決されます。

### ステップ3: Firebaseを設定

1. Firebase Consoleから`GoogleService-Info.plist`をダウンロードします。
2. ファイルをプロジェクトにコピーします:

```bash
cp GoogleService-Info.plist ios/TDPushSample/GoogleService-Info.plist
```
3. Xcodeでメインアプリのtargetにファイルが追加されていることを確認します。


### ステップ4: Info.plistでTreasure Dataを設定

`Info.plist`にTreasure Dataの設定を追加します:

```xml
<key>TDWriteKey</key>
<string>your_write_api_key_here</string>
<key>TDDatabase</key>
<string>mobile</string>
<key>TDTable</key>
<string>push_events</string>
<key>TDEndpoint</key>
<string>https://in.treasuredata.com</string>
```

**注意:** 実際のAPI keyをソース管理にcommitしないでください。placeholderを使い、必要な設定を別途記載してください。

### ステップ5: XcodeでCapabilitiesを設定

1. Project Navigatorでプロジェクトを選択します。
2. アプリのtargetを選択します。
3. **Signing & Capabilities**タブを開きます。
4. **+ Capability**をクリックし、以下を追加します:
  - **Push Notifications**
  - **Background Modes** → **Remote notifications**にチェック


### ステップ6: Notification Service Extensionを作成（画像付き通知用）

通知に画像を表示するにはNotification Service Extensionが必要です:

1. Xcodeで**File** > **New** > **Target**を選択します。
2. **Notification Service Extension**を選択します。
3. Extension名（例: `NotificationService`）を入力します。
4. **Finish**をクリックします。


### ステップ7: Info.plistでdeep linkを設定

1. `Info.plist`にURL schemeを登録します:


```xml
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
        <key>CFBundleURLName</key>
        <string>com.example.myapp</string>
    </dict>
</array>
```

1. サンプルの通知タップ処理で使用するschemeと許可する遷移先を設定します:


```xml
<key>TDDeepLinkScheme</key>
<string>myapp</string>
<key>TDAllowedDeepLinkHosts</key>
<array>
    <string>product</string>
</array>
<key>TDAllowedDomains</key>
<array>
    <string>example.com</string>
</array>
```

**設定の補足:**

- この例では`myapp://product/12345`と`https://example.com/promo`を許可します。
- `TDDeepLinkScheme`は`CFBundleURLSchemes`に登録したschemeと一致させてください。
- サンプルには`tdpushsample`用の設定があります。変更していないfixtureをテストするときは、その設定を維持してください。


## データペイロードスキーマ

アプリは通知の`userInfo`で以下のJSON構造を受信します。APNsの`aps`とFCMのcustom data fieldは`userInfo`の直下に配置されます。

```json
{
  "aps": {
    "alert": {
      "title": "Special Offer!",
      "body": "Get 20% off your next purchase"
    },
    "content-available": 1,
    "category": "default",
    "mutable-content": 1
  },
  "tdCampaignId": "cmp_20251214_promo",
  "title": "Special Offer!",
  "message": "Get 20% off your next purchase",
  "image": "https://cdn.example.com/banner.png",
  "link": "myapp://product/12345"
}
```

| フィールド | 型 | 必須 | 説明 |
|  --- | --- | --- | --- |
| `aps.content-available` | Integer | Yes | Engage Studioにより`1`に設定されます。iOSがcallbackを呼び出したときにアプリが`delivery`イベントを記録できるよう、バックグラウンド実行を要求します。バックグラウンド実行は保証されません。 |
| `aps.category` | String | Yes | Engage Studioにより`default`に設定されます。アプリが登録する通知カテゴリを識別し、ユーザーが通知を削除したときにコールバックを受信できるようにすることで、`dismiss`トラッキングを有効化します。 |
| `aps.mutable-content` | Integer | No | 画像付き通知で`1`に設定されます。Notification Service Extensionによる画像の添付を有効にします。 |
| `tdCampaignId` | String | Yes | Engage Studioからの一意のキャンペーン識別子 |
| `title` | String | Yes | 通知タイトル |
| `message` | String | Yes | 通知本文テキスト。iOS通知に表示される本文は`aps.alert.body`です。 |
| `image` | String | No | 通知画像のURL。画像付き通知ではFCMのAPNs image optionにも設定されます。 |
| `link` | String | No | **On click behavior**に応じたWeb URLまたはdeep link。**Open app**では省略され、通知タップ時は追加のURL遷移を行わずにアプリを開きます。 |


### 配信トラッキングと削除トラッキングのためのAPNsフィールド

Engage Studioは、アプリが配信イベントと削除イベントをトラッキングできるように、すべてのiOSプッシュ通知の`aps`ディクショナリに2つのフィールドを自動的に追加します:

これらのフィールドの仕組み
- **`content-available: 1`** — **delivery**イベントを記録するため、短時間のバックグラウンド実行をiOSに要求します。バックグラウンド処理を実行するか、いつ実行するかはiOSが決めるため、callbackは保証されません。Appleの[Pushing background updates to your app](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app)を参照してください。
- **`category: default`** — 通知を通知カテゴリに関連付けます。アプリがカスタム削除アクションを許可する一致するカテゴリを登録すると、ユーザーが通知をスワイプして削除したときにiOSがデリゲートを呼び出し、**dismiss**トラッキングを有効化します。Appleの[Generating a remote notification](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)を参照してください。


これらのペイロードフィールドはEngage Studioにより自動的に送信されるため、キャンペーンの設定は不要です。ただし、配信イベントと削除イベントを実際にキャプチャするには、後述の[必要なアプリ側のセットアップ](#%E9%85%8D%E4%BF%A1%E3%83%88%E3%83%A9%E3%83%83%E3%82%AD%E3%83%B3%E3%82%B0%E3%81%A8%E5%89%8A%E9%99%A4%E3%83%88%E3%83%A9%E3%83%83%E3%82%AD%E3%83%B3%E3%82%B0%E3%81%AE%E6%9C%89%E5%8A%B9%E5%8C%96%E5%BF%85%E8%A6%81%E3%81%AA%E3%82%A2%E3%83%97%E3%83%AA%E5%81%B4%E3%81%AE%E3%82%BB%E3%83%83%E3%83%88%E3%82%A2%E3%83%83%E3%83%97)を完了する必要があります。

## イベントトラッキング

アプリは以下のイベントをトラッキングしTreasure Dataに送信する必要があります:

| イベントタイプ | トラッキングタイミング | 必須フィールド |
|  --- | --- | --- |
| `delivery` | iOSがforeground通知delegateまたはbackground remote-notification callbackを呼び出したとき。background実行はbest-effortです。 | `campaign_id`, `platform`, `time` |
| `open` | ユーザーが通知をタップしたとき | `campaign_id`, `platform`, `time` |
| `dismiss` | ユーザーが通知を削除したとき | `campaign_id`, `platform`, `time` |
| `link_open` | ユーザーがWebリンクをタップしたとき | `campaign_id`, `platform`, `time`, `value` (URL) |
| `deeplink_open` | ユーザーがディープリンクをタップしたとき | `campaign_id`, `platform`, `time`, `value` (URI) |
| `token_register` | FCMトークンが取得または更新されたとき | `fcm_token`, `platform`, `time`, `user_id` (ログイン時) |


**実装ノート:**

- **ユーザーID:** 共通イベントスキーマでは`user_id`は必須フィールドではありません。ログイン済みユーザーの場合は`token_register`に含めます。匿名ユーザーの場合は省略するか、`null`を送信できます。Treasure AIは登録済みの`fcm_token`を使って、それ以前のイベントをユーザーに関連付けられます。
- **Campaign ID:** `userInfo["tdCampaignId"]`をイベントの`campaign_id`に記録します。
- **FCM message ID:** `userInfo["gcm.message_id"]`をイベントの`message_id`に記録します。FCMが付加するmetadataであり、custom dataのfieldではありません。
- **アップロード:** Treasure Data SDKでイベントを記録し、`uploadEvents()`で送信します。SDKはキューイングとアップロードの再試行を処理します。


配信イベントと削除イベントにはアプリ側のセットアップが必要
backgroundの`delivery`イベントと`dismiss`イベントは、Engage Studioがペイロードに追加する`content-available`フィールドと`category`フィールドに依存します。iOSはbackground実行を遅らせたり省略したりする場合があります。iOSがcallbackを呼び出したときにイベントを記録するには、後述の[配信トラッキングと削除トラッキングの有効化](#%E9%85%8D%E4%BF%A1%E3%83%88%E3%83%A9%E3%83%83%E3%82%AD%E3%83%B3%E3%82%B0%E3%81%A8%E5%89%8A%E9%99%A4%E3%83%88%E3%83%A9%E3%83%83%E3%82%AD%E3%83%B3%E3%82%B0%E3%81%AE%E6%9C%89%E5%8A%B9%E5%8C%96%E5%BF%85%E8%A6%81%E3%81%AA%E3%82%A2%E3%83%97%E3%83%AA%E5%81%B4%E3%81%AE%E3%82%BB%E3%83%83%E3%83%88%E3%82%A2%E3%83%83%E3%83%97)のセットアップを完了してください。

完全なスキーマ詳細については[Push Events Table](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/push-events-table)ドキュメントを参照してください。

## 配信トラッキングと削除トラッキングの有効化（必要なアプリ側のセットアップ）

Engage Studioは、iOSプッシュペイロードに`content-available: 1`と`category: default`を自動的に追加します。これらのfieldはiOSがcallbackを呼び出したときに`delivery`イベントと`dismiss`イベントを記録できるようにしますが、background実行は保証しません。

### 1. Background Modesを有効化する

[ステップ5: XcodeでのCapabilitiesの設定](#%E3%82%B9%E3%83%86%E3%83%83%E3%83%975-xcode%E3%81%A7capabilities%E3%82%92%E8%A8%AD%E5%AE%9A)で説明されているように、アプリターゲットで**Background Modes → Remote notifications**を有効化します。これにより、システム条件が許す場合に、`content-available: 1`を持つ通知に対してiOSがアプリを短時間バックグラウンド実行し、`delivery`イベントを記録できます。

### 2. `default`通知カテゴリを登録する

通知が削除されたときにiOSがアプリに通知するように、識別子`default`と`.customDismissAction`オプションを持つ`UNNotificationCategory`を登録します。通知センターを設定するとき（たとえば`application(_:didFinishLaunchingWithOptions:)`内）にカテゴリを設定します:

```swift
let defaultCategory = UNNotificationCategory(
    identifier: "default",
    actions: [],
    intentIdentifiers: [],
    options: [.customDismissAction]
)
UNUserNotificationCenter.current().setNotificationCategories([defaultCategory])
```

`identifier`はペイロードで送信される`category`の値（`default`）と一致する必要があります。`setNotificationCategories`は登録済みカテゴリ全体を置き換えるため、他のSDKや機能で使うカテゴリも一緒に登録してください。

### 3. 削除イベントをトラッキングする

ユーザーが通知をスワイプして削除すると、iOSはアクション識別子として`UNNotificationDismissActionIdentifier`を指定して`userNotificationCenter(_:didReceive:withCompletionHandler:)`を呼び出します。`handleNotificationResponse`でアクションを判定し、`dismiss`イベントをトラッキングします:

```swift
func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    DispatchQueue.main.async {
        self.handleNotificationResponse(response)
        completionHandler()
    }
}
```

### 4. バックグラウンド配信をトラッキングする

iOSが`content-available: 1`を持つ通知について`application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`を呼び出したときに、そこで`delivery`イベントを記録します。フォアグラウンド通知は`willPresent`デリゲートですでにトラッキングされているため、`applicationState != .active`でガードし、イベントの重複を避けます。background実行はbest-effortです:

```swift
func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
    // ここではバックグラウンド配信のみをトラッキングします。
    // フォアグラウンド配信は重複イベントを避けるため willPresent デリゲートでトラッキングします。
    if application.applicationState != .active {
        trackDeliveryEvent(userInfo: userInfo)
    }
    completionHandler(.newData)
}
```

リファレンス実装
[サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/ios)では、通知への応答を次のように処理します。

- `AppDelegate.handleNotificationResponse`でaction identifierに応じて`open`または`dismiss`を記録します。
- `SceneDelegate`の`connectionOptions.notificationResponse`も同じhelperに渡し、request identifierとaction identifierで重複を抑止します。
- タップ後の画面遷移はSceneがactiveになるまで保留します。


## テスト

### 実機でのテスト

#### Engage Studioのテストを送信

1. iOS実機でアプリを実行し、現在のFCM tokenをアプリログから取得します。
2. Engage StudioでMobile Push campaignを開き、**キャンペーンコンテンツ**タブを選択します。
3. **モバイルプッシュ通知を新規作成**をクリックします。既存のコンテンツがある場合は**編集**をクリックします。**モバイルプッシュ通知エディタ**が開きます。
4. **モバイルプッシュ認証**で、アプリのFirebaseプロジェクトに対応する認証を選択します。
5. **タイトル**と**メッセージ**を入力します。画像やタップ時の動作をテストする場合は、**画像**と**クリック時の動作**を設定します。
6. **テスト送信**をクリックします。
7. **テストデバイストークン**にtokenを入力します。
8. **送信**をクリックします。
9. 通知、タップ時の動作、campaign eventを確認します。


foreground、background、アプリ終了状態からのタップをそれぞれ確認します。1回のタップで`open`が1件記録され、設定した画面またはweb linkが開くことを確認します。**アプリを開く**の場合はアプリの画面を表示します。

**注意:** backgroundのdelivery trackingは、iOSがcallbackを呼び出した場合に記録されます。background実行は保証されないため、終了状態からのタップの確認では`delivery`イベントを必須にしません。

### シミュレーターで通知処理をローカルテスト

iOS 15+のシミュレーターでアプリを起動し、通知を許可します。

1. サンプルの[test-notification.apns](https://github.com/treasure-data/engage-push-notification-sample/blob/main/shared/test-payloads/test-notification.apns)をローカルに保存します。
2. `Simulator Target Bundle`を自分のアプリのBundle IDに設定します。`link`には、`myapp://product/12345`など、アプリが処理できるdeep linkを設定します。
3. シミュレーターにpayloadを送信します:


```bash
xcrun simctl push booted com.example.myapp test-notification.apns
```

1. 通知表示とタップ時の動作を確認します。


ローカルテストの範囲
- `simctl push`はFCMとAPNsの配信経路を通らず、FCMが生成するmessage IDも含みません。
- 画像付き通知、campaignの配信経路、関連するevent trackingは、iOS実機でEngage Studioの**テスト送信**を使って確認してください。


### イベントトラッキングの確認

Treasure Dataでクエリを実行してイベントがログに記録されていることを確認:

```sql
SELECT
  time,
  type,
  campaign_id,
  platform
FROM mobile.push_events
WHERE platform = 'ios'
ORDER BY time DESC
LIMIT 100
```

## ユーザーID関連付け

プッシュ通知イベントを特定のユーザーとリンクするには、FCMトークン登録時に`user_id`を渡します。

**実装ノート:**

- **ログインユーザー**: トークン登録イベントに`user_id`(例: 顧客ID、メールハッシュ値)を含める
- **未ログインユーザー**: `user_id`に`nil`を渡す — Treasure Dataはユーザーログイン時に後でトークンを関連付けます
- **名前解決**: Treasure Dataは時間経過に伴う`fcm_token`値の照合によってイベントをリンクします


## トラブルシューティング

### 通知が受信されない

1. **APNs証明書を確認**: APNs認証キーがFirebase Consoleにアップロードされているか確認
2. **Bundle IDを確認**: XcodeのBundle IDがFirebase登録と一致するか確認(大文字小文字を区別)
3. **通知パーミッションを確認**: 設定 > 通知でアプリが通知パーミッションを持っているか確認
4. **デバイス登録を確認**: `didRegisterForRemoteNotificationsWithDeviceToken`が呼ばれているか確認
5. **campaign配信を確認**: Engage Studioの**テスト送信**で、Firebaseプロジェクトに対応する**モバイルプッシュ認証**と現在のFCM tokenを使って確認します。


### リッチ画像が表示されない

1. **Notification Service Extensionを確認**: Extensionが適切に設定されアプリに追加されているか確認
2. **画像URLを確認**: URLがHTTPSであり画像にアクセス可能か確認
3. **Extensionログを確認**: Console.appを使用してExtensionログを確認
4. **ファイルサイズを確認**: 大きな画像はタイムアウトする可能性あり(制限約10MB)


### イベントがTreasure Dataに表示されない

1. **書き込みキーを確認**: Info.plistの`TDWriteKey`が正しくアクティブであるか確認
2. **エンドポイントを確認**: `TDEndpoint`がリージョン(US、東京、EU)と一致するか確認
3. **テーブル名を確認**: `TDDatabase`と`TDTable`がTreasure Dataに存在するか確認
4. **SDK初期化を確認**: AppDelegateでTreasure Data SDKが初期化されているか確認
5. **ログを有効化**: `TreasureData.enableLogging()`を追加してSDKの動作を確認
6. **手動アップロード**: `TreasureData.sharedInstance().uploadEvents()`を手動で呼び出してみる


### ディープリンクが機能しない

1. **URLスキームを確認**: `Info.plist`に正しい`CFBundleURLTypes`設定があるか確認
2. **ディープリンクをテスト**: Safariでテスト: アドレスバーに`myapp://test`を入力
3. **Scene Delegateを確認**: `scene(_:openURLContexts:)`が実装されているか確認
4. **URI形式を確認**: ディープリンクが登録されたスキームで始まっているか確認


## セキュリティのベストプラクティス

1. **APIキーを保護**:
  - 実際の`TDWriteKey`をソース管理にコミットしない
  - GitにコミットするInfo.plistにはプレースホルダー値を使用
  - 必要な設定を別途ドキュメント化
  - 書き込み専用キーを使用(マスターキーではない)
  - 本番アプリではKeychainの使用を検討
2. **ディープリンクを検証**:
  - ナビゲーション前にディープリンクの宛先を常に検証
  - 機密性の高いアクションにURL許可リストを実装
  - ディープリンクパラメータをサニタイズ
3. **イベントデータを保護**:
  - イベントペイロードにPII(個人を特定できる情報)を含めない
  - 可能な限りハッシュ化または匿名化されたユーザーIDを使用
4. **ネットワークセキュリティ**:
  - APIエンドポイントには常にHTTPSを使用
  - App Transport Security (ATS)を実装
  - 本番アプリでは証明書ピン留めを検討


## サンプルリポジトリ

完全な本番環境対応の実装:

**[https://github.com/treasure-data/engage-push-notification-sample/tree/main/ios](https://github.com/treasure-data/engage-push-notification-sample/tree/main/ios)**

リポジトリに含まれる内容:

- インラインドキュメント付きの完全なソースコード
- XcodeGenプロジェクト設定
- Swift Package Manager依存関係管理
- Treasure Data SDK連携の例
- テスト手順
- セキュリティのベストプラクティス


## 実装ガイド

このセクションでは、サンプルアプリケーションのビルドとテストの詳細な手順を提供します。

### プロジェクト構造

サンプルリポジトリのディレクトリ構造:

```
ios/
├── TDPushSample/
│   ├── AppDelegate.swift           # Firebase & TD SDK init, notification delegates
│   ├── SceneDelegate.swift         # Deep link routing
│   ├── ViewController.swift        # Main UI
│   ├── TrackingService.swift       # Event tracking with TD SDK
│   ├── CategoryView.swift          # Category example
│   ├── ProductDetailView.swift     # Product detail example
│   ├── Models/                     # Data models
│   ├── Utils/                      # Utility classes
│   ├── Assets.xcassets
│   ├── Info.plist                  # App config & TD settings
│   └── GoogleService-Info.plist.example  # Firebase config template
├── NotificationService/             # Extension for rich media
│   └── NotificationService.swift
├── project.yml                      # XcodeGen configuration
└── TDPushSample.xcodeproj/         # Generated by XcodeGen
```

### ビルドと実行手順

#### 事前準備

- macOS 14.5以降
- Xcode 16.2以降
- HomebrewでインストールしたXcodeGen


#### セットアップ手順

1. リポジトリをcloneします:


```bash
git clone https://github.com/treasure-data/engage-push-notification-sample.git
cd engage-push-notification-sample/ios
```

1. XcodeGenをインストールしていない場合はインストールします:


```bash
brew install xcodegen
```

1. Xcodeプロジェクトを生成します:


```bash
xcodegen generate
```

1. Firebaseを設定します:
  - Firebase projectから`GoogleService-Info.plist`をダウンロードします。
  - `TDPushSample/GoogleService-Info.plist`にコピーします。
2. Treasure Dataを設定します:
  - `TDPushSample/Info.plist`を開きます。
  - 以下のkeyを自分の設定に更新します:
    - `TDWriteKey`: 書き込み専用API key
    - `TDDatabase`: database名（例: `mobile`）
    - `TDTable`: table名（例: `push_events`）
    - `TDEndpoint`: TD endpoint（例: `https://in.treasuredata.com`）
3. Xcodeでプロジェクトを開きます:


```bash
open TDPushSample.xcodeproj
```

1. ビルドして実行します:
  - targetのdeviceまたはsimulatorを選択します。
  - Cmd+Rでビルドして実行します。
  - Swift Package Managerが依存関係を解決します。


### テストワークフロー

#### 事前準備

テストを開始する前に、以下を確認してください:

- [ ] iOSアプリが登録されたFirebaseプロジェクト
- [ ] Firebase ConsoleにアップロードされたAPNs認証キー
- [ ] ダウンロードしてプロジェクトに追加された`GoogleService-Info.plist`
- [ ] 作成されたTreasure Dataデータベースとテーブル
- [ ] 取得した書き込み専用APIキー
- [ ] iOS実機またはiOS 15+シミュレーター


#### シミュレーターで通知処理をローカルテスト

1. 生成した`TDPushSample.xcodeproj`を開き、利用可能なシミュレーターを選択し、Cmd+Rでアプリをインストールして起動します。通知権限を求められたら許可してください。
2. サンプルリポジトリの`ios`ディレクトリから、シミュレーター用fixtureを注入します:


```bash
xcrun simctl push booted com.treasuredata.pushsample ../shared/test-payloads/test-notification.apns
```

1. 通知表示と、`tdpushsample://product/12345`に対応する商品画面への遷移を確認します。


このテストで確認できる範囲は[シミュレーターで通知処理をローカルテスト](#%E3%82%B7%E3%83%9F%E3%83%A5%E3%83%AC%E3%83%BC%E3%82%BF%E3%83%BC%E3%81%A7%E9%80%9A%E7%9F%A5%E5%87%A6%E7%90%86%E3%82%92%E3%83%AD%E3%83%BC%E3%82%AB%E3%83%AB%E3%83%86%E3%82%B9%E3%83%88)を参照してください。

#### 実機でのテスト

1. USBケーブルでデバイスを接続
2. デバイスでDeveloper Modeを有効化:
  - 設定 > プライバシーとセキュリティ > Developer Mode
3. Xcodeからアプリをビルドしてインストール
4. XcodeコンソールでFCMトークンを確認:


```
FCM token: [your-token-here]
```

1. Engage Studioからcampaign testを送信:
デバイスの現在のFCM tokenを使い、[Engage Studioのテストを送信](#engage-studio%E3%81%AE%E3%83%86%E3%82%B9%E3%83%88%E3%82%92%E9%80%81%E4%BF%A1)の手順に従います。
2. 通知が表示され、設定したタップ時の動作とcampaign eventが記録されることを確認します。


#### イベントトラッキングの確認

Treasure Dataにクエリを実行してイベントがログに記録されていることを確認:

```sql
SELECT
  time,
  type,
  campaign_id,
  platform,
  user_id
FROM mobile.push_events
WHERE platform = 'ios'
  AND time > td_time_add(now(), '-1h', 'JST')
ORDER BY time DESC
LIMIT 20
```

期待されるイベントシーケンス:

1. `token_register` - アプリ起動時
2. `delivery` - iOSがforegroundまたはbackgroundのdelivery callbackを呼び出したとき。background実行はbest-effortです
3. `open` - ユーザーが通知をタップ時
4. `link_open` または `deeplink_open` - 通知にリンクが含まれる場合


### 実装チェックリスト

自分のアプリにプッシュ通知を実装する際は、このチェックリストを使用してください:

#### フェーズ1: プロジェクトセットアップ

- [ ] XcodeGenをインストール: `brew install xcodegen`
- [ ] iOSプロジェクトを作成またはclone
- [ ] `xcodegen generate`でXcodeプロジェクトを生成
- [ ] XcodeでPush Notifications capabilityを追加
- [ ] Background Modes capability（Remote notifications）を追加
- [ ] Info.plistにdeep link用URL schemeを設定
- [ ] `GoogleService-Info.plist`をダウンロードして追加
- [ ] Info.plistにTreasure Dataの設定を追加


#### フェーズ2: コアコンポーネント

- [ ] `AppDelegate`でFirebaseを初期化
- [ ] `AppDelegate`でTreasure Data SDKを初期化
- [ ] `UNUserNotificationCenter` delegateを設定
- [ ] Firebase Messaging delegateを設定
- [ ] 通知権限をリクエスト
- [ ] リモート通知に登録
- [ ] TD SDKでイベントを記録する`TrackingService`を作成


#### フェーズ3: Notification Service Extension

- [ ] Notification Service Extensionターゲットを作成
- [ ] `NotificationService`クラスを実装
- [ ] 画像ダウンロードロジックを追加
- [ ] 画像用の`UNNotificationAttachment`を作成
- [ ] Extensionタイムアウトを適切に処理


#### フェーズ4: イベントトラッキング

- [ ] `willPresent`デリゲートで`delivery`イベントを追跡
- [ ] `.customDismissAction`を持つ`default`通知カテゴリを登録
- [ ] バックグラウンド配信のためにBackground Modes（Remote notifications）が有効になっていることを確認
- [ ] `didReceiveRemoteNotification`でバックグラウンドの`delivery`イベントを追跡
- [ ] `didReceive response`デリゲートで`open`イベントを追跡
- [ ] `didReceive response`で`UNNotificationDismissActionIdentifier`の`dismiss`イベントを追跡
- [ ] Webリンクの`link_open`イベントを追跡
- [ ] アプリリンクの`deeplink_open`イベントを追跡
- [ ] アプリ起動時とトークン更新時に`token_register`イベントを追跡


#### フェーズ5: ディープリンク処理

- [ ] SceneDelegateで`scene(_:openURLContexts:)`を実装
- [ ] ディープリンクURLのスキームとパスを解析
- [ ] ディープリンクに基づいて適切な画面に遷移
- [ ] SafariまたはSFSafariViewControllerでWebリンクを処理
- [ ] ディープリンクの宛先を検証
- [ ] サンプルのタップ処理用に`TDDeepLinkScheme`、`TDAllowedDeepLinkHosts`、`TDAllowedDomains`を設定


#### フェーズ6: 設定とセキュリティ

- [ ] Info.plistに`TDWriteKey`、`TDDatabase`、`TDTable`、`TDEndpoint`を設定
- [ ] ソース管理ではAPI keyにplaceholderを使用
- [ ] 必要な設定を別途記載
- [ ] TD SDK操作のエラー処理を実装
- [ ] `TreasureData.enableLogging()`でデバッグ用ログを追加


#### フェーズ7: テスト

- [ ] `.apns` fixtureを使用してシミュレーターで通知処理をローカルテスト
- [ ] Engage Studioの**テスト送信**を使用して実機でcampaign配信とイベントをテスト
- [ ] 通知内のリッチメディア（画像）をテスト
- [ ] ディープリンクナビゲーションをテスト
- [ ] Webリンク開封をテスト
- [ ] Treasure Dataにイベントが表示されることを確認
- [ ] バックグラウンドアプリ状態でテスト
- [ ] 強制終了アプリ状態でテスト


### ビルドトラブルシューティング

#### "No such module 'Firebase'"または"No such module 'TreasureData'"エラー

- Swift Package Managerが依存関係を解決したことを確認
- File > Packages > Reset Package Cachesを試す
- ビルドフォルダをclean: Product > Clean Build Folder (Cmd+Shift+K)
- `xcodegen generate`でプロジェクトを再生成


#### Notification Service Extensionが画像を読み込まない

- 画像URLがHTTPSであることを確認
- 画像にアクセス可能であることを確認（ブラウザでURLをテスト）
- Console.appでExtensionログを確認
- スキーム設定でExtensionターゲットのメモリ制限を増やしていることを確認


#### イベントがTreasure Dataに表示されない

- Info.plistの`TDWriteKey`が正しいことを確認
- `TDEndpoint`がregionと一致することを確認
- `TDDatabase`と`TDTable`が正しいことを確認
- AppDelegateでTD SDKが初期化されていることを確認
- `TreasureData.enableLogging()`でログを有効化
- `TreasureData.sharedInstance().uploadEvents()`でアップロードを実行


#### ディープリンクが開かない

- Info.plistのURLスキームがディープリンクと一致することを確認
- Safariからディープリンクをテスト: アドレスバーに`myapp://test`を入力
- SceneDelegateで`scene(_:openURLContexts:)`が実装されていることを確認
- iOS 12以下の場合は、代わりにAppDelegateに実装


## 次のステップ

1. **サンプルリポジトリをクローン**して実装を確認
2. [Mobile Push Setup](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/mobile-push-setup)ガイドに従って**Firebaseを設定**
3. iOSアプリに**コンポーネントを実装**
4. **通知配信とイベントトラッキングをテスト**
5. [Push Events Table](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/push-events-table)で**イベントデータを確認**
6. [Engage Studio](/ja/products/marketing-cloud/engage-studio/channels/mobile-push)で**最初のキャンペーンを作成**


## 関連ドキュメント

- [Mobile Push Setup](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/mobile-push-setup) - FirebaseとAPNs設定
- [Android Developer Guide](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/developer-guide-android) - Android実装ガイド
- [Push Events Table](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/push-events-table) - イベントスキーマと分析クエリ
- [Campaign Creation](/ja/products/marketing-cloud/engage-studio/channels/mobile-push) - Mobile Pushキャンペーンの作成