Gravity Engine 連携
サードパーティからのコールバックにより、プロジェクトのデータ量が増えます。選択したイベントが既存の計測と重複しないか確認してください。
概要
インターフェースの概要
| API | タイプ | 粒度 | アトリビューション | コスト | 収益 | インプレッション | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|
| リアルタイムAPI | コールバック | ユーザーレベル | ✅ | ✅ | ✅ | ✅ |
Gravity Engine は、イベントのバッチ、ユーザープロパティ、アトリビューションマクロのパラメーターを JSON 形式で POST します。ThinkingData はプロジェクト設定に従って、イベントデータとユーザープロパティ操作に変換します。
連携前に ユーザー識別ルール を読み、#distinct_id と #account_id の用途を確認してください。コールバック仕様は Gravity Engine 公式ドキュメント を参照してください。
統合の流れ
- ThinkingData SDK を導入して初期化し、ゲストID を取得します。Gravity Engine SDK を導入し、ThinkingData の識別子を Gravity Engine のユーザープロパティに同期します。
- ThinkingData で gravityengine 連携を設定します。ユーザー識別フィールド、イベント送信、ユーザープロパティのマッピングを設定し、プロジェクトのコールバック URL を取得します。
- Gravity Engine の管理画面でイベントコールバックを有効にします。必要なイベントを選択し、POST URL と広告アトリビューション用のマクロパラメーターを設定します。
- テストユーザーでイベントを発生させます。ThinkingData でイベント名、時刻、ユーザーとの紐付け、ユーザープロパティを確認してから、本番トラフィックを有効にします。
1. クライアントSDKの設定
1.1 Gravity Engine SDK と ThinkingData SDK の導入
対象プラットフォームの SDK を選択して初期化します。Gravity Engine クライアント SDK ドキュメント と ThinkingData SDK 導入ガイド を参照してください。メソッドのシグネチャは SDK のバージョンによって異なります。識別子の同期手順は以下のとおりです。
1.2 ユーザー識別子の同期
- ThinkingData SDK を初期化してゲストID を取得します。
- Gravity Engine SDK の初期化時に、ThinkingData のゲストID と、判明している場合はアカウント ID を渡します。Gravity Engine は ta_distinct_id と ta_account_id に保存します。
- ログインまたはキャラクターのログイン後に ThinkingData SDK の login を呼び出し、Gravity Engine のユーザープロパティ API で ta_account_id を更新します。アカウント切り替え時も両方の識別子を同期します。
- テストコールバックを送信し、user_properties に以下のフィールドがあることを確認します。イベントの properties にだけ識別子を入れても連携できません。
{
"user_properties": {
"ta_distinct_id": "ta-test-distinct-id",
"ta_account_id": "ta-test-account-id"
}
}
Gravity Engine は ta_distinct_id を送信し、利用できる場合はアカウント ID も送信します。変換には少なくとも 1 つの有効な識別子が必要です。ペイロードの client_id は Gravity Engine の識別子であり、ThinkingData のゲストID の代わりにはなりません。
2. プランの設定
対象環境のサードパーティ連携で Gravity Engine を選択します。プラットフォーム識別子は gravityengine です。以下は参照テンプレートに対応する設定画面です。
2.1 ユーザー識別フィールド
| ThinkingData の識別子 | 推奨フィールド | 取得ルール |
|---|---|---|
| アカウント ID(#account_id) | user_properties.ta_account_id | 取り込み設定 → ユーザー識別フィールド → アカウント ID で指定したペイロードのパスを優先します。値が空の場合はこのフィールドにフォールバックします。 |
| ゲストID(#distinct_id) | user_properties.ta_distinct_id | 取り込み設定 → ユーザー識別フィールド → ゲストID で指定したペイロードのパスを優先します。値が空の場合はこのフィールドにフォールバックします。 |
2 つの識別子は個別に取得し、個別にフォールバックします。両方が空の場合はイベントもユーザー操作も生成されません。イベントプロパティの $ta_account_id、$ta_distinct_id、client_id で取得元が上書きされることはありません。
2.2 イベントデータの格納設定
イベントテーブルへの取り込みを有効にすると、有効な名前とミリ秒タイムスタンプを持つ events[] の各オブジェクトからイベントが 1 件生成されます。オブジェクト以外の項目、名前がない項目、時刻が無効な項目はスキップされ、有効な項目には影響しません。重複やデータ量の増加を抑えるため、必要なイベントだけを選択してください。
デフォルトでは events[].event の先頭の $ を取り除き、gravity_ を付けます。イベント名のマッピングは「2.4 連携設定」で指定できます。
2.3 ユーザープロパティの格納設定
AE はデフォルトで Gravity Engine のアトリビューション値を、以下の標準化されたユーザープロパティに書き込みます。
| Gravity Engine フィールド | 標準化フィールド | 説明 |
|---|---|---|
| callback_params.channel | te_ads_object.media_source | メディアチャンネル |
| callback_params.campaign_name | te_ads_object.campaign_name | 広告キャンペーン名 |
| callback_params.ad_name | te_ads_object.ad_name | 広告名 |
| callback_params.ad_id | te_ads_object.ad_id | 広告ID |
変更が必要な場合は、「設定ルール」をクリックして、下図のような格納ルールの設定ページに移動します
特定のイベントからのみ書き込むには、「すべてのイベントを含める」をオフにして、ソースイベント名を指定します。AE は指定したコールバックイベントからのみ値を取得します。デフォルトの user_setOnce は最初の値を保持します。
ユーザープロパティの格納を無効にしたい場合は、すべてのルールを停止します:
2.4 統合構成
連携設定でイベント名のマッピングを指定できます。
2.5 ターミナルアドレス
POST https://<ThinkingData-受信ドメイン>/callback/integration/gravityengine/<ThinkingData-プロジェクト-APPID>
Content-Type: application/json
Gravity Engine のコールバック URL には、確認済みの公開受信ドメインと対象プロジェクトの APPID を使用します。パスの APPID は ThinkingData のプロジェクトを指定し、ペイロードの app_id は Gravity Engine のアプリを識別します。APPID によるプロジェクトの紐付けは強力な認証にはなりません。
3. Gravity Engine でのコールバック設定
3.1 イベントコールバックの設定
Gravity Engine のアプリ管理画面でイベントコールバック設定を開き、有効にして以下のパラメーターを入力します。
3.2 広告アトリビューションマクロの設定
Gravity Engine の管理画面で、以下の小文字の callback_params キーに対応するマクロを設定します。マクロの定義は Gravity Engine のアトリビューションコールバックドキュメント を参照してください。ThinkingData は展開後の値を読み取り、マクロの展開や欠落した広告情報の検索は行いません。
| コールバックパラメーター | Gravity Engine マクロ | 意味 |
|---|---|---|
| advertiser_id | __ADVERTISER_ID__ | 広告主アカウント ID |
| campaign_id | __CAMPAIGN_ID__ | 広告キャンペーンID |
| campaign_name | __CAMPAIGN_NAME__ | 広告キャンペーン名 |
| ad_id | __AD_ID__ | Gravity Engine 広告 ID |
| ad_name | __AD_NAME__ | Gravity Engine 広告名 |
| creative_id | __CREATIVE_ID__ | Gravity Engine クリエイティブ ID |
| creative_name | __CREATIVE_NAME__ | Gravity Engine クリエイティブ名 |
| ad_platform | __AD_PLATFORM__ | メディアプラットフォーム |
| csite | __CSITE__ | 広告掲載枠 |
| os_type | __OS_TYPE__ | デバイスタイプ |
例えば campaign_id に __CAMPAIGN_ID__ を設定すると、リクエストに callback_params.campaign_id="テストキャンペーンID" が含まれます。マクロが未設定、または有効な値を返さない場合、対応するフィールドは生成されません。$ のないキーも自動では送信されません。
イベントとユーザーのマクロパラメーターには同じ規則が適用されます。プラットフォーム別のイベントプロパティは Gravity Engine の連携資料の添付を参照してください。ミニプログラムの $app_id は、ペイロードルートの Gravity Engine アプリの app_id とは別に扱います。
3.3 コールバックデータの例
サンプル ID と過去のタイムスタンプは構造を示すためのものです。連携テストには実際のテストユーザー、現在のイベント時刻、Gravity Engine が生成した署名を使用してください。user_properties は今回の連携で取り決めたフィールドです。
{
"app_id": "gravity-app-id",
"client_id": "gravity-client-id",
"sign": "<Gravity Engine が生成した署名>",
"events": [
{
"event": "$PayEvent",
"time": 1779439377000,
"properties": {
"$os": "iOS",
"$model": "iPhone 12",
"$country": "China",
"$pay_amount": 600,
"$pay_type": "CNY"
}
}
],
"callback_params": {
"channel": "campaign-a",
"advertiser_id": "ad-account-1",
"campaign_id": "campaign-1",
"campaign_name": "テストキャンペーン",
"ad_id": "group-1",
"creative_id": "creative-1",
"ad_platform": "bytedance",
"os_type": "ios"
},
"user_properties": {
"ta_distinct_id": "ta-test-distinct-id",
"ta_account_id": "ta-test-account-id",
"$ad_count": 1
}
}
| フィールド | タイプ | 説明 |
|---|---|---|
| app_id、client_id | string | Gravity Engine のアプリとクライアントの識別子です。ThinkingData のプロジェクトやユーザーの識別子の代わりにはなりません。 |
| events | array | event、time、properties を含むイベントのバッチです。イベント出力を制御し、ユーザールールの実行には影響しません。 |
| events[].time | number | ミリ秒単位の正の整数 Unix タイムスタンプです。整数を表す文字列も使用できます。桁数から単位を推定しません。 |
| events[].properties | object | 現在のイベントのプロパティです。 |
| callback_params | object | 展開後のマクロパラメーターとカスタムパラメーターです。 |
| user_properties | object | ThinkingData の識別子とマッピングに使用するユーザープロパティの値です。 |
4. データの格納
4.1 イベントデータの取り込みルール
| 項目 | ルール |
|---|---|
| イベント名 | 先頭の $ を 1 つ取り除き、サードパーティの命名規則に従って正規化し、gravity_ を付けます。例として $PayEvent は gravity_PayEvent になります。元の名前に有効な event_mapping がある場合は正規化したマッピング値を使用し、プレフィックスは追加しません。 |
| イベント時間 | events[].time のミリ秒タイムスタンプをサービスのローカル時刻に変換して #time に書き込み、時差を時間単位で properties の #zone_offset に書き込みます。無効な時刻を現在時刻で補完しません。 |
| イベントプロパティ | callback_params、現在のイベントの properties の順でマージします。名前のマッピング後はイベントプロパティが優先されます。同じ取得元では、明示的なプロパティが $ エイリアスより優先されます。例えば #os は $os より、amount は $amount より優先されます。 |
| ルートフィールド | app_id と client_id が存在し null でない場合、型を保持して properties.gravity_app_id と properties.gravity_client_id に書き込み、同名の値を上書きします。空文字列は保持します。未指定または null の場合、値の追加やマージ済みの同名プロパティの削除は行いません。 |
| IP とデータソース | マージ後の $ip または #ip が有効な文字列の場合、イベントルートの #ip に書き込みます。コールバックサーバーの IP で補完しません。#data_source_detail は GravityEngine 固定で、#zone_offset はサービスが計算し、入力で上書きできません。 |
| その他のフィールド | sign、user_properties 全体、events は自動で展開されません。通常のプロパティ名に gravity_ は付きません。数値、真偽値、配列、オブジェクトは元の JSON 型を保持します。 |
例では $PayEvent を pay_event にマッピングします。マッピングがない場合は gravity_PayEvent になります。Asia/Shanghai では 1779439377000 は 2026-05-22 16:42:57.000 に相当し、#zone_offset=8 です。他の環境ではサービスのタイムゾーンに従います。
4.2 イベントのプリセットプロパティのマッピング
以下は従来の Gravity Engine 連携の 38 項目のマッピングです。値は callback_params と現在のイベントプロパティから取得し、デフォルト値は追加しません。#ip はイベントルートに、それ以外は properties に書き込みます。
| Gravity Engine のソースフィールド | ThinkingData のターゲットフィールド | 説明 |
|---|---|---|
| $ip | #ip | イベントルートに書き込みます。入力は文字列である必要があります。 |
| $country | #country | 国 |
| $province | #province | 都道府県・州 |
| $city | #city | 市区町村 |
| $os | #os | OS |
| $os_version | #os_version | OS バージョン |
| $manufacturer | #manufacturer | メーカー |
| $model | #device_model | デバイスモデル。既定のターゲット名を使用します。 |
| $screen_width | #screen_width | 画面幅 |
| $screen_height | #screen_height | 画面の高さ |
| $app_version | #app_version | アプリバージョン |
| $carrier | #carrier | 通信事業者 |
| $network_type | #network_type | ネットワークタイプ |
| $device_id | #device_id | デバイス識別子 |
| $lib | #lib | SDK 識別子 |
| $lib_version | #lib_version | SDK バージョン |
| $browser | #browser | ブラウザー |
| $browser_version | #browser_version | ブラウザーバージョン |
| $scene | #scene | シーン値 |
| $system_language | #system_language | システム言語 |
| $bundle_id | #bundle_id | アプリのバンドル ID |
| $duration | #duration | 経過時間。秒単位と数値型を保持します。 |
| $app_crashed_reason | #app_crashed_reason | クラッシュの原因 |
| $background_duration | #background_duration | バックグラウンド時間。元の値を保持します。 |
| $element_content | #element_content | 要素の内容 |
| $element_id | #element_id | 要素 ID |
| $element_position | #element_position | 要素の位置 |
| $element_selector | #element_selector | 要素セレクター |
| $element_type | #element_type | 要素タイプ |
| $resume_from_background | #resume_from_background | バックグラウンドからの復帰 |
| $scene_name | #scene_name | シーン名 |
| $scene_path | #scene_path | シーンパス |
| $screen_name | #screen_name | ページ名または画面名 |
| $share_depth | #share_depth | 共有の深さ |
| $start_reason | #start_reason | 起動理由 |
| $title | #title | ページタイトル |
| $url | #url | ページ URL |
| $url_path | #url_path | URL パス |
表にない $xxx は先頭の $ を 1 つ取り除き、正規化します。例は $pay_amount → pay_amount、$brand → brand です。単位が定義されていない $timezone_offset は timezone_offset に、$event_duration は event_duration になります。$user_id、$account_id、$distinct_id、$event_name、$event_time、$server_time は ThinkingData の対応するフィールドを上書きしません。プリセット # プロパティがサポートされていても、Gravity Engine が送信するとは限らず、保存用フィールドや内部フィールドの上書きも許可されません。

