TradPlusデバイスレベルデータレポートAPI
サードパーティデータ統合によって生成されたデータは、クラスターの消費データ量に含まれますのでご注意ください
概要
インターフェースの概要
| インターフェース名 | タイプ | 粒度 | アトリビューション | コスト | 収益 | 表示 | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|
| デバイスレベルデータレポートAPI | API | ユーザーレベル | ✅ | ✅ | ✅ |
デバイスレベルデータレポートAPIは、ユーザーレベルの広告マネタイズデータを提供します。特定の1日におけるユーザーの広告表示回数、クリック回数、収益などの指標が含まれます。
統合の流れ
- TradPlusクライアントSDKとAE SDKを統合し、TradPlus SDKでAEのユーザー識別IDを設定します
- TradPlusの管理画面にログインし、Access TokenとアプリIDを取得します
- AE管理画面にログインし、サードパーティ統合モジュールでTradPlusデバイスレベルデータレポートAPIの統合プランを追加します
- AEシステムがデータを正常に受信しているかを確認し、レポートを作成します
1. クライアントSDKの設定
TradPlusデータを統合する最初のステップは、クライアント側でAE SDKとTradPlus SDKを連携させ、TradPlus SDKでAEシステムのユーザー識別IDを設定することです
1.1 方法1（自動統合）
-
統合しているAndroid、iOS SDKについて
- SDKのバージョンが2.8.0~2.8.1の場合は、この方法をそのまま使用できます
- SDKのバージョンが2.8.2以上の場合は、サードパーティデータプラグインもインストールする必要があります。詳しくはAndroid SDKのサードパーティデータとiOS SDKのサードパーティデータを参照してください
-
統合しているUnity SDKのバージョンが2.4.0以上、Unreal SDKのバージョンが1.5.0以上の場合は、この方法をそのまま使用できます
AEのSDKの初期化と自動統合コードの有効化は、TradPlusのSDKの初期化より前に完了する必要があります。次の手順に従って操作してください：
1. AE SDKを初期化します。
2. `enableThirdPartySharing`を呼び出して、ゲストIDを自動設定します。
3. TradPlus SDKを初期化します。
各プラットフォームのSDKのコードサンプルは次のとおりです：
- Android
- iOS
- Unity
- Unreal
// 1. Android SDKを初期化
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. enableThirdPartySharingインターフェースを呼び出し、ta_distinct_idをTradPlusイベントに設定
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.TRAD_PLUS);
// 3. TradPlus SDKを初期化
// 。。。
// 1. iOS SDKを初期化
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
[TDAnalytics startAnalyticsWithConfig:config];
// 2. enableThirdPartySharingインターフェースを呼び出し、ta_distinct_idをTradPlusイベントに設定
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeTradPlus];
// 3. TradPlus SDKを初期化
// 。。。
// 1. Unity SDKを初期化
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2. enableThirdPartySharingを呼び出し、ta_distinct_idをTradPlusイベントに設定
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.TRADPLUS);
// 3. TradPlus SDKを初期化
// 。。。
// 1. Unreal SDKを初期化
UTDAnalytics::Initialize();
// 2. enableThirdPartySharingを呼び出し、ta_distinct_idをTradPlusイベントに設定
TArray<FString> EventTypeList;
EventTypeList.Emplace(TEXT("TAThirdPartyShareTypeTRADPLUS"));
UTDAnalytics::EnableThirdPartySharing(EventTypeList, AppID);
// 3. TradPlus SDKを初期化
// 。。。
このプランの仕組みは、内部でTradPlusの内部メソッドを自動的に呼び出し、AE SDKのゲストIDをTradPlus SDKのuserId（デバイスレベルデータレポートAPIの返却パラメータの1つ）に渡すというものです。
1.2 方法2（手動統合）
手動統合プランでは、TradPlusのAppKeyManager.CUSTOM_USERID（Android）またはdicCustomValue（iOS）メソッドを使用して、AEのゲストIDをTradPlus SDKのuserId（デバイスレベルデータレポートAPIの返却パラメータの1つ）に渡します。
（非常に重要）AEのSDKの初期化とdicCustomValue /initCustomMapインターフェースの呼び出しは、TradPlusのSDKの初期化より前に完了する必要があります。次の手順に従って操作してください：
1. AE SDKを初期化します。
2. ` dicCustomValue ` / ` initCustomMap`インターフェースを呼び出してゲストIDを設定します。
3. TradPlus SDKを初期化します。
各SDKの手動統合のコードサンプルは次のとおりです：
- Android
- iOS
- Unity
// 1. Android SDKを初期化
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. AEのゲストIDを取得（AEの#distinct_idに対応）
String distinctId = TDAnalytics.getDistinctId();
// 3. ゲストIDをTradPlusの収集イベントに設定
HashMap<String, String> customMap = new HashMap<>();
customMap.put(AppKeyManager.CUSTOM_USERID, distinctId);
//APPディメンションのルールを設定し、すべてのplacementに適用
SegmentUtils.initCustomMap(customMap);
// 4. TradPlus SDKを初期化
// 。。。
// 1. iOS SDKを初期化
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2. AEのゲストIDを取得（AEの#distinct_idに対応）
NSString *distinctId = [TDAnalytics getDistinctId];
// 3. ゲストIDをTradPlusの収集イベントに設定
[TradPlus sharedInstance].dicCustomValue = @{@"user_id": distinctId};
// 4. TradPlus SDKを初期化
// 。。。
// 1. Unity SDKを初期化
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2. AEのゲストIDを取得（AEの#distinct_idに対応）
var distinctId = TDAnalytics.GetDistinctId();
// 3. ゲストIDをTradPlusの収集イベントに設定
Dictionary<string, string> map = new Dictionary<string, string>();
map.Add("user_id", distinctId);
//APPディメンションのルールを設定し、すべてのplacementに適用
TradPlus.initCustomMap(map);
// 4. TradPlus SDKを初期化
// 。。。
2. TradPlus管理画面での情報取得
SDKの設定が完了したら、TradPlusの管理画面にログインし、Access TokenとアプリIDを取得する必要があります
- Access tokenは、TradPlus管理画面の「マイアカウント」-「レポートAPI key」で「key を生成」をクリックして取得できます
- アプリIDは「アプリ管理」-「アプリ & 広告枠」で確認できます
3. プランの設定
SDKの設定が完了し、Access TokenとアプリIDを取得したら、AEシステムにログインし、「サードパーティ統合」モジュールで新しいプランの設定を完了できます。下図はTradPlusデバイスレベルデータレポートAPIの設定画面です。この章の内容に従ってプランを作成してください：
3.1 認証情報の設定
「認証情報」の下にある「認証情報設定」ボタンをクリックし、ポップアップに認証作業で取得した情報を入力します
3.2 定期取得
「定期取得」モジュールで、AEシステムがTradPlusデバイスレベルデータレポートAPIのデータを定期的に取得する方針を設定できます。毎日の特定の時刻、または1時間ごとに、一定期間のデータを取得するよう選択できます。取得したデータもデータ量に計上されるため、定期取得で長すぎる期間のデータを取得しないことをお勧めします
3.3 取得タイムゾーン
取得するデータのタイムゾーンも設定できます。デフォルトはUTC+8です
3.4 ユーザー識別フィールド
TradPlusデバイスレベルデータレポートAPIはユーザーレベルのデータであるため、ユーザー識別ルール、つまりTradPlus SDKで設定したAEシステムのユーザー識別IDを設定する必要があります。AEシステムはこの設定に基づき、コールバックデータを変換する際に、これらのフィールドをデータ内のユーザー識別フィールドとして設定します。
本ドキュメントの前のステップに従ってクライアントSDKを設定した場合は、次の設定を使用してください：
- アカウントID関連フィールド：なし
- ゲストID関連フィールド：user_id
3.5 イベントデータの格納設定
「イベントデータの格納設定」スイッチをオンにすると、コールバックされたデータはすべてイベントテーブルに書き込まれます。イベントデータの格納を有効にすることをお勧めします。
3.6 ユーザープロパティの格納設定
デフォルトでは、AEシステムはTradPlusデバイスレベルデータレポートAPIのデータをユーザープロパティに書き込みません。一部のフィールドをユーザーテーブルに書き込みたい場合は、まずルールをオンにして実行状態にしてから、プロパティのマッピング機能でユーザーテーブルに書き込むフィールドを追加してください。ソースプロパティ名にはフィールドの格納名を入力する必要があります：
3.7 統合構成
統合構成モジュールでは、データ取得の詳細な設定を制御できます。たとえば、格納後のイベント名などです
統合構成の内容はJSONです。次の内容に従ってカスタム設定できます：
| モジュール | 名前 | 意味 |
|---|---|---|
| sink_event | event_name | 格納後のイベント名。カスタマイズ可能 |
| transfer | double_columns | 指標フィールドです。変更しないでください |
3.8 イベントの格納ルール
- データ内のdateTimeStampフィールド、つまりデータのタイムスタンプを、イベントの#event_timeとして使用します
- データのイベント名は tradplus_device_report です
- その他のフィールドはすべて格納されます。格納されるすべてのイベントプロパティは以下のとおりです
| フィールド | タイプ | 備考 |
|---|---|---|
| #zone_offset | int | タイムゾーン。リクエスト時に使用したタイムゾーン |
| currency | String | 通貨 |
| appid | String | アプリID（TradPlus） |
| placement_id | String | 広告枠ID（TradPlus） |
| placement_name | String | 広告枠名（TradPlus） |
| ad_format | Int | 広告枠タイプ |
| ad_format_name | String | 広告枠タイプ名 |
| area | String | 国・地域コード（ISO 3166-1の2文字の国・地域コード） |
| network | Int | 広告ネットワークID |
| network_name | String | 広告ネットワーク名 |
| network_placement_id | String | 広告ネットワークの広告枠ID情報 |
| network_placement_name | String | 広告ネットワークの広告ソース名（TradPlus） |
| network_placement_info | String | 広告ネットワークの広告枠の詳細情報 |
| android_id | String | デバイスID、androidid |
| gaid | String | Googleの広告デバイスID |
| idfa | String | iOSのデバイスID |
| user_id | 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.9 標準化フィールド
TradPlusデバイスレベルデータレポートの一部のフィールドについて、AEシステムは標準化処理を行います
| 元フィールド | 標準化フィールド | 意味 |
|---|---|---|
| network_name | te_ads_object.media_source | マネタイズチャンネル |
| placement_name | te_ads_object.placement | 広告の配置 |
| area | te_ads_object.country | 国・地域コード |
| currency | te_ads_object.currency | コストまたは収益の通貨 |
| impression | te_ads_object.impressions | 露出数 |
| click | te_ads_object.clicks | クリック数 |
| revenue | te_ads_object.revenue | マネタイズ収益 |