メインコンテンツまでスキップ

Gravity Engine 連携

最終更新 2026/11/10
ヒント

サードパーティからのコールバックにより、プロジェクトのデータ量が増えます。選択したイベントが既存の計測と重複しないか確認してください。

概要​

インターフェースの概要​

APIタイプ粒度アトリビューションコスト収益インプレッションクリックコンバージョン
リアルタイムAPIコールバックユーザーレベル✅✅✅✅

Gravity Engine は、イベントのバッチ、ユーザープロパティ、アトリビューションマクロのパラメーターを JSON 形式で POST します。ThinkingData はプロジェクト設定に従って、イベントデータとユーザープロパティ操作に変換します。

連携前に ユーザー識別ルール を読み、#distinct_id と #account_id の用途を確認してください。コールバック仕様は Gravity Engine 公式ドキュメント を参照してください。

統合の流れ​

  1. ThinkingData SDK を導入して初期化し、ゲストID を取得します。Gravity Engine SDK を導入し、ThinkingData の識別子を Gravity Engine のユーザープロパティに同期します。
  2. ThinkingData で gravityengine 連携を設定します。ユーザー識別フィールド、イベント送信、ユーザープロパティのマッピングを設定し、プロジェクトのコールバック URL を取得します。
  3. Gravity Engine の管理画面でイベントコールバックを有効にします。必要なイベントを選択し、POST URL と広告アトリビューション用のマクロパラメーターを設定します。
  4. テストユーザーでイベントを発生させます。ThinkingData でイベント名、時刻、ユーザーとの紐付け、ユーザープロパティを確認してから、本番トラフィックを有効にします。

1. クライアントSDKの設定​

1.1 Gravity Engine SDK と ThinkingData SDK の導入​

対象プラットフォームの SDK を選択して初期化します。Gravity Engine クライアント SDK ドキュメント と ThinkingData SDK 導入ガイド を参照してください。メソッドのシグネチャは SDK のバージョンによって異なります。識別子の同期手順は以下のとおりです。

1.2 ユーザー識別子の同期​

  1. ThinkingData SDK を初期化してゲストID を取得します。
  2. Gravity Engine SDK の初期化時に、ThinkingData のゲストID と、判明している場合はアカウント ID を渡します。Gravity Engine は ta_distinct_id と ta_account_id に保存します。
  3. ログインまたはキャラクターのログイン後に ThinkingData SDK の login を呼び出し、Gravity Engine のユーザープロパティ API で ta_account_id を更新します。アカウント切り替え時も両方の識別子を同期します。
  4. テストコールバックを送信し、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.channelte_ads_object.media_sourceメディアチャンネル
callback_params.campaign_namete_ads_object.campaign_name広告キャンペーン名
callback_params.ad_namete_ads_object.ad_name広告名
callback_params.ad_idte_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_idstringGravity Engine のアプリとクライアントの識別子です。ThinkingData のプロジェクトやユーザーの識別子の代わりにはなりません。
eventsarrayevent、time、properties を含むイベントのバッチです。イベント出力を制御し、ユーザールールの実行には影響しません。
events[].timenumberミリ秒単位の正の整数 Unix タイムスタンプです。整数を表す文字列も使用できます。桁数から単位を推定しません。
events[].propertiesobject現在のイベントのプロパティです。
callback_paramsobject展開後のマクロパラメーターとカスタムパラメーターです。
user_propertiesobjectThinkingData の識別子とマッピングに使用するユーザープロパティの値です。

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#osOS
$os_version#os_versionOS バージョン
$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#libSDK 識別子
$lib_version#lib_versionSDK バージョン
$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_pathURL パス

表にない $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 が送信するとは限らず、保存用フィールドや内部フィールドの上書きも許可されません。

このページは役に立ちましたか?