Android開発者ガイド
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Cursorに接続
CursorにMCPサーバーをインストール
VS Codeに接続
VS CodeにMCPサーバーをインストール

ベータ機能

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

概要

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

FCM連携: Firebase Cloud Messaging経由でプッシュ通知を受信
トークン管理: デバイストークンをTreasure Dataに登録および更新
通知表示: 画像、アクションボタン、ディープリンクを含む通知を表示
イベントトラッキング: Treasure Data SDKを使用してユーザーインタラクション(配信、開封、削除、リンク)をトラッキング
自動データアップロード: Treasure Data SDKがイベントのTreasure Dataへのアップロードを自動的に処理

サンプル実装が利用可能

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

Treasure Data Mobile Push - 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トークン更新を処理

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

2. Push Event Receiver

目的: 通知とのユーザーインタラクションを処理する

主な責務:

通知タップ(メインコンテンツ)を処理
アクションボタンタップ(Webリンク、ディープリンク)を処理
通知削除を処理
対応するイベント(open, dismiss, link_open, deeplink_open)をトラッキング
Chrome Custom TabsでWeb URLを開く
アプリ内でディープリンクを開く

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

3. FCM Token Service

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

主な責務:

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

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

4. Event Queue

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

主な責務:

SharedPreferencesにイベントを永続化
最大サイズ制限(1000イベント)でFIFOキューを実装
アップロード用のバッチドレインをサポート
キューオーバーフローを適切に処理

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

5. Push Event Uploader

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

主な責務:

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

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

6. MainActivity Integration

目的: 通知タップとディープリンクを処理する

主な責務:

通知タップインテントを受信
openイベントをトラッキング
ディープリンクに基づいて適切な画面に遷移
指定されたWeb URLを開く

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

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

アプリはFCM dataペイロードで以下の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ドキュメントを参照してください。

設定要件

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以降

依存関係の設定例:

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設定を構成します（このファイルはバージョン管理から除外してください）:

TD_WRITE_KEY=your_write_api_key_here
TD_DATABASE=mobile
TD_TABLE=push_events
TD_ENDPOINT=https://in.treasuredata.com

build.gradle.ktsでこれらのプロパティにアクセス:

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関連付け

プッシュ通知イベントを特定のユーザーとリンクするには:

ログインユーザー: すべてのイベントにuser_id(例: 顧客ID、メールハッシュ値)を含める
匿名ユーザー: イベントでuser_idにnullを渡す
ログイン時: user_idを含む新しいtoken_registerイベントを送信してデバイスを関連付ける

Treasure Dataは同じfcm_tokenからのすべての以前のイベントをユーザーにリンクします。

テスト

通知配信のテスト

Google Play Servicesを搭載したデバイスでアプリを実行
logcatでFCMトークンを確認
Firebase Consoleからテスト通知を送信
デバイスに通知が表示されることを確認

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

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

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

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

APIキー:
- TD_WRITE_KEYをソース管理にコミットしない
- BuildConfigまたは環境変数を使用
- 書き込み専用キーを使用(マスターキーではない)
ディープリンク:
- ディープリンクの宛先を常に検証
- 機密性の高いアクションにURL許可リストを実装
- ナビゲーション前にパラメータをサニタイズ
イベントデータ:
- イベントペイロードにPIIを含めない
- 可能な限りハッシュ化または匿名化されたユーザーIDを使用
ネットワークセキュリティ:
- 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

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

インラインドキュメント付きの完全なソースコード
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) 以降

セットアップ手順

リポジトリをクローン:

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

Android Studioでプロジェクトを開く
Firebaseを設定:
- google-services.jsonを自分のFirebase設定ファイルに置き換える
- app/build.gradle.ktsのapplicationIdをFirebaseアプリと一致するように更新
Treasure Dataを設定:
- local.properties.exampleをlocal.propertiesにコピー
- local.propertiesをTreasure Data設定で編集:
```
TD_WRITE_KEY=your_write_api_key_here
TD_DATABASE=mobile
TD_TABLE=push_events
TD_ENDPOINT=https://in.treasuredata.com
```
- 重要: local.propertiesをバージョン管理にコミットしないでください
Gradleを同期してビルド:

./gradlew assembleDebug

テストワークフロー

事前準備

Androidアプリが登録されたFirebaseプロジェクト
app/ディレクトリに配置されたgoogle-services.json
作成されたTreasure Dataデータベースとテーブル
Google Play Services搭載のエミュレーターまたは実機

エミュレーターでのテスト

エミュレーターを起動:

emulator -avd Pixel_5_API_34

アプリをインストールして実行:

./gradlew installDebug
adb shell am start -n com.treasuredata.pushsample/.MainActivity

FCMトークンをログで確認:

adb logcat | grep -E "FCM token|FCMService"

Firebase Consoleからテスト通知を送信して確認

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

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"エラー

ls app/google-services.json
./gradlew --refresh-dependencies

WorkManagerジョブが実行されない

# 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

次のステップ

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

概要

必要要件

アーキテクチャ概要

実装コンポーネント

1. Firebase Messaging Service

2. Push Event Receiver

3. FCM Token Service

4. Event Queue

5. Push Event Uploader

6. MainActivity Integration

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

イベントトラッキング

設定要件

AndroidManifest.xml

build.gradle.kts

local.properties

通知パーミッション

ユーザーID関連付け

テスト

通知配信のテスト

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

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

トラブルシューティング

通知が受信されない

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

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

サンプルリポジトリ

実装ガイド

プロジェクト構造

ビルドと実行手順

事前準備

セットアップ手順

テストワークフロー

事前準備

エミュレーターでのテスト

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

実装チェックリスト

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

フェーズ2: Manifest設定

フェーズ3: コアコンポーネント

フェーズ4: 通知表示

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

フェーズ6: テスト

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

"google-services.json is missing"エラー

WorkManagerジョブが実行されない

通知が表示されない

イベントがTreasure Dataにアップロードされない

次のステップ

関連ドキュメント

Was this helpful?