ironSourceデータ統合ソリューション
最終更新日：2022-08-17
1. 概要
サードパーティデータ統合によって生成されたデータは、クラスターの消費データ量に含まれますのでご注意ください
本記事では、ironSourceのデータをAgentic Engine（以下、AEシステム）にコールバックする方法を説明します。本プランは次に対応しています：
- クライアントSDKでデータを送信すると、収益データをリアルタイムに取得できます。ただし、収益データは推定値であり、最終的な精算データとは若干の差があります
- Impression Level Revenue APIで、より正確な収益データを取得できます。ただし、リアルタイム性は劣ります（T+1で収益データを取得でき、T+2で最終データを取得できます）
- Reporting APIで、露出、収益、ユーザーアクティブなどを含む集約指標データを取得します。
ironSourceの統合を始める前に、AEシステムのデータルールを読み、AEのデータ構造を理解しておいてください。また、データの取得に必要な情報を担当のカスタマーサクセスマネージャーにお渡しいただくことをお勧めします。形式はデータ統合設定情報テンプレートを参考にしてください。
2. クライアントSDKによる送信
インターフェースの基本情報
| インターフェース名 | APIタイプ | 製品化 | データ粒度 | アトリビューションデータ | コストデータ | 収益データ | インプレッション | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|---|
| ILR SDK | クライアントSDK | いいえ | ユーザーレベル | はい |
Impression Level Revenue (ILR) SDK APIは、ironSource SDKのリアルタイム収益インターフェースで、ironSourceクライアントSDK（Android、iOS、Unity SDK）7.0.3以降のバージョンで提供されています。このインターフェースでは、広告の表示後にコールバックで推定収益データをリアルタイムに取得し、AEクライアントSDKと組み合わせて送信することで、リアルタイム性の高い収益データを取得できます。
2.1 ironSourceの設定
ILR SDKのリアルタイム収益コールバック機能を有効にするには、まずironSource管理画面にログインし、「My Account」-「API」ページの「ARM SDK Postbacks」欄で「Enable ad revenue measurements (ARM) SDK postbacks」にチェックを入れる必要があります
2.2 AEクライアントSDKの設定
方法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);
// ironSource IDの関連付けを有効化
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_IRON_SOURCE);
// ironSource SDKを初期化
// ...
この方法の仕組みは、内部でonImpressionSuccessEventコールバックを自動的に登録し、コールバックを受け取った後にIronSourceImpressionDataのパラメータを自動的に解析して、AE SDKでta_ironSource_callbackイベントを送信するというものです
方法2（手動統合）：
手動統合プランでは、ImpressionData Listenerを実装し、その中にAE SDKのデータ送信インターフェースを追加する必要があります。以下はUnityのコードサンプルです。ImpressionSuccessEvent()を実装してonImpressionSuccessEventに登録すると、広告の表示後にコールバックがトリガーされ、データが送信されます。各SDKの実装方法については、以下のリンクを参照してください：
// ImpressionSuccessEventを登録し、その中でAEにデータを送信するコードロジックを設定
private void ImpressionSuccessEvent(IronSourceImpressionData impressionData) {
Debug.Log ("unity-script: ImpressionSuccessEvent impressionData = " + impressionData);
if (impressionData != null) {
Dictionary<string, object> properties = new Dictionary<string, object>()
{
// 収益ソース: 広告ユニット
{"adUnit", impressionData.adUnit},
// 収益ソース: 広告チャネル
{"adNetwork", impressionData.adNetwork},
// 収益ソース: ironSourceインスタンス名
{"instanceName", impressionData.instanceName},
// 収益ソース: ironSourceインスタンスID
{"instanceId", impressionData.instanceId},
// Placement
{"placement", impressionData.placement},
// 通貨タイプ
{"currency", "USD"},
// 収益
{"revenue", impressionData.revenue},
// 収益タイプ
{"precision",impressionData.precision}
};
// 収益データをAEに送信（収益イベント名をironSource_sdk_postbacksとした場合）
ThinkingAnalyticsAPI.Track("ironSource_sdk_postbacks", properties);
}
}
ironSource SDK Postbacksのコールバックフィールドの一覧は次のとおりです。ironSource公式ドキュメントも参照できます：
| フィールド名 | 説明 | データタイプ |
|---|---|---|
| auctionId | 入札の一意識別ID | String |
| adUnit | 表示された広告ユニット（例：Rewarded Video、Interstitial、Banner） | String |
| adNetwork | 広告メディアチャネル名 | String |
| instanceName | 広告インスタンス名 | String |
| instanceId | 広告インスタンスID | String |
| country | ISO 3166-1形式の国（地域）コード | String |
| placement | 広告プレースメント | String |
| revenue | 収益データ（USD）。この値は推定値の場合があります。詳しくはprecisionフィールドの値を参照してください | Double |
| precision | revenue値のソース:
| String |
| ab | ironSource管理画面で設定したA/B Testのマーク | String |
| segmentName | ユーザーが割り当てられたトラフィックグループ名（Segment。ironSource管理画面で設定） | String |
| lifetimeRevenue | ユーザーが累計で生み出した収益額 | Double |
| encryptedCPM | このフィールドはMeta Audience Network（Facebook Audience Network）の広告データにのみ存在します | String |
3. Impression Level Revenue API
インターフェースの基本情報
| インターフェース名 | APIタイプ | 製品化 | データ粒度 | アトリビューションデータ | コストデータ | 収益データ | インプレッション | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|---|
| Impression Level Revenue API | プル型 | いいえ | ユーザーレベル | はい | はい |
Impression Level Revenue APIは、表示レベル（impression-level）とユーザーレベル（user level）の2種類のデータを提供しています。表示レベルのデータは1件ごとに1回の広告露出であり、イベントデータの意味に合致します。一方、ユーザーレベルのデータは1人のユーザーの生涯指標を集計したもので、イベントデータとしてコールバックするのには適していません。また、このデータは絶えず変化するため、AEシステムでの処理・分析にも適していません。そのため、表示レベルのデータの統合にのみ対応しています。
3.1 認証コードとApp Keyの取得
Impression Level Revenue APIを統合する前に、認証コードと、データを取得するプロジェクトのApp Keyを取得する必要があります。
- ironSource管理画面にログインし、右上のユーザーメニューをクリックして「My Account」ページの「Reporting API」タブに移動し、Secret KeyとRefresh TokenをThinkingAIの担当者に送信します：
- 次に、ironSource管理画面の「Ad Unit」ページに移動し、「APPLICATIONS」リストで統合するアプリを選択すると、右側のカードにそのアプリのApp Keyが表示されます。これをThinkingAIの担当者に送信するか、データ統合設定情報テンプレートに記録します（iOSとAndroidは別々であるため、両方のプラットフォームのデータを統合する場合は、2つのApp Keyを送信する必要があります）
3.2 クライアントSDKの設定
ironSourceのユーザーデータをAEプロジェクトと関連付けるには、ironSourceのsetUserId()メソッドを使用して、AEユーザーのゲストIDをironSourceに送信する必要があります。以下のサンプルコードではUnity SDKを例に、AEのゲストIDをironSourceのUserIdとして設定しています：
// AEのゲストIDをironSourceのUser IDとして設定
IronSource.Agent.setUserId(ThinkingAnalyticsAPI.GetDistinctId());
AEクライアントSDKのデフォルトのゲストIDの値は次のとおりです：
- Androidでは、AE SDKのゲストIDはGAIDで、ironSourceのadvertising_idにはGAIDが使用されます
- iOSでは、AE SDKのゲストIDはIDFVで、ironSourceのadvertising_idにはIDFA/IDFVが使用されます
3.3 対象フィールド
以下は、Impression Level Revenue APIが返すフィールドです：
- ディメンションフィールド
| フィールド名 | 説明 | 値の例 |
|---|---|---|
| event_timestamp | 露出のタイムスタンプ | 2021-09-01 11:26:46 |
| #zone_offset | タイムゾーン（AEプリセットプロパティ） | 0（固定値） |
| advertising_id | ユーザーの広告ID（GAID / IDFA） | 137cf2f0-609c-4ae3-ab64-ed5c0d7392fd |
| advertising_vendor_id | ユーザーのVendor ID（app Set ID / IDFV） | A0810F0B-16C2-474B-B765-77B3A3113AA2 |
| user_id | ユーザーが設定したUser ID（3.2で設定したユーザーID） | c7d9fed7-aa40-4bfa-918f-8d4b155bfd4b |
| ad_unit | 広告ユニット | rewarded_video |
| ad_network | 広告メディア | Admob |
| instance_name | インスタンス名 | Bidding, High |
| country | 国（地域）コード | US |
| placement | プレースメント | Home_Screen |
| segment | ユーザーが割り当てられたトラフィックグループ名 | Tier 1 |
| AB_Testing | A/B Testタグ | A,B |
| app_key | アプリKey | |
| app_name | アプリ名 | |
| platform | プラットフォーム | iOS, android |
- 指標フィールド
| フィールド名 | 説明 | 値の例 |
|---|---|---|
| impressions | 露出数 | 1000 |
| revenue | 収益額 | 0.5 |
3.4 インターフェースのパラメータ
-
時間：
-
日単位、UTCタイムゾーンのデータを取得します
- 取得できるのは直近14日分のデータのみです（たとえば、1月1日のデータは最長で1月14日まで保持され、それ以降は取得してもデータがありません）
- 毎日UTC時間の午後2時（北京時間の午後10時）に、前日（UTCタイムゾーン）のデータを取得できます
- データの修正は過去2日間のデータ（つまり昨日と一昨日）にのみ適用され、それ以降のデータは安定し、調整されなくなります
-
3.5 データの格納ルール
デフォルトでは、取得したデータはイベントとしてAEプロジェクトに書き込まれます。1件の表示データが1件のイベントデータとして書き込まれます：
- データ内のuser_idをデータのゲストIDとして使用します。このフィールドはAEプロジェクトのゲストIDに対応している必要があります
- データ内のevent_timestampフィールド（広告表示時刻）を、イベントの#event_timeとして使用します
- データのイベント名は ironsource_ad_revenue_impression_level です
- その他のフィールドはすべて格納されます
3.6 データ統合設定情報テンプレート
以上のドキュメントを読んだら、次の情報テンプレートに記入し、ThinkingAIの担当カスタマーサクセスマネージャーに送信することをお勧めします：
データインターフェース：ironSource Impression Level Revenue API
--------
会社名：XXX
AEプロジェクト環境：（SAAS/プライベートデプロイ）
AEプロジェクト名：XXX
AEプロジェクトAPP ID: XXX
データ受信URL push_url: XXX
---------
secretkey: XXX
refreshToken: XXX
---------
データ取得設定
appKey：XXX, XXX(iOS, Androidは別々)
履歴データの取得時間範囲：yyyy/mm/dd - yyyy/mm/dd（直近14日間のデータのみ取得できます）
定期取得：毎日北京時間22時に前日のデータを取得
4. Reporting API
インターフェースの基本情報
| インターフェース名 | APIタイプ | 製品化 | データ粒度 | アトリビューションデータ | コストデータ | 収益データ | インプレッション | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|---|
| Reporting API | プル型 | いいえ | 集約指標 | はい | はい | はい |
Reporting APIは、ironSourceの集約指標データのインターフェースです。このインターフェースを通じて、露出、収益、ユーザーのアクティブなどの集約された指標データを取得できます。
4.1 認証コードの取得
Reporting APIを統合する前に、認証コードを取得する必要があります。ironSource管理画面にログインし、右上のユーザーメニューをクリックして「My Account」ページの「Reporting API」タブに移動し、Secret KeyとRefresh TokenをThinkingAIの担当者に送信します：
4.2 対象フィールド
以下は、Reporting APIが返すフィールドです：
- ディメンションフィールド
以下は、Reporting APIの分析ディメンションです。分析ディメンションごとに対応できる指標は異なる点に注意してください。具体的な対応関係については、ironSource公式ドキュメントを参照してください：
| ディメンション名 | フィールド名 | 説明 | デフォルトかどうか | 備考 |
|---|---|---|---|---|
| date | date | データ時間 | はい | |
| adUnits | adUnits | 広告ユニット | はい | |
app | appKey | アプリKey | はい | |
| bundleId | アプリID | はい | ||
| appName | アプリ名 | はい | ||
| platform | platform | アプリのプラットフォーム | はい | |
| adSource | providerName | 広告ソース | はい | |
| instance | instanceName | インスタンス名 | segment、placementと排他 | |
| instanceId | インスタンスID | |||
| country | countryCode | 国（地域）コード | はい | |
| segment | segment | ユーザーが割り当てられたトラフィックグループ名 | instance、placementと排他 | |
| placement | placement | プレースメント | instance、segmentと排他 | |
| osVersion | osVersion | OS バージョン | 最大4つから1つを選択 | |
| connectionType | connectionType | ネットワーク接続タイプ | ||
| sdkVersion | sdkVersion | SDKバージョン | ||
| appVersion | appVersion | アプリバージョン | ||
| att | att | ATTステータス | ||
| idfa | idfa | IDFAが利用可能かどうか | ||
| abTest | abTest | A/B Testタグ |
- 指標フィールド
以下は、Reporting APIが対応している指標のリストです。利用可能な指標は分析ディメンションの影響を受けるため、実際に受信される指標は下表の内容より少なくなる点に注意してください：
| フィールド名 | 説明 |
|---|---|
| revenue | 総収益 |
| eCPM | eCPM |
| appFillRate | 広告フィル率（露出数 / リクエスト数） |
| appRequests | 広告リクエスト数 |
| impressions | 露出数 |
| completions | 完了数
|
| revenuePerCompletion | 平均完了収益額（収益 / 完了数） |
| appFills | 広告フィル数 |
| useRate | 広告の露出数とフィル数の比率 |
| activeUsers | DAU |
| engagedUsers | 広告エンゲージユーザー数 |
| engagedUsersRate | 広告エンゲージユーザーの割合 |
| impressionsPerEngagedUser | 広告エンゲージユーザーあたりの平均広告露出数 |
| revenuePerActiveUser | ARPU値（単位はセント） |
| revenuePerEngagedUser | 広告エンゲージユーザーのARPU値（単位はセント） |
| clicks | 総クリック数 |
| clickThroughRate | クリック率（CTR） |
| completionRate | 特定の行動を完了した割合、つまりコンバージョン率 |
| adSourceChecks | 広告ソースが広告の利用可否を確認した回数 |
| adSourceResponses | 広告ソースがレスポンスを返した回数 |
| adSourceAvailabilityRate | 広告の利用可能率（露出数 / 広告レスポンス数） |
| sessions | Session数 |
| engagedSessions | 広告エンゲージがあったSession数 |
| impressionsPerSession | Sessionあたりの平均露出数 |
| impressionPerEngagedSessions | 広告エンゲージがあったSessionあたりの平均露出数 |
| sessionsPerActiveUser | ユーザーあたりの平均Session数 |
4.3 インターフェースのパラメータ
- 時間：
- 日単位、UTCタイムゾーンのデータを取得します
- アプリ：
- 取得するアプリを指定できます（AndroidとiOSは別々）
4.4 データの格納ルール
デフォルトでは、取得したデータはイベントとしてAEプロジェクトに書き込まれます：
- Reporting APIは集計データのため、固定値をユーザー識別子として使用します。すべてのデータが1人の仮想ユーザーに紐付けられていると考えてください
- データ内のdateフィールド（データ時間）を、イベントの#event_timeとして使用します
- データのイベント名は ironsource_reporting_level です
- その他のフィールドはすべて格納されます
4.5 データ統合設定情報テンプレート
以上のドキュメントを読んだら、次の情報テンプレートに記入し、ThinkingAIの担当カスタマーサクセスマネージャーに送信することをお勧めします：
データインターフェース：ironSource Reporting API
--------
会社名：XXX
AEプロジェクト環境：（SAAS/プライベートデプロイ）
AEプロジェクト名：XXX
AEプロジェクトAPP ID: XXX
データ受信URL push_url: XXX
---------
secretkey: XXX
refreshToken: XXX
---------
データ取得設定
分析粒度：xxx，xxx（入力しない場合はデフォルトを使用）
取得するアプリのKey：xxx，xxx（デフォルトはすべて取得）
履歴データの取得時間範囲：yyyy/mm/dd - yyyy/mm/dd
定期取得：毎日X時に前日のデータを取得
5. データ検証
AEシステム管理画面の「データ管理」-「イベント管理」ページ、または「SQL IDE」ページで、次のイベントが格納されているかを検索できます：
-
クライアントSDKに対応するイベント
- ta_ironSource_callback（方法1）
- ironSource_sdk_postbacks（方法2）
-
Impression Level Revenue APIに対応するイベント
- ironsource_ad_revenue_impression_level
-
Reporting APIに対応するイベント
- ironsource_reporting_level
6. FAQ
6.1 クライアントSDKによる送信とImpression Level Revenue APIによる送信では、データにどのような違いがありますか？
- クライアントSDKで送信するデータは即時性が高い一方で、正確性は低くなります
- Impression Level Revenue APIのデータには1日の遅延があり、データが安定するのは3日目であるため即時性は低くなりますが、データが安定した後の正確性は高くなります。
6.2 AEに格納したデータとironSource管理画面のUIのデータにわずかな差異があるのはなぜですか？
- ironSourceはUTCタイムゾーンでの取得のみ提供しています。AE管理画面で設定したタイムゾーンがUTCになっているか確認してください
- データのわずかな差異は、ironSource APIのデータチャネルとironSource管理画面UIのデータチャネルのわずかな違いによって生じている可能性があります。たとえば、UIのデータチャネルはデータベースA-Bで、さらにフロントエンドコードによる小数の四捨五入ロジックが加わります。一方、APIのデータチャネルはデータベースA-Cです。