# Branch Metrics Import Integration

[Branch](https://branch.io/)は、主要ブランド向けのリンクインフラストラクチャで、モバイル広告キャンペーンのシームレスなトラッキングを可能にします。webhookを通じてBranchのモバイルイベントをTreasure Dataと統合することで、モバイルデータを直接Treasure Dataに取り込み、包括的な分析を行うことができます。この連携により、すべての関連するモバイルイベントがTreasure Dataにキャプチャされ、保存されることが保証されます。

## Branchトラッキングイベントの概要

BranchはAndroidおよびiOS SDKを通じたイベントトラッキングをサポートしており、以下のイベントタイプを自動的に収集します:

- Click
- Open
- Install
- Reinstall
- Impression
- Custom Events
- Content Events
- Lifecycle Events
- Subscription and In-App Purchase Events


これらのイベントは、BranchのWebhook機能とTreasure Data Ingest APIを使用してTreasure Dataに転送でき、Treasure Data CDP内でモバイルデータの価値を最大化することができます。

イベントの詳細については、[Branch Event Documentation](https://help.branch.io/developers-hub/docs/track-branch-events)を参照してください。

## イベントデータ構造

イベントの包括的なリスト、フィールド定義、データ型、およびイベントタイプ別のフィールド可用性については、[Branch Event Ontology](https://help.branch.io/developers-hub/docs/branch-event-ontology#full-list-of-fields)を参照してください。

## Branch ConsoleでのPostback連携の設定

Branch ConsoleでWebhook設定を行うには、以下の手順に従ってイベントがTreasure Dataにリアルタイムで転送されるようにします:

### Treasure Data Write-Only API Keyの生成

Treasure Dataでは、データインポート時の認証にWrite-Only API Keyが必要です。このキーを生成するには:

1. Treasure コンソールでMy Profileに移動します。
2. API Keyタブを選択します。
3. Write-Only API Keyを生成します。詳細については、[Generating API Keys](https://docs.treasuredata.com/smart/project-product-documentation/getting-your-api-keys)を参照してください。


### アプローチ1: ネイティブWebhook連携

BranchはTreasure Dataとのネイティブ連携をサポートしており、IMPRESSION、CLICK、OPEN、INSTALL、REINSTALL、USER_LIFECYCLE_EVENT、CONTENT_EVENT、COMMERCE_EVENT、CUSTOM_EVENTなどのイベントがBranchのWebhookとTreasure Data Postback APIを通じて直接送信されます。

- 設定するには、Branch ConsoleのData Feeds > Data Integration > Treasure Dataに移動します。
- Treasure Data Write-Only API Keyと宛先データベースを入力します。


このアプローチは現在、US地域のみでサポートされています。

### アプローチ2: カスタムWebhook連携

アプローチ1でカバーされていないイベント(例: ADD_TO_CARTイベント、またはTreasure DataインスタンスがEU01地域やその他の地域にある場合)については、カスタムWebhookを設定する必要があります。この連携により、パートナー連携と同じデータを収集できます。

#### 設定 - Webhook URL

WEBHOOK URLメニューでは、イベントの送信先URLを入力できます。このURLはFree Form Editオプションで記述できます。

- Webhook URLフィールドを使用して、BranchイベントをどこにDELIVERするかを指定します。Free Form Editオプションでカスタマイズします。
- Webhook URLフィールドを使用して、Branchイベントの送信先を指定します。Free Form Editオプションでカスタマイズできます。
- 適切なTreasure Dataリージョンのingestエンドポイントを選択してください:
  - USリージョン: https://in.treasuredata.com/postback/v3/event/<database_name>/<table_name>
  - EU01リージョン:  https://eu01.in.treasuredata.com/postback/v3/event/<database_name>/<table_name>
  - Tokyoリージョン: https://tokyo.in.treasuredata.com/postback/v3/event/<database_name>/<table_name>
  - Koreaリージョン: https://ap02.in.treasuredata.com/postback/v3/event/<database_name>/<table_name>
  - AP03リージョン: https://ap03.in.treasuredata.com/postback/v3/event/<database_name>/<table_name>
- *<database_name>*と*<table_name>*を、Treasure Data内で使用するデータベース名とテーブル名に置き換えてください。


詳細については、[Treasure Data Postback APIドキュメント](/apis/postback/quickstart)を参照してください。

#### 設定 - FILTERS

すべてのトリガーイベントにPOSTメソッドを使用します。

HEADERSセクションには、次のパラメータを含めてください:

| **Key** | **Value** |
|  --- | --- |
| Content-Type | application/json |
| X-TD-Write-Key | Your WRITE APIKEY |


Treasure DataはJSON形式のデータを期待します。必要に応じて、カスタムデータ構文にBranchのマクロ機能を使用することもできます。本番稼働前にイベントの取り込みをテストすることを推奨します。

## データ検証とテスト

データ取り込みを検証するには(例: iOS):

- Branchは[iOSサンプルコード](https://github.com/BranchMetrics/branch-ios-sdk-samples/tree/main)を提供しています。このサンプルコードをテストAPIキーと共に使用して、実機またはシミュレートされたiPhoneデバイスからイベントを送信できます。
- 送信されたイベントについて、Treasure DataのRecent Recordsセクションを確認してください。データは通常3〜5分以内に表示されます。
- Treasure Dataでクエリを作成してイベントを検証します。


## よくある質問

Q. テーブルの「time」カラムとは何ですか?
A. Treasure Dataは、受信イベントにtimeフィールドが含まれていない場合、UNIXタイムスタンプを自動的に追加します。このタイムスタンプは、Treasure Dataサーバーがイベントリクエストを受信した時刻を表します。

Q. Treasure DataとBranch間でユーザーをどのように紐付けできますか?
A. Treasure Dataでは、Branchのユーザートラッキングフィーチャーを使用して、CRM ID、メールアドレス、またはその他の識別子を含めることを推奨しています。これにより、Treasure DataとBranch間で統合されたID解決が可能になります。詳細については、[Branchユーザートラッキングドキュメント](https://help.branch.io/developers-hub/docs/ios-advanced-features#set-initialization-metadata)を参照してください。

Q. WebhookのためにIPホワイトリストを設定する必要がありますか?
A. いいえ、Treasure DataのPostbackエンドポイントにはIPホワイトリストは必要ありません。

Q. カラム内のJSONフィールドをどのように解析できますか?
A. Trinoを使用して、次のクエリ例でJSONデータを抽出できます:


```SQL
SELECT
  JSON_EXTRACT_SCALAR(JSON_PARSE(event_data), '$.currency') AS currency
FROM
  add_cart_live;
```