TradPlusデータ統合ソリューション
最終更新日：2022-08-22
1. 概要
サードパーティデータ統合によって生成されたデータは、クラスターの消費データ量に含まれますのでご注意ください
概要
本記事では、TradPlusの広告マネタイズデータをAgentic Engine（以下、AEシステム）にコールバックする方法を説明します。本プランは次に対応しています：
- デバイスレベルデータレポートAPIで、ユーザーレベルの広告マネタイズデータを統合
- 総合レポートクエリAPIで、集計された広告マネタイズデータを統合
TradPlusの統合を始める前に、AEシステムのデータルールを読み、AEのデータ構造を理解しておいてください。また、データの取得に必要な情報を担当のカスタマーサクセスマネージャーにお渡しいただくことをお勧めします。形式はデータ統合設定情報テンプレートを参考にしてください。
流れ
TradPlusデータの統合の流れは次のとおりです：
- デバイスレベルデータレポートAPIの統合
- TradPlus管理画面でTokenとアプリIDを取得し、ThinkingAIの担当者に送信します
- クライアントSDKで、AEプロジェクトのゲストIDをTradPlusのカスタムIDとして設定します
- 取得するデータのディメンション、指標タイプ、取得頻度、取得する時間範囲を決めます
- ThinkingAIの担当者がデータ取得の開発作業を行います
- AE管理画面でダッシュボードやレポートを作成し、データ検証を完了します
- 総合レポートクエリAPI
- TradPlus管理画面でTokenとアプリIDを取得し、ThinkingAIの担当者に送信します
- 取得するデータのディメンション、指標タイプ、取得頻度、取得する時間範囲を決めます
- ThinkingAIの担当者がデータ取得の開発作業を行います
- AE管理画面でダッシュボードやレポートを作成し、データ検証を完了します
2. 認証
どのデータを統合する場合でも、まずTradPlus管理画面にログインしてAccess TokenとアプリIDを取得し、ThinkingAIの担当者に送信する必要があります。
- Access tokenは、TradPlus管理画面の「マイアカウント」-「レポートAPI key」で「key を生成」をクリックして取得できます
- アプリIDは「アプリ管理」-「アプリ & 広告枠」で確認できます
3. デバイスレベルデータレポートAPI
インターフェースの基本情報
| インターフェース名 | APIタイプ | 製品化 | データ粒度 | アトリビューションデータ | コストデータ | 収益データ | インプレッション | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|---|
| デバイスレベルデータレポートAPI | プル型 | いいえ | ユーザーレベル | はい | はい | はい |
デバイスレベルデータレポートAPIは、ユーザーレベルの広告マネタイズデータを提供します。特定の1日におけるユーザーの広告表示回数、クリック回数、収益などの指標が含まれます。
3.1 クライアントSDKの設定
TradPlusの広告データをAEプロジェクトのユーザーデータと関連付けるには、クライアントSDKで設定を行い、AEプロジェクトのゲストIDをTradPlus管理画面に渡す必要があります。
方法1（自動統合）：
統合しているAE SDKのバージョンが2.8.0~2.8.1の場合は、このプランをそのまま使用できます
統合しているAE SDKのバージョンが2.8.2以上の場合は、サードパーティデータプラグインもインストールする必要があります
この方法は自動統合プランです。AEクライアントSDKを初期化した後、以下のコードを呼び出して有効にしてください。詳しくはAndroid SDKのサードパーティデータ と iOS SDKのサードパーティデータを参照してください：
// AE SDKを初期化
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// TradPlus IDの関連付けを有効化
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TRAD_PLUS);
// TradPlus SDKを初期化
// ...
この方法の仕組みは、内部でSegmentUtilsのinitCustomMapメソッドを自動的に呼び出し、AE SDKのゲストIDをAppKeyManager.CUSTOM_USERIDに渡すというものです
方法2（手動統合）：
手動統合プランでは、TradPlusのAppKeyManager.CUSTOM_USERID（Android）またはdicCustomValue（iOS）メソッドを使用して、AEのゲストIDをTradPlus SDKのuserId（デバイスレベルデータレポートAPIの返却パラメータの1つ）に渡します。
iOSのコードサンプル：
//アプリディメンションのカスタム情報
NSString *ta_distinct_id = [instance getDistinctId];
[TradPlus sharedInstance].dicCustomValue = @{@"user_id": ta_distinct_id};
Androidネイティブのコードサンプル：
String ta_distinct_id = instance.getDistinctId();
HashMap<String, String> customMap = new HashMap<>();
customMap.put(AppKeyManager.CUSTOM_USERID, ta_distinct_id);
//APPディメンションのルールを設定し、すべてのplacementに適用
SegmentUtils.initCustomMap(customMap);
Unity SDKのコードサンプル：
string ta_distinct_id = ThinkingAnalyticsAPI.GetDistinctId();
Dictionary<string, string> map = new Dictionary<string, string>();
map.Add("user_id", ta_distinct_id);
//APPディメンションのルールを設定し、すべてのplacementに適用
TradPlus.initCustomMap(map);
注意（非常に重要）：
AppKeyManager.CUSTOM_USERID（Android/Unity）またはdicCustomValue（iOS）による送信は、TradPlus SDKの初期化より前に完了する必要があります。そうしないと、一部のuserIdがコールバックされない可能性があります。
3.2 データの取得
3.2.1 対象フィールド
- ディメンションフィールド
| フィールド | タイプ | 備考 |
|---|---|---|
| dateTimeStamp | int | タイムスタンプ（日付） |
| #zone_offset | int | タイムゾーン。リクエスト時に使用したタイムゾーン |
| appId | String | アプリID（TradPlus） |
| placementId | String | 広告枠ID（TradPlus） |
| placementName | String | 広告枠名（TradPlus） |
| adFormat | Int | 広告枠タイプ |
| adFormatName | String | 広告枠タイプ名 |
| area | String | 国・地域コード（ISO 3166-1の2文字の国・地域コード） |
| network | Int | 広告ネットワークID |
| networkName | String | 広告ネットワーク名 |
| networkPlacementId | String | 広告ネットワークの広告枠ID情報 |
| networkPlacementName | String | 広告ネットワークの広告ソース名（TradPlus） |
| networkPlacementInfo | String | 広告ネットワークの広告枠の詳細情報 |
| androidId | String | デバイスID、androidid |
| gaid | String | Googleの広告デバイスID |
| idfa | String | iOSのデバイスID |
| userId | String | ユーザーが独自にアップロードしたCustom User ID。ここにはAEプロジェクトのゲストIDが入ります |
| channel | String | チャネル |
| sub_channel | String | サブチャンネル |
| oaid | String | Androidデバイス識別子 |
| idfv | String | アプリ開発元の識別子 |
| os_version | String | 端末のOSバージョン |
| att_status | Int | AppleのATTステータス（0:ユーザー未決定; 1:制限あり; 2:拒否; 3:許可） |
- 指標フィールド
| フィールド | タイプ | 備考 |
|---|---|---|
| impression | Int | 表示数（TradPlus） |
| click | Int | クリック数（TradPlus） |
| revenue | Float | 収益 |
| ecpm | Float | 1000回表示あたりの収益 |
3.2.2 インターフェースのパラメータ
- 時間：
- 日単位のデータを取得します
- タイムゾーンは"UTC+8"、"UTC+0"、"UTC-8"から選択できます
- 日単位のデータを取得します
- 通貨：
- USD、CNYから選択できます。デフォルトはUSDです
- 取得するプロジェクト：
- データを取得するプラットフォームのプロジェクトを指定し、そのプロジェクトのApp IDを提供する必要があります
3.2.3 データの格納ルール
デフォルトでは、取得したデータはイベントとしてAEプロジェクトに書き込まれます：
- データ内のuserIdをデータのゲストIDとして使用します。このフィールドはAEプロジェクトのゲストIDに対応している必要があります
- データ内のdateTimeStampフィールド、つまりデータのタイムスタンプを、イベントの#event_timeとして使用します
- データのイベント名は tradplus_device_report です
- その他のフィールドはすべて格納されます
4. 総合レポートクエリAPI
インターフェースの基本情報
| インターフェース名 | APIタイプ | 製品化 | データ粒度 | アトリビューションデータ | コストデータ | 収益データ | インプレッション | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|---|
| 総合レポートクエリAPI | プル型 | いいえ | 集計データ | はい | はい | はい |
総合レポートクエリAPIは、広告マネタイズの集約指標データを提供します。広告表示回数、クリック回数、収益などの指標が含まれます。
4.1 分析ディメンション
以下は、総合レポートクエリAPIのすべての分析ディメンションです。デフォルトでは、すべてのグループ化ディメンションを使用します。調整が必要な場合は、取得するグループ項目をデータ統合設定情報テンプレートに記入してください。
| グループ項目 | フィールド | 備考 |
|---|---|---|
| date | date | 日付。形式：YYYY-mm-dd |
| appId | appId | アプリID（TradPlus） |
| packageName | パッケージ名 | |
| placementId | placementId | 広告枠ID（TradPlus） |
| placementName | 広告枠名（TradPlus） | |
| adFormat | adFormat | 広告枠タイプ |
| adFormatName | 広告枠タイプ名 | |
| area | area | 国・地域コード（ISO 3166-1の2文字の国・地域コード） |
| network | network | 広告ネットワークID |
| networkName | 広告ネットワーク名 | |
| networkPlacementId | networkPlacementId | 広告ネットワークの広告枠ID情報 |
| networkPlacementName | 広告ネットワークの広告ソース名（TradPlus） | |
| networkPlacementInfo | 広告ネットワークの広告枠の詳細情報 |
4.2 対象指標
以下は、総合レポートクエリAPIの対象となる指標フィールドです。デフォルトでは、すべてのフィールドを取得します。調整が必要な場合は、取得する指標フィールドをデータ統合設定情報テンプレートに記入してください。
| フィールド | タイプ | 備考 |
|---|---|---|
| dau | Int | 1日のアクティブユーザー数（appレベル） |
| deu | Int | 1日あたりの広告視聴ユーザー数 |
| arpu | Float | ユーザーあたりの平均収益 |
| newUsers | Int | 新規ユーザー（appレベル） |
| newUserRate | Float | 新規ユーザーの割合（appレベル） |
| requestApi | Int | サードパーティ広告プラットフォームのリクエスト数 |
| fillrateApi | Float | サードパーティ広告プラットフォームのフィル率 |
| impressionApi | Int | サードパーティ広告プラットフォームの表示数 |
| clickApi | Int | サードパーティ広告プラットフォームのクリック数 |
| ctrApi | Float | サードパーティ広告プラットフォームのクリック率 |
| ecpmApi | Float | サードパーティ広告プラットフォームのeCPM |
| revenue | Float | 収益 |
4.3 インターフェースのパラメータ
- 時間：
- 日単位のデータを取得します
- タイムゾーンは"UTC+8"、"UTC+0"、"UTC-8"から選択できます
- 日単位のデータを取得します
- 通貨：
- USD、CNYから選択できます。デフォルトはUSDです
- 取得するプロジェクト：
- データを取得するプラットフォームのプロジェクトを指定し、そのプロジェクトのApp IDを提供することができます
4.4 データの格納ルール
デフォルトでは、取得したデータはイベントとしてAEプロジェクトに書き込まれます：
- 総合レポートクエリAPIは集計データのため、固定値をユーザー識別子として使用します。すべてのデータが1人の仮想ユーザーに紐付けられていると考えてください
- データ内のdateフィールド、つまりデータの日付を、イベントの#event_timeとして使用します
- データのイベント名は tradplus_allreport です
- その他のフィールドはすべて格納されます
5. データ統合設定情報テンプレート
以上のドキュメントを読んだら、取得するAPI、フィールド、取得方法などの情報を次の情報欄に記入し、ThinkingAIの担当カスタマーサクセスマネージャーに送信してください。
インターフェース：TradPlusデバイスレベルデータレポートAPI / 総合レポートクエリAPI
--------
会社名：XXX
AEプロジェクト環境：（SAAS/プライベートデプロイ）
AEプロジェクト名：XXX
AEプロジェクトAPP ID: XXX
データ受信URL push_url: XXX
---------
TradPlus Access Token: XXX
---------
データ取得タイプ：デバイスレベルデータレポートAPI / 総合レポートクエリAPI （両方を使用する場合は、それぞれ分けて記入してください）
<-----以下はデバイスレベルデータレポートAPI----->
TradPlus管理画面のアプリID: XXX, XXX
データ取得のタイムゾーン：XXX (タイムゾーン。列挙値：UTC-8、UTC+8、UTC+0。指定しない場合はデフォルトで "UTC+0")
<--------------------------------->
<-----以下は総合レポートクエリAPIの情報----->
TradPlus管理画面のアプリID: XXX, XXX
データ取得のタイムゾーン：XXX (タイムゾーン。列挙値：UTC-8、UTC+8、UTC+0。指定しない場合はデフォルトで "UTC+0")
分析ディメンション：XXX, XXX（デフォルトは全フィールド）
取得する指標：XXX, XXX（デフォルトはall、つまり全フィールド）
<------------------------------------>
履歴データの取得時間範囲：yyyy/mm/dd - yyyy/mm/dd
定期取得：毎日X時に前日のデータを取得
6. 連携テストとデータ利用
6.1 データ検証
AEシステム管理画面の「データ管理」-「イベント管理」ページ、または「SQL IDE」ページで、次のイベントが格納されているかを検索できます：
- デバイスレベルデータレポートAPI：tradplus_device_report
- 総合レポートクエリAPI：tradplus_allreport