TopOnデータ統合ソリューション
最終更新日：2022-08-17
1. 統合前の準備
サードパーティデータ統合によって生成されたデータは、クラスターの消費データ量に含まれますのでご注意ください
1. 概要
本記事では、TopOnのデータをAgentic Engine（以下、AEシステム）にコールバックする方法を説明します。本プランは次の3つの方法に対応しています。インターフェース名をクリックすると、該当するプランの項目に移動できます：
| インターフェース | 説明 | APIタイプ | 製品化 | データ更新頻度 |
|---|---|---|---|---|
| デバイスレベルデータレポートAPI | 集計データ | プル型 | はい | 2日前のデータのみ取得可能（T2） |
| 総合レポート | 集計データ | プル型 | いいえ | 当日のデータを取得可能（T0） |
| クライアントSDKによる送信 | ユーザー詳細データ | クライアントSDK | - | リアルタイム |
TopOnのデータの統合を始める前に、AEシステムのデータルールを読み、AEのデータ構造を理解しておいてください。また、データの取得に必要な情報を担当のカスタマーサクセスマネージャーにお渡しいただくことをお勧めします。形式はデータ統合設定情報テンプレート（デバイスレベルデータレポートAPI、総合レポート）を参考にしてください。
2. デバイスレベルデータレポートAPI（製品化済み）
インターフェースの基本情報
| インターフェース名 | APIタイプ | 製品化 | データ粒度 | アトリビューションデータ | コストデータ | 収益データ | インプレッション | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|---|
| デバイスレベルデータレポートAPI | プル型 | はい | ユーザーレベル | はい | はい | はい |
デバイスレベルデータレポートAPIでは、ユーザーディメンションの集約指標を取得できます。一定期間内のユーザーの総表示、クリック、収益のデータが含まれます。
2.1 API権限
データを取得する前に、まずTopOnの担当者にデバイスレベルデータレポートAPIの権限の開通を申請する必要があります。開通後、開発者管理画面のアカウント情報ページでPublisher Keyを確認できます。Publisher KeyとTopOn管理画面のプロジェクトのアプリIDをThinkingAIの担当者に送信するか、データ統合設定情報テンプレートに記入してください。
アカウント情報ページでPublisher Keyを取得できます
アプリページでTopOnプロジェクトのアプリIDを確認できます
2.2 クライアントSDKの設定
レポートデータのuser_idプロパティは、Androidアプリではコスト上の理由からデフォルトでは返されません。必要な場合は、まずSDKのバージョンを5.9.70以上にアップグレードし、TopOnの運用担当者に連絡して権限について相談してください
方法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);
// TopOn IDの関連付けを有効化
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TOP_ON);
// TopOn SDKを初期化
// ...
// ゲストIDを変更した後は、再度データを同期する必要があります(任意)。
instance.identify("distinct_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TOP_ON);
この方法の仕組みは、内部でATSDKのinitCustomMapメソッドを自動的に呼び出し、ATCustomRuleKeys.USER_IDを渡すというものです。渡す値はAEプロジェクトのゲストIDです。
方法2（手動統合）：
手動統合プランでは、TopOnのApp全体のカスタムルール設定を使用して、AEの#distinct_idをTopOn SDKのcustom_rule内のuser_idに渡す必要があります。呼び出し方法とコード例については、こちらのドキュメントを参照してください。
iOSクライアントのコード設定サンプル：
[[ATAPI sharedInstance] setCustomData:@{kATCustomDataUserIDKey:self.TA_DISTINCT_ID}];
Androidクライアントのコード設定サンプル：
// AEのゲストIDを取得（AEの#distinct_idに対応）
String te_distinct_id = instance.getDistinctId();
Map<String, String> customMap = new HashMap<>();
customMap.put(ATCustomRuleKeys.USER_ID, te_distinct_id);
ATSDK.initCustomMap(customMap);
注意（非常に重要）：
setCustomData (iOS)メソッドまたはinitCustomMap (Android)による送信は、TopOn SDKの初期化より前に完了する必要があります。そうしないと、一部のuser_idがコールバックされない可能性があります。
2.3 データの取得
2.3.1 対象フィールド
デバイスレベルデータレポートAPIの対象フィールドは次のとおりです
| フィールド | タイプ | 備考 |
|---|---|---|
| placement_id | 文字列 | 広告枠ID |
| placement_name | 文字列 | 広告枠名 |
| placement_format | 文字列 | 広告タイプ： 0：native；1：rewarded_video；2：banner；3：interstitial； 4：splash |
| android_id | 文字列 | デバイスID、androidid |
| gaid | 文字列 | Googleの広告デバイスID |
| idfa | 文字列 | iOSのデバイスID |
| area | 文字列 | 国 |
| impression | 数値 | 表示数 |
| click | 数値 | クリック数 |
| revenue | 数値 | 収益。サードパーティ広告プラットフォームの収益をデバイスレベルで分割したもので、通貨単位は開発者管理画面の設定と同じです |
ecpm | 数値 | TopOnが収益APIに基づいてデバイスの表示ごとに分割した収益と、TopOnが集計したデバイスの表示からeCPMを算出します。計算式：（デバイス収益/TopOnが集計したデバイスの表示）* 1000。注：eCPMは2日遅れで提供されます |
| is_abtest | 文字列 | コントロールグループまたはテストグループ： 0：コントロールグループ、またはA/Bテストが未開通であることを表します；1：テストグループを表します |
| traffic_group_id | 文字列 | コントロールグループまたはテストグループのid |
| segment_id | 文字列 | トラフィックグループID |
| segment_name | 文字列 | トラフィックグループ名 |
| idfv | 文字列 | iOSのデバイスID |
| oaid | 文字列 | AndroidのデバイスID |
| user_id | 文字列 | 開発者のカスタムユーザーID |
| network_firm_id | 文字列 | 広告プラットフォームID |
| network_firm | 文字列 | 広告プラットフォーム名 |
| currency | 文字列 | 開発者アカウントの通貨。USDは米ドル、CNYは人民元を表します |
| os_version | 文字列 | iOSデバイスのOSバージョン |
| att_status | 文字列 | iOSデバイスのATT許可ステータス： 0：Not determined(許可するかどうか未決定) ；1：Restricted (制限あり)；2：Denied(拒否済み)；3：Authorized(許可済み) |
| imei | 文字列 | Androidのデバイス識別コード |
| device_type | 文字列 | IOSデバイスタイプ。列挙値の説明： 0：IOS以外のデバイス；1：iphone；2：ipad |
| brand | 文字列 | デバイスブランド名 |
| model | 文字列 | デバイスモデル |
| app_vn | 文字列 | アプリのバージョン名 |
| app_vc | 文字列 | アプリのバージョン番号 |
| new_user_type | 文字列 | 新規ユーザータイプ。列挙値の説明： 1: 新規ユーザーである；2: 新規ユーザーではない |
| channel | 文字列 | チャネル。開発者がTopOn SDKで渡したチャネル |
| estimate_revenue | decimal(18,6) | 推定収益。入札広告ソースはリアルタイムの広告表示価格を集計して推定収益を算出し、非入札広告ソースは手動入力したeCPM価格 * TopOnが集計した表示数を集計して推定収益を算出します |
2.3.2 インターフェースのパラメータ
-
時間：
- 特定の日を開始時間としてデータを取得します。開始時間は2日前以前のみ指定できます
- タイムゾーンはUTC 0、-8、+8から選択できます。指定しない場合は、開発者アカウントのタイムゾーンがデフォルトで使用されます
-
App：
- データを取得するAppを指定する必要があります。TopOn管理画面のアプリIDを提供してください
2.3.3 データの格納ルール
デフォルトでは、取得したデータはイベントとしてAEプロジェクトに書き込まれます：
- データ内のuser_idをデータのゲストIDとして使用します。このフィールドはAEプロジェクトのゲストIDに対応している必要があります
- 取得したデータの開始時間フィールドを、イベントの#event_timeとして使用します
- データのイベント名は ta_ad_revenue_topon です
- その他のフィールドはすべて格納されます
2.4 データ統合設定情報テンプレート
以上のドキュメントを読んだら、次の情報テンプレートに記入し、ThinkingAIの担当カスタマーサクセスマネージャーに送信することをお勧めします：
データインターフェース：TopOnデバイスレベルデータレポートAPI
--------
会社名：XXX
AEプロジェクト環境：（SAAS/プライベートデプロイ）
AEプロジェクト名：XXX
AEプロジェクトAPP ID: XXX
データ受信URL push_url: XXX
---------
TopOn App ID：XXX
TopOn Publisher Key：XXX
---------
取得タイムゾーン：UTC+8 (列挙値：UTC-8、UTC+8、UTC+0。指定しない場合は開発者アカウントのタイムゾーンをデフォルトで使用)
履歴データの取得時間範囲：yyyy/mm/ddから（2日前以前）
定期取得：毎日X時に過去X日間のデータを取得
3. 総合レポート
インターフェースの基本情報
| インターフェース名 | APIタイプ | 製品化 | データ粒度 | アトリビューションデータ | コストデータ | 収益データ | インプレッション | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|---|
| 総合レポート | プル型 | いいえ | 集計データ | はい | はい | はい |
総合レポートとは、TopOnのデータレポートクエリAPIにおける総合レポートデータのことで、集約された広告マネタイズデータを提供します。表示、クリック、収益の指標が含まれます。
3.1 API権限
データを取得する前に、まずTopOnの担当者にデータレポートクエリAPIの権限の開通を申請する必要があります。開通後、開発者管理画面のアカウント情報ページでPublisher Keyを確認できます。Publisher KeyとTopOn管理画面のプロジェクトのアプリIDをThinkingAIの担当者に送信するか、データ統合設定情報テンプレートに記入してください。
アカウント情報ページでPublisher Keyを取得できます
アプリページでTopOnプロジェクトのアプリIDを確認できます
3.2 データの取得
3.2.1 グループディメンション
下表は、総合レポートクエリAPIが対応しているすべてのグループディメンションです。注意：10日以内のデータをクエリする場合は最大6つ、10日より前のデータをクエリする場合は最大3つのグループディメンションを選択できます：
| グループ化ディメンション | フィールド | タイプ | デフォルトかどうか | 備考 |
|---|---|---|---|---|
| date | date | 文字列 | はい | 日付。形式：YYYYmmdd |
app | app_id | 文字列 | はい | 開発者管理画面のアプリID |
| app_name | 文字列 | はい | アプリ名 | |
| app_platform | 文字列 | はい | アプリのシステムプラットフォーム | |
| app_pkg_name | 文字列 | はい | アプリのパッケージ名 | |
| placement | placement_id | 文字列 | はい | 開発者管理画面の広告枠ID |
| placement_name | 文字列 | はい | 広告枠名 | |
adformat | adformat | 文字列 | 広告フォーマット。列挙値：Rewarded Video、Interstitial、Banner、Native、Splash | |
| area | area | 文字列 | 国（地域）コード | |
network | network | 文字列 | 広告プラットフォームのアカウントID | |
| network_name | 文字列 | 広告プラットフォームのアカウント名 | ||
adsource | adsource_network | 文字列 | はい | 広告ソースが属する広告プラットフォームの名前 |
| adsource_token_position_id | 文字列 | はい | 広告ソースの位置ID | |
| adsource_token_orientation | 文字列 | はい | 広告ソースの向き | |
| adsource_token_video_muted | 文字列 | はい | 広告がミュートかどうか | |
| adsource_token_app_id | 文字列 | はい | 広告ソースのApp ID | |
| adsource_token_app_name | 文字列 | はい | 広告ソースのApp名 | |
| adsource_id | 文字列 | はい | 広告ソースid | |
| adsource_name | 文字列 | はい | 広告ソース名 | |
| network_firm_id | network_firm_id | 文字列 | はい | 広告プラットフォームID |
| network_firm | 文字列 | はい | 広告プラットフォーム名 | |
| scenario | scenario_id | 文字列 | 広告シナリオID | |
| scenario_name | 文字列 | 広告シナリオ名 | ||
traffic_group | traffic_group_id | 文字列 | トラフィックグループid | |
| traffic_group_name | 文字列 | トラフィックグループ名 | ||
| traffic_group_segment_id | 文字列 | トラフィックグループの数値ID。注意：デフォルトのトラフィックグループの場合はsegment_id = 0で、返されません | ||
| channel | channel | 文字列 | チャンネル名 | |
| sdk_version | sdk_version | 文字列 | SDKバージョン | |
| app_version | app_version | 文字列 | アプリバージョン |
3.2.2 指標フィールド
デフォルトでは、以下のすべてのフィールドを選択して格納します。調整が必要な場合は、データ統合設定情報テンプレートに記録してください：
| フィールド | タイプ | 備考 |
|---|---|---|
| time_zone | 文字列 | タイムゾーン。列挙値：UTC+8、UTC+0、UTC-8 |
| currency | 文字列 | 開発者アカウントの通貨。このフィールドとrevenueフィールドで構成される収益は、開発者管理画面のレポートの収益と一致する必要があります |
| new_users | 数値 | 新規ユーザー |
| new_user_rate | 数値 | 新規ユーザーの割合 |
| day2_retention | 数値 | 翌日継続 |
| deu | 数値 | DEU |
| engaged_rate | 数値 | 浸透率 |
| imp_dau | 数値 | 表示 / DAU |
| imp_deu | 数値 | 表示 / DEU |
| impression_rate | 数値 | 表示率 |
| dau | 数値 | group_byの条件に応じて返されます |
| arpu | 数値 | dauがある場合のみ返されます |
| request | 数値 | リクエスト数 |
| fillrate | 数値 | フィル率 |
| impression | 数値 | 表示数 |
| click | 数値 | クリック数 |
| ctr | 数値 | クリック率 |
| ecpm | 数値 | TopOnがレポートAPIを通じて広告プラットフォームから取得した実際の収益と、TopOnが集計した表示からeCPMを算出します。計算式：（収益/TopOnが集計した表示）*1000。注：eCPMは1日遅れで提供されます |
| revenue | 数値 | サードパーティ広告プラットフォームの収益。通貨は開発者アカウントの通貨です |
| request_api | 数値 | サードパーティ広告プラットフォームのリクエスト数 |
| fillrate_api | 数値 | サードパーティ広告プラットフォームのフィル率 |
| impression_api | 数値 | サードパーティ広告プラットフォームの表示数 |
| click_api | 数値 | サードパーティ広告プラットフォームのクリック数 |
| ctr_api | 数値 | サードパーティ広告プラットフォームのクリック率 |
| ecpm_api | 数値 | TopOnがレポートAPIを通じて広告プラットフォームから取得した実際の収益と表示APIから、eCPM APIを算出します。計算式：（収益/表示API）*1000。注：eCPM APIは1日遅れで提供されます |
| estimate_revenue | 数値 | 推定収益。通貨：米ドル |
estimate_revenue_ecpm | 数値 | 推定収益とTopOnが集計した表示から推定eCPMを算出します。計算式：（推定収益/TopOnが集計した表示）*1000。注：1. 推定eCPMは当日提供されます。2. 通常の広告ソースは手動入力したeCPM価格に基づいて計算され、入札広告ソースはリアルタイムの入札価格に基づいて計算されます |
| ready_request | 数値 | isReady呼び出し回数 |
| ready_rate | 数値 | isReady成功率 |
| cy_estimate_revenue | 数値 | 開発者アカウントの通貨で返される推定収益 |
| cy_estimate_revenue_ecpm | 数値 | 開発者アカウントの通貨で返される推定eCPM。計算方法はestimate_revenue_ecpmと同じです |
| load | 数値 | トラフィックリクエスト。注意：一部のgroup_byディメンション（例：network_firm_id）を選択した場合、レスポンスは「0」になります |
| load_fillrate | 数値 | トラフィックのフィル率。注意：一部のgroup_byディメンション（例：network_firm_id）を選択した場合、この指標はレスポンスで返されません |
3.2.3 インターフェースのパラメータ
-
時間：
- 日単位のデータを取得します
- タイムゾーンはUTC 0、-8、+8から選択できます。指定しない場合は、開発者アカウントのタイムゾーンがデフォルトで使用されます
3.2.4 データの格納ルール
デフォルトでは、取得したデータはイベントとしてAEプロジェクトに書き込まれます：
- 総合レポートクエリAPIが返すのは集約データであるため、固定値をユーザー識別子として使用します。すべてのデータが1人の仮想ユーザーに紐付けられていると考えてください
- データ内のdateフィールド、つまりデータの日付を、集計データの#event_timeとして設定します
- データのイベント名は topon_fullreport です
- その他のフィールドはすべて格納されます
3.3 データ統合設定情報テンプレート
以上のドキュメントを読んだら、次の情報テンプレートに記入し、ThinkingAIの担当カスタマーサクセスマネージャーに送信することをお勧めします：
データインターフェース：TopOn総合レポートクエリAPI
--------
会社名：XXX
AEプロジェクト環境：（SAAS/プライベートデプロイ）
AEプロジェクト名：XXX
AEプロジェクトAPP ID: XXX
データ受信URL push_url: XXX
---------
TopOn App ID：XXX
TopOn Publisher Key：XXX
---------
取得タイムゾーン：UTC+8 (列挙値：UTC-8、UTC+8、UTC+0)
分析ディメンション：xxx、xxx
取得する指標：xxx、xxx
履歴データの取得時間範囲：yyyy/mm/ddから（2日前以前）
定期取得：毎日X時に過去X日間のデータを取得
4. クライアントSDKによる送信
インターフェースの基本情報
| インターフェース名 | APIタイプ | 製品化 | データ粒度 | アトリビューションデータ | コストデータ | 収益データ | インプレッション | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|---|
| ATAdInfoコールバックインターフェース | クライアントSDK | いいえ | ユーザー詳細データ | はい | はい |
TopOnクライアントSDKにはATAdInfoコールバックインターフェースがあります。getEcpm()などのメソッドで推定eCPM値やその他の関連するディメンションと指標を取得し、AE SDKでAEシステムに送信できます。
Android SDKを例に、収益データを受け取ってAEに渡すコード例を示します：
ATBannerView mBannerView = new ATBannerView(this);
mBannerView.setBannerAdListener(new ATBannerExListener() {
@Override
public void onBannerShow(ATAdInfo entity) {
JSONObject properties = new JSONObject();
try{
properties.put("id", entity.getShowId());
properties.put("publisher_revenue", entity.getPublisherRevenue());
properties.put("currency", entity.getCurrency());
properties.put("country", entity.getCountry());
properties.put("adunit_id", entity.getTopOnPlacementId());
properties.put("adunit_format", entity.getTopOnAdFormat());
properties.put("precision", entity.getEcpmPrecision());
properties.put("network_type", entity.getAdNetworkType());
properties.put("network_placement_id", entity.getNetworkPlacementId());
properties.put("ecpm_level", entity.getEcpmLevel());
properties.put("segment_id", entity.getSegmentId());
properties.put("scenario_id", entity.getScenarioId());
properties.put("scenario_reward_name", entity.getScenarioRewardName());
properties.put("scenario_reward_number", entity.getScenarioRewardNumber());
properties.put("channel", entity.getChannel());
properties.put("sub_channel", entity.getSubChannel());
properties.put("custom_rule", entity.getCustomRule());
properties.put("network_firm_id", entity.getNetworkFirmId());
properties.put("adsource_id", entity.getAdsourceId());
properties.put("adsource_index", entity.getAdsourceIndex());
properties.put("adsource_price", entity.getEcpm());
properties.put("adsource_isheaderbidding", entity.isHeaderBiddingAdsource());
properties.put("ext_info", entity.getExtInfoMap());
}catch(JSONException e){
}
// 収益データをAEに送信。イベント名はtopon_sdk_ad_info
instance.track("topon_sdk_ad_info", properties);
}
});
データの送信後、イベント名がtopon_sdk_ad_infoのイベントに基づいて、AEシステムで関連するディメンションと指標の分析を行えます。
5. 連携テストとデータ利用
5.1 連携テスト
「リアルタイムレコード」、「イベント分析」、または「SQL IDE」で、次のイベントを検索できます：
- デバイスレベルレポートAPIのデータ：ta_ad_revenue_topon
- 総合レポートクエリAPIのデータ：topon_fullreport
- クライアントSDKのリアルタイムコールバックインターフェース：topon_sdk_ad_info
5.2 データ利用
- AE SDKで送信したアプリ内課金とTopOnから取得した広告マネタイズ収益を合算し、より完全なROI分析を行う
広告経由で獲得した非オーガニックユーザーが生み出した収益（サブスクリプション課金、アプリダウンロード課金、アプリ内イベント課金、広告マネタイズを含む）を、ユーザー獲得コストで割ります。計算の過程でユーザーレベルのデータが必要になるため、デバイスレベルデータレポートAPIを使用します。
- 「チャネルソース」仮想イベントプロパティの作成
イベントプロパティとユーザープロパティのアトリビューションデータを、仮想プロパティで1つの仮想イベントプロパティに合成し、グループ化の項目として使用します
channel_final = coalesce(channel(cost), network_name)
- 推定eCPMでユーザーレベルの広告収益をリアルタイムに計算
TopOnの推定eCPMは分析ニーズを満たす精度があり、リアルタイム性にも価値があります。TopOnクライアントSDKのリアルタイムコールバックインターフェースが返す推定eCPMを使用して、AEシステム内でユーザーレベルの広告収益を計算することを検討できます。
| adsource_price | String | 推定収益とTopOnが集計した表示から推定eCPMを算出します。計算式：（推定収益/TopOnが集計した表示）*1000。注：1. クライアントSDKのリアルタイムコールバックインターフェースによる推定eCPMは当日提供されます。2. 通常の広告ソースは手動入力したeCPM価格に基づいて計算され、入札広告ソースはリアルタイムの入札価格に基づいて計算されます |
|---|
- 広告ソースID（adsource_id）を使用して、露出ごとの収益を計算
- イベントプロパティ統合後のデータタイプ
データ利用の柔軟性を高めるため、イベントプロパティはデフォルトで「文字列型として統合」されます。AEシステムの仮想プロパティ機能で文字列型のフィールドを他の型に変換できます。例：
- revenueプロパティを数値型に変換："revenue"（データタイプは数値を選択）
- topon_fullreportで全体フィルターを使用し、app_pkg_nameを「not null」で絞り込む
topon_fullreportのデータを使用する際に、全体フィルターでapp_pkg_nameを「not null」で絞り込むと、ノイズとなるデータを除外できます
- iOSデバイスのATT許可ステータスを取得
iOSのデバイスレベルAPIで、デバイスのATT許可ステータスを取得できます：
0：Not determined(許可するかどうか未決定)；1：Restricted (制限あり)；2：Denied(拒否済み)；3：Authorized(許可済み)
6. FAQ
TopOnのデバイスレベルAPIと総合レポートAPIから送られてきたデータを区別するには？
イベント名で区別できます。ta_ad_revenue_toponはデバイスレベル、topon_fullreportは総合レポートのデータです