# Android開発者ガイド ベータ機能 Mobile Pushは現在ベータ版です。機能、API、実装の詳細は正式リリース前に変更される可能性があります。 ## 概要 このガイドでは、Treasure Data Android SDKを使用してAndroidアプリにEngage Studio Mobile Push通知を統合するための実装要件を提供します。開発チームは次の機能を実装する必要があります: 1. **FCM連携**: Firebase Cloud Messaging経由でプッシュ通知を受信 2. **トークン管理**: デバイストークンをTreasure Dataに登録および更新 3. **通知表示**: 画像、アクションボタン、ディープリンクを含む通知を表示 4. **イベントトラッキング**: Treasure Data SDKを使用してユーザーインタラクション(配信、開封、削除、リンク)をトラッキング 5. **自動データアップロード**: Treasure Data SDKがイベントのTreasure Dataへのアップロードを自動的に処理 サンプル実装が利用可能 本番環境対応の完全なサンプルアプリケーションがGitHubで公開されています: **[Treasure Data Mobile Push - Androidサンプル](https://github.com/treasure-data/engage-push-notification-sample/tree/main/android)** サンプルに含まれる内容: - 完全なFirebase Messaging Service実装 - Treasure Data SDKを使用したイベントトラッキング - ディープリンクとWebリンク処理 - アクションボタンと画像を含む通知UI リポジトリをクローンして実装の参考にしてください。 ## 必要要件 | コンポーネント | 要件 | | --- | --- | | **最小Androidバージョン** | Android 8.0 (API 26) 以降 | | **言語** | Kotlin (推奨) または Java | | **必要な依存関係** | - Firebase Messaging SDK (Firebase BoM 34.7.0+経由) - Treasure Data Android SDK 1.1.0+ - WorkManager 2.9.1+ (バックグラウンドタスク用) - Chrome Custom Tabs 1.8.0+ (Webリンク処理用) | | **トラッキングイベント** | `delivery`, `open`, `dismiss`, `deeplink_open`, `link_open`, `token_register` | ## アーキテクチャ概要 ``` ┌─────────────────────┐ │ Engage Studio │ │ Campaign │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Firebase Cloud │ │ Messaging (FCM) │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Your Android App │ ├─────────────────────┤ │ MyFirebaseMessaging │ ← 通知を受信 │ Service │ ├─────────────────────┤ │ PushEventReceiver │ ← ユーザーアクションを処理 ├─────────────────────┤ │ Treasure Data SDK │ ← イベントをトラッキングしアップロード └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Treasure Data │ │ Ingest API │ └─────────────────────┘ ``` ## 実装コンポーネント Androidアプリは以下のコンポーネントを実装する必要があります: ### 1. Firebase Messaging Service **目的:** FCMからプッシュ通知を受信し表示する **主な責務:** - 受信FCMメッセージをリッスン - 通知ペイロード(タイトル、本文、画像、リンク)を抽出 - アクションボタン付きの通知を表示 - 通知受信時に`delivery`イベントをトラッキング - FCMトークン更新を処理 **参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/android)の`MyFirebaseMessagingService.kt`を参照してください ### 2. Push Event Receiver **目的:** 通知とのユーザーインタラクションを処理する **主な責務:** - 通知タップ(メインコンテンツ)を処理 - アクションボタンタップ(Webリンク、ディープリンク)を処理 - 通知削除を処理 - 対応するイベント(`open`, `dismiss`, `link_open`, `deeplink_open`)をトラッキング - Chrome Custom TabsでWeb URLを開く - アプリ内でディープリンクを開く **参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/android)の`PushEventReceiver.kt`を参照してください ### 3. FCM Token Service **目的:** Treasure Dataとのデバイストークン登録を管理する **主な責務:** - 現在のFCMトークンを取得 - アプリ起動時にTreasure Dataにトークンを登録 - FCMによるトークン更新時に再登録 - ユーザーログイン時にトークンとユーザーIDを関連付け - `token_register`イベントをトラッキング **参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/android)の`FcmTokenService.kt`を参照してください ### 4. Event Queue **目的:** Treasure Dataにアップロードする前にイベントをローカルに保存する **主な責務:** - SharedPreferencesにイベントを永続化 - 最大サイズ制限(1000イベント)でFIFOキューを実装 - アップロード用のバッチドレインをサポート - キューオーバーフローを適切に処理 **参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/android)の`EventQueue.kt`を参照してください ### 5. Push Event Uploader **目的:** Treasure Data Ingest APIにイベントをアップロードする **主な責務:** - イベントをバッチアップロード(リクエストあたり最大500件) - 信頼性の高いバックグラウンド実行にWorkManagerを使用 - 指数バックオフを使用した再試行ロジックを実装 - Treasure Dataポストバック APIにイベントを送信 - アップロード失敗を適切に処理 **参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/android)の`PushEventUploader.kt`を参照してください ### 6. MainActivity Integration **目的:** 通知タップとディープリンクを処理する **主な責務:** - 通知タップインテントを受信 - `open`イベントをトラッキング - ディープリンクに基づいて適切な画面に遷移 - 指定されたWeb URLを開く **参照:** [サンプルリポジトリ](https://github.com/treasure-data/engage-push-notification-sample/tree/main/android)の`MainActivity.kt`を参照してください ## データペイロードスキーマ アプリはFCM `data`ペイロードで以下のJSON構造を受信します: ```json { "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" } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `td_campaign_id` | String | Yes | Engage Studioからの一意のキャンペーン識別子 | | `title` | String | Yes | 通知タイトル | | `body` | String | Yes | 通知本文テキスト | | `image_url` | String | No | リッチ通知画像のURL | | `link` | String | No | ブラウザで開くWeb URL | ## イベントトラッキング アプリは以下のイベントをトラッキングしTreasure Dataに送信する必要があります: | イベントタイプ | トラッキングタイミング | 必須フィールド | | --- | --- | --- | | `delivery` | 通知が受信され表示されたとき | `campaign_id`, `message_id`, `platform`, `time` | | `open` | ユーザーが通知をタップしたとき | `campaign_id`, `message_id`, `platform`, `time`, `user_id` | | `dismiss` | ユーザーが通知を削除したとき | `campaign_id`, `message_id`, `platform`, `time`, `user_id` | | `link_open` | ユーザーがWebリンクをタップしたとき | `campaign_id`, `message_id`, `platform`, `time`, `user_id`, `value` (URL) | | `deeplink_open` | ユーザーがディープリンクをタップしたとき | `campaign_id`, `message_id`, `platform`, `time`, `user_id`, `value` (URI) | | `token_register` | FCMトークンが取得または更新されたとき | `fcm_token`, `platform`, `time`, `user_id` (ログイン時) | すべてのイベントはTreasure Data Ingest APIエンドポイントに送信する必要があります: ``` POST https://in.treasuredata.com/postback/v3/event/{database}/{table} Header: X-TD-Write-Key: YOUR_WRITE_KEY ``` 完全なスキーマ詳細については[Push Events Table](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/push-events-table)ドキュメントを参照してください。 ## 設定要件 ### AndroidManifest.xml アプリで以下を宣言する必要があります: - `INTERNET`パーミッション - `POST_NOTIFICATIONS`パーミッション(Android 13+) - Firebase Messaging Service - 通知アクション用のBroadcast Receiver - ディープリンクのインテントフィルター ### build.gradle.kts 必要な依存関係: - Firebase BoM: `34.7.0`以降 - Firebase Messaging (バージョンはBoMで管理) - Treasure Data Android SDK: `1.1.0`以降 - WorkManager: `2.9.1`以降 - Chrome Custom Tabs: `1.8.0`以降 依存関係の設定例: ```kotlin dependencies { // Firebase implementation(platform("com.google.firebase:firebase-bom:34.7.0")) implementation("com.google.firebase:firebase-messaging") implementation("com.google.firebase:firebase-analytics") // Treasure Data SDK implementation("com.treasuredata:td-android-sdk:1.1.0") // バックグラウンドタスク implementation("androidx.work:work-runtime-ktx:2.9.1") // Webリンク implementation("androidx.browser:browser:1.8.0") } ``` ### local.properties `local.properties`でTreasure Data設定を構成します（このファイルはバージョン管理から除外してください）: ```properties TD_WRITE_KEY=your_write_api_key_here TD_DATABASE=mobile TD_TABLE=push_events TD_ENDPOINT=https://in.treasuredata.com ``` `build.gradle.kts`でこれらのプロパティにアクセス: ```kotlin val localProperties = Properties() localProperties.load(FileInputStream(rootProject.file("local.properties"))) android { defaultConfig { buildConfigField("String", "TD_WRITE_KEY", "\"${localProperties["TD_WRITE_KEY"]}\"") buildConfigField("String", "TD_DATABASE", "\"${localProperties["TD_DATABASE"]}\"") buildConfigField("String", "TD_TABLE", "\"${localProperties["TD_TABLE"]}\"") buildConfigField("String", "TD_ENDPOINT", "\"${localProperties["TD_ENDPOINT"]}\"") } } ``` ### 通知パーミッション Android 13+ (API 33)の場合、ランタイムで`POST_NOTIFICATIONS`パーミッションをリクエストします。 ## ユーザーID関連付け プッシュ通知イベントを特定のユーザーとリンクするには: 1. **ログインユーザー**: すべてのイベントに`user_id`(例: 顧客ID、メールハッシュ値)を含める 2. **匿名ユーザー**: イベントで`user_id`に`null`を渡す 3. **ログイン時**: `user_id`を含む新しい`token_register`イベントを送信してデバイスを関連付ける Treasure Dataは同じ`fcm_token`からのすべての以前のイベントをユーザーにリンクします。 ## テスト ### 通知配信のテスト 1. Google Play Servicesを搭載したデバイスでアプリを実行 2. logcatでFCMトークンを確認 3. Firebase Consoleからテスト通知を送信 4. デバイスに通知が表示されることを確認 ### イベントトラッキングの確認 Treasure Dataでクエリを実行してイベントがログに記録されていることを確認: ```sql SELECT time, type, campaign_id, message_id, platform FROM mobile.push_events WHERE platform = 'android' ORDER BY time DESC LIMIT 100 ``` ## セキュリティのベストプラクティス 1. **APIキー**: - `TD_WRITE_KEY`をソース管理にコミットしない - BuildConfigまたは環境変数を使用 - 書き込み専用キーを使用(マスターキーではない) 2. **ディープリンク**: - ディープリンクの宛先を常に検証 - 機密性の高いアクションにURL許可リストを実装 - ナビゲーション前にパラメータをサニタイズ 3. **イベントデータ**: - イベントペイロードにPIIを含めない - 可能な限りハッシュ化または匿名化されたユーザーIDを使用 4. **ネットワークセキュリティ**: - APIエンドポイントには常にHTTPSを使用 - 本番環境では証明書ピン留めを検討 ## トラブルシューティング ### 通知が受信されない - FCMトークンが生成されアップロードされたことを確認 - Google Play Servicesがインストールされ更新されていることを確認 - 通知パーミッションを確認(Android 13+) - `google-services.json`が`app/`ディレクトリにあることを確認 ### イベントがTreasure Dataに表示されない - `local.properties`の`TD_WRITE_KEY`が正しいことを確認 - `TD_ENDPOINT`がリージョンと一致することを確認 - Treasure Dataにデータベースとテーブルが存在することを確認 - `MyApplication`でTreasure Data SDKが適切に初期化されていることを確認 - デバッグログを有効化してSDKの動作を確認: `TreasureData.enableLogging()` ### ディープリンクが機能しない - AndroidManifest.xmlのインテントフィルターを確認 - 次のコマンドでテスト: `adb shell am start -W -a android.intent.action.VIEW -d "myapp://test"` - URI形式が登録されたスキームと一致することを確認 ## サンプルリポジトリ 完全な本番環境対応の実装: **[https://github.com/treasure-data/engage-push-notification-sample/tree/main/android](https://github.com/treasure-data/engage-push-notification-sample/tree/main/android)** リポジトリに含まれる内容: - インラインドキュメント付きの完全なソースコード - Treasure Data SDK連携を含むGradle設定 - AndroidManifest.xmlセットアップ - テスト手順 - セキュリティのベストプラクティス - 設定ファイルの例 ## 実装ガイド このセクションでは、サンプルアプリケーションのビルドとテストの詳細な手順を提供します。 ### プロジェクト構造 サンプルリポジトリは以下のディレクトリ構造に従います: ``` android/ ├── app/ │ ├── src/main/ │ │ ├── java/com/treasuredata/pushsample/ │ │ │ ├── MainActivity.kt # ディープリンクと通知処理 │ │ │ ├── MyApplication.kt # アプリ初期化 │ │ │ └── fcm/ │ │ │ ├── MyFirebaseMessagingService.kt # FCMメッセージ受信 │ │ │ ├── PushEventReceiver.kt # 通知アクション処理 │ │ │ ├── PushAction.kt # アクション定数 │ │ │ ├── FcmTokenService.kt # トークン管理 │ │ │ ├── EventQueue.kt # ローカルイベント保存 │ │ │ └── PushEventUploader.kt # TDへのバッチアップロード │ │ ├── res/ │ │ └── AndroidManifest.xml │ ├── build.gradle.kts │ └── google-services.json # Firebase設定 ├── gradle/ ├── build.gradle.kts └── settings.gradle.kts ``` ### ビルドと実行手順 #### 事前準備 - Android Studio Hedgehog (2023.1.1) 以降 - JDK 17 以降 - Android SDK 26 (Android 8.0) 以降 #### セットアップ手順 1. リポジトリをクローン: ```bash git clone https://github.com/treasure-data/engage-push-notification-sample.git cd engage-push-notification-sample/android ``` 1. Android Studioでプロジェクトを開く 2. Firebaseを設定: - `google-services.json`を自分のFirebase設定ファイルに置き換える - `app/build.gradle.kts`の`applicationId`をFirebaseアプリと一致するように更新 3. Treasure Dataを設定: - `local.properties.example`を`local.properties`にコピー - `local.properties`をTreasure Data設定で編集: ```properties TD_WRITE_KEY=your_write_api_key_here TD_DATABASE=mobile TD_TABLE=push_events TD_ENDPOINT=https://in.treasuredata.com ``` - **重要:** `local.properties`をバージョン管理にコミットしないでください 4. Gradleを同期してビルド: ```bash ./gradlew assembleDebug ``` ### テストワークフロー #### 事前準備 - [ ] Androidアプリが登録されたFirebaseプロジェクト - [ ] `app/`ディレクトリに配置された`google-services.json` - [ ] 作成されたTreasure Dataデータベースとテーブル - [ ] Google Play Services搭載のエミュレーターまたは実機 #### エミュレーターでのテスト 1. エミュレーターを起動: ```bash emulator -avd Pixel_5_API_34 ``` 1. アプリをインストールして実行: ```bash ./gradlew installDebug adb shell am start -n com.treasuredata.pushsample/.MainActivity ``` 1. FCMトークンをログで確認: ```bash adb logcat | grep -E "FCM token|FCMService" ``` 1. Firebase Consoleからテスト通知を送信して確認 #### イベントトラッキングの確認 ```sql SELECT time, type, campaign_id, message_id, platform, user_id FROM mobile.push_events WHERE platform = 'android' AND time > td_time_add(now(), '-1h', 'JST') ORDER BY time DESC LIMIT 20 ``` ### 実装チェックリスト #### フェーズ1: プロジェクトセットアップ - [ ] 最小SDK 26のAndroidプロジェクトを作成 - [ ] `build.gradle.kts`にFirebase依存関係を追加 - [ ] WorkManager、OkHttp、Chrome Custom Tabs依存関係を追加 - [ ] `google-services.json`をダウンロードして`app/`に配置 #### フェーズ2: Manifest設定 - [ ] `INTERNET`パーミッションを宣言 - [ ] `POST_NOTIFICATIONS`パーミッションを宣言（Android 13+） - [ ] `MyFirebaseMessagingService`を登録 - [ ] `PushEventReceiver` BroadcastReceiverを登録 - [ ] MainActivityにディープリンク用のインテントフィルターを追加 #### フェーズ3: コアコンポーネント - [ ] `MyApplication`クラスでFirebase初期化 - [ ] `MyFirebaseMessagingService`を実装 - [ ] `FcmTokenService`でトークン管理を実装 - [ ] SharedPreferences永続化を使用した`EventQueue`を実装 - [ ] WorkManager + OkHttpを使用した`PushEventUploader`を実装 #### フェーズ4: 通知表示 - [ ] 通知チャネルを作成（Android 8+） - [ ] タイトル、本文、アイコン付きの通知をビルド - [ ] 画像サポートを追加（`image_url`が存在する場合） - [ ] NotificationManagerで通知を表示 #### フェーズ5: イベントトラッキング - [ ] `onMessageReceived`で`delivery`イベントを追跡 - [ ] 通知タップ時に`open`イベントを追跡 - [ ] 通知削除時に`dismiss`イベントを追跡 - [ ] Webリンクタップ時に`link_open`イベントを追跡 - [ ] ディープリンクタップ時に`deeplink_open`イベントを追跡 #### フェーズ6: テスト - [ ] エミュレーターで通知配信をテスト - [ ] 実機で通知配信をテスト - [ ] 通知画像をテスト - [ ] ディープリンクナビゲーションをテスト - [ ] Chrome Custom TabsでWebリンク開封をテスト - [ ] Treasure Dataにイベントが表示されることを確認 ### ビルドトラブルシューティング #### "google-services.json is missing"エラー ```bash ls app/google-services.json ./gradlew --refresh-dependencies ``` #### WorkManagerジョブが実行されない ```bash # WorkManagerステータスを確認 adb shell dumpsys jobscheduler | grep PushEventUpload ``` #### 通知が表示されない - Google Play Servicesがインストールされていることを確認 - 通知パーミッションが許可されていることを確認（Android 13+） - logcatでFCMエラーを確認: `adb logcat | grep FCM` #### イベントがTreasure Dataにアップロードされない - `TD_WRITE_KEY`が正しいことを確認 - ネットワーク接続を確認 - エンドポイントURLがリージョンと一致することを確認 - WorkManagerログを確認: `adb logcat | grep WorkManager` ## 次のステップ 1. **サンプルリポジトリをクローン**して実装を確認 2. [Mobile Push Setup](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/mobile-push-setup)ガイドに従って**Firebaseを設定** 3. Androidアプリに**コンポーネントを実装** 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とTreasure Data設定 - [iOS Developer Guide](/ja/products/marketing-cloud/engage-studio/channels/mobile-push/developer-guide-ios) - iOS実装ガイド - [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キャンペーンの作成