iOS開発者ガイド

このガイドでは、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へのアップロードを自動的に処理

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

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

主な責務:

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

参照: サンプルリポジトリのAppDelegate.swiftを参照してください

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

主な責務:

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

参照: サンプルリポジトリのNotificationService.swiftを参照してください

目的: Treasure Dataとのデバイストークン登録を管理する

主な責務:

• FirebaseからFCMトークンを取得
• アプリ起動時にTreasure Dataにトークンを登録
• トークン更新時に再登録
• ユーザーログイン時にトークンとユーザーIDを関連付け
• token_registerイベントをトラッキング

参照: サンプルリポジトリのFCMTokenService.swiftを参照してください

目的: Treasure Dataにアップロードする前にイベントをローカルに保存する

主な責務:

• UserDefaultsにイベントを永続化
• 最大サイズ制限(1000イベント)でFIFOキューを実装
• アップロード用のバッチドレインをサポート
• キューオーバーフローを適切に処理
• DispatchQueueを使用したスレッドセーフな操作

参照: サンプルリポジトリのEventQueue.swiftを参照してください

目的: Treasure Data Ingest APIにイベントをアップロードする

主な責務:

• イベントをバッチアップロード(リクエストあたり最大500件)
• 信頼性の高い実行にバックグラウンドキューを使用
• 失敗したアップロードの再試行ロジックを実装
• Treasure Dataポストバック APIにイベントを送信
• アップロード失敗を適切に処理

参照: サンプルリポジトリのPushEventUploader.swiftを参照してください

目的: 通知からのディープリンクを処理する

主な責務:

• SceneDelegateまたはAppDelegate経由でディープリンクURLを受信
• URLスキームとパスを解析
• ディープリンクに基づいて適切な画面に遷移
• SafariでWeb URLを開く

参照: サンプルリポジトリのSceneDelegate.swiftを参照してください

1. Firebase ConsoleからGoogleService-Info.plistをダウンロード

2. ファイルをXcodeプロジェクトに追加:

   • GoogleService-Info.plistをプロジェクトナビゲーターにドラッグ
   • Copy items if neededにチェックが入っていることを確認
   • メインアプリターゲットに追加

3. Swift Package Managerを使用してFirebase SDKを追加:

   • Xcodeで File > Add Packages... に移動
   • 入力: https://github.com/firebase/firebase-ios-sdk
   • バージョン12.0.0以降を選択 (最新: 12.7.0)
   • 次のproductsを追加:
     • FirebaseMessaging
     • FirebaseAnalytics (オプション)

4. またはCocoaPodsを使用 (Podfileに追加):

platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'Firebase/Messaging', '~> 12.7'
  pod 'Firebase/Analytics', '~> 12.7'
end

その後実行:

pod install

1. Project Navigatorでプロジェクトを選択
2. アプリターゲットを選択
3. Signing & Capabilitiesタブに移動
4. + Capabilityをクリックして追加:
   • Push Notifications
   • Background Modes → Remote notificationsにチェック

通知で画像をサポートするには、Notification Service Extensionが必要です:

1. Xcodeで File > New > Target に移動
2. Notification Service Extensionを選択
3. Extension名を入力 (例: NotificationService)
4. Finishをクリック

Info.plistにURLスキームサポートを追加:

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

アプリは通知userInfoで以下のJSON構造を受信します。カスタムデータフィールドに加えて、Engage Studioは配信トラッキングと削除トラッキングを有効化するcontent-availableフィールドとcategoryフィールドを含む標準のAPNs apsディクショナリを含めます（後述の配信トラッキングと削除トラッキングのためのAPNsフィールドを参照）:

{
  "aps": {
    "alert": {
      "title": "Special Offer!",
      "body": "Get 20% off your next purchase"
    },
    "content-available": 1,
    "category": "default"
  },
  "td_campaign_id": "cmp_20251214_promo",
  "title": "Special Offer!",
  "body": "Get 20% off your next purchase",
  "image_url": "https://cdn.example.com/banner.png",
  "link": "https://example.com/promo"
}

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

これらのペイロードフィールドはEngage Studioにより自動的に送信されるため、キャンペーンの設定は不要です。ただし、配信イベントと削除イベントを実際にキャプチャするには、後述の必要なアプリ側のセットアップを完了する必要があります。

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

すべてのイベントはTreasure Data SDKにより、設定されたTreasure Dataエンドポイントに自動的に送信されます。SDKはバッチ処理、キューイング、再試行ロジックを自動的に処理します。

完全なスキーマ詳細についてはPush Events Tableドキュメントを参照してください。

Engage Studioは、iOSプッシュペイロードにcontent-available: 1とcategory: defaultを自動的に追加します。これらをdeliveryイベントとdismissイベントに変換するには、アプリで以下を実装する必要があります。

ステップ5: XcodeでのCapabilitiesの設定で説明されているように、アプリターゲットでBackground Modes → Remote notificationsを有効化します。これにより、content-available: 1を持つ通知が到着したときにiOSがアプリをバックグラウンドで起動できるようになり、deliveryイベントを記録できます。

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

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

identifierはペイロードで送信されるcategoryの値（default）と一致する必要があります。

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

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    let userInfo = response.notification.request.content.userInfo

    switch response.actionIdentifier {
    case UNNotificationDismissActionIdentifier:
        // User dismissed the notification
        TrackingService.shared.track(event: "dismiss", userInfo: userInfo)
    case UNNotificationDefaultActionIdentifier:
        // User tapped the notification
        TrackingService.shared.track(event: "open", userInfo: userInfo)
    default:
        break
    }

    completionHandler()
}

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

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

iOSシミュレーターはiOS 13とXcode 11.4+からプッシュ通知をサポートしています:

1. テストペイロードファイルtest-notification.apnsを作成:

{
  "Simulator Target Bundle": "com.example.myapp",
  "aps": {
    "alert": {
      "title": "Test Notification",
      "body": "This is a test message"
    },
    "sound": "default",
    "badge": 1
  },
  "campaign_id": "test_campaign",
  "message_id": "test_001",
  "deeplink": "myapp://test"
}

2. シミュレーターに送信:

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

1. アプリログからFCMトークンを取得
2. Firebase Console > Cloud Messagingを開く
3. Send your first messageをクリック
4. タイトルと本文を入力
5. Send test messageをクリック
6. FCMトークンを入力
7. デバイスに通知が表示されることを確認

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

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

プッシュ通知イベントを特定のユーザーとリンクするには、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. Firebase Consoleでテスト: Firebase Consoleから直接テスト通知を送信

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

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

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

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

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

サンプルリポジトリは以下のディレクトリ構造に従います:

ios/
├── MyApp/
│   ├── AppDelegate.swift           # Firebase初期化、通知デリゲート
│   ├── SceneDelegate.swift         # ディープリンクルーティング
│   ├── ViewController.swift        # メインUI
│   ├── Models/
│   │   ├── FCMTokenService.swift   # トークン登録
│   │   ├── EventQueue.swift        # ローカルイベント保存
│   │   └── PushEventUploader.swift # TDへのバッチアップロード
│   ├── Assets.xcassets
│   ├── Info.plist
│   └── GoogleService-Info.plist    # Firebase設定
├── NotificationService/             # リッチメディア用Extension
│   └── NotificationService.swift
├── MyApp.xcodeproj/
└── Podfile                          # 依存関係

1. 依存関係をインストール:

cd ios
pod install

2. Xcodeでワークスペースを開く:

open MyApp.xcworkspace

3. Firebaseを設定:

   • GoogleService-Info.plistをあなたのFirebase設定ファイルに置き換える
   • Bundle IDをFirebaseアプリと一致するように更新

4. Treasure Dataを設定:

   • PushEventUploader.swiftを開く
   • YOUR_TD_WRITE_KEYを実際の書き込み専用APIキーに置き換える
   • 必要に応じてTD_DATABASEとTD_TABLEを更新

5. ビルドして実行:

   • ターゲットデバイス/シミュレーターを選択
   • Cmd+Rを押してビルドと実行

1. XcodeでMyApp.xcodeprojを開く

2. Firebaseパッケージを追加:

   • File > Add Packages...
   • 入力: https://github.com/firebase/firebase-ios-sdk
   • バージョン12.7.0以降を選択
   • FirebaseMessagingとFirebaseAnalyticsを追加

3. 上記CocoaPodsの手順3-5に従う

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

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

1. テストペイロードファイルtest-notification.apnsを作成:

{
  "Simulator Target Bundle": "com.example.myapp",
  "aps": {
    "alert": {
      "title": "テスト通知",
      "body": "これはテストメッセージです"
    },
    "sound": "default",
    "badge": 1
  },
  "campaign_id": "test_campaign",
  "message_id": "test_001",
  "deeplink": "myapp://test",
  "image_url": "https://example.com/image.jpg"
}

2. シミュレーターでアプリを実行:

# シミュレーターを起動
xcrun simctl boot "iPhone 15"

# ビルドして実行
xcodebuild -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  build

3. テスト通知を送信:

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

4. 通知が表示され画像が読み込まれることを確認

1. USBケーブルでデバイスを接続

2. デバイスでDeveloper Modeを有効化:

   • 設定 > プライバシーとセキュリティ > Developer Mode

3. Xcodeからアプリをビルドしてインストール

4. XcodeコンソールでFCMトークンを確認:

FCM token: [your-token-here]

5. Firebase Consoleからテスト通知を送信:

   • Firebase Console > Cloud Messagingを開く
   • "Send your first message"をクリック
   • タイトルと本文を入力
   • "Send test message"をクリック
   • FCMトークンを貼り付け
   • "Test"をクリック

6. デバイスに通知が表示されることを確認

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

SELECT
  time,
  type,
  campaign_id,
  message_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 - 通知受信時
3. open - ユーザーが通知をタップ時
4. link_open または deeplink_open - 通知にリンクが含まれる場合

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

• 最小デプロイメントターゲットiOS 13.0のiOSプロジェクトを作成
• XcodeでPush Notificationsケイパビリティを追加
• Background Modesケイパビリティを追加（Remote notifications）
• Info.plistでディープリンク用のURLスキームを設定
• プロジェクトにFirebaseを追加（CocoaPodsまたはSPM）
• GoogleService-Info.plistをダウンロードして追加

• AppDelegateでFirebase初期化を実装
• UNUserNotificationCenterデリゲートを設定
• Firebase Messagingデリゲートを設定
• 通知パーミッションをリクエスト
• リモート通知に登録
• トークン管理用のFCMTokenServiceを実装
• UserDefaults永続化を使用したEventQueueを実装
• URLSessionを使用したPushEventUploaderを実装

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

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

• SceneDelegateでscene(_:openURLContexts:)を実装
• ディープリンクURLのスキームとパスを解析
• ディープリンクに基づいて適切な画面に遷移
• SafariまたはSFSafariViewControllerでWebリンクを処理
• ディープリンクの宛先を検証

• プレースホルダーTD_WRITE_KEYを実際のキーに置き換え
• APIキーを.gitignoreに追加
• ネットワーク障害のエラーハンドリングを実装
• 失敗したアップロードの再試行ロジックを実装
• デバッグ用のログを追加（本番環境では削除）

• シミュレーターで通知配信をテスト
• 実機で通知配信をテスト
• 通知内のリッチメディア（画像）をテスト
• ディープリンクナビゲーションをテスト
• Webリンク開封をテスト
• Treasure Dataにイベントが表示されることを確認
• バックグラウンドアプリ状態でテスト
• 強制終了アプリ状態でテスト

• CocoaPodsを使用する場合、.xcworkspace（.xcodeprojではなく）を開いていることを確認
• 依存関係が不足している場合はpod installを実行
• ビルドフォルダをクリーン: Product > Clean Build Folder (Cmd+Shift+K)

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

• TD_WRITE_KEYが正しいことを確認
• HTTP 200レスポンスのネットワークログを確認
• データベースとテーブル名が設定と一致することを確認
• EventQueueがイベントを永続化していることを確認（UserDefaultsを検査）

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

1. サンプルリポジトリをクローンして実装を確認
2. Mobile Push Setupガイドに従ってFirebaseを設定
3. iOSアプリにコンポーネントを実装
4. 通知配信とイベントトラッキングをテスト
5. Push Events Tableでイベントデータを確認
6. Engage Studioで最初のキャンペーンを作成

• Mobile Push Setup - FirebaseとAPNs設定
• Android Developer Guide - Android実装ガイド
• Push Events Table - イベントスキーマと分析クエリ
• Campaign Creation - Mobile Pushキャンペーンの作成