AppLovin MAX S2S Impression Revenue API
サードパーティデータ統合によって生成されたデータは、クラスターの消費データ量に含まれますのでご注意ください
概要
インターフェースの概要
| インターフェース名 | タイプ | 粒度 | アトリビューション | コスト | 収益 | 表示 | クリック | コンバージョン |
|---|---|---|---|---|---|---|---|---|
| MAX S2S Impression Revenue API | コールバック | ユーザーレベル | ✅ | ✅ |
AppLovinは、MAX S2S Impression Revenue APIによってデータをコールバックする方法を提供しています。マネタイズ広告が表示されるたびに、AppLovinは表示単位の収益データを、設定されたコールバックリンクにコールバックします。
統合の流れ
- AppLovin SDKとAE SDKを統合し、AppLovin SDKでAEのユーザー識別IDを設定します
- AE管理画面にログインし、サードパーティ統合モジュールでAppLovin MAX S2S Impression Revenue APIプランを追加して、関連する設定を完了します
- AppLovin管理画面にログインし、コールバックアドレスの設定を完了します
- AEシステムがデータを正常に受信しているかを確認し、レポートを作成します
1. クライアントSDKの設定
AppLovinデータを統合する最初のステップは、クライアント側でAE SDKとAppLovin SDKを連携させることです。
1.1 方法1（自動関連付け）
-
統合しているAndroid、iOS SDKについて
- SDKのバージョンが2.8.0~2.8.1の場合は、この方法をそのまま使用できます
- SDKのバージョンが2.8.2以上の場合は、サードパーティデータプラグインもインストールする必要があります。詳しくはAndroid SDKのサードパーティデータとiOS SDKのサードパーティデータを参照してください
AEのSDKの初期化と自動統合を有効にするコードは、AppLovinのSDKの初期化より前に完了する必要がありますのでご注意ください。次の手順に従って操作してください：
1. AE SDKを初期化します。
2. `enableThirdPartySharing`を呼び出して、ゲストIDを自動設定します。
3. AppLovin SDKを初期化します。
各プラットフォームのSDKのコードサンプルは次のとおりです：
- Android
- iOS
// 1、Android SDKを初期化
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2、enableThirdPartySharingインターフェースを呼び出し、ta_distinct_idをapplovinイベントに設定
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.APPLOVIN_IMPRESSION)
// 3、applovin SDKを初期化
// 。。。
// 1、iOS SDKを初期化
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
[TDAnalytics startAnalyticsWithConfig:config];
// 2、enableThirdPartySharingインターフェースを呼び出し、ta_distinct_idをapplovinイベントに設定
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeAppLovin];
// 3、applovin SDKを初期化
// 。。。
この方法の仕組みは、内部でAppLovinSdk SDKのsetUserIdentifier()メソッドを自動的に呼び出し、AEプロジェクトのゲストIDを渡すというものです。
1.2 方法2（手動関連付け）
手動関連付けの方法では、AppLovinでsetUserIdentifier()インターフェースを使用して、AEプロジェクトのゲストIDを設定する必要があります。
AEのSDKの初期化とsetUserIdentifierインターフェースの呼び出しは、AppLovinのSDKの初期化より前に完了する必要がありますのでご注意ください。次の手順に従って操作してください：
1. AE SDKを初期化します。
2. `setUserIdentifier`を呼び出して、ゲストIDを設定します。
3. AppLovin 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をapplovinの収集イベントに設定
AppLovinSdk.getInstance(context).setUserIdentifier(distinctId);
// 4、applovin SDKを初期化
// 。。。
// 1、iOS SDKを初期化
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
[TDAnalytics startAnalyticsWithConfig:config];
// 2、AEのゲストIDを取得（AEの#distinct_idに対応）
NSString *distinctId = [TDAnalytics getDistinctId];
// 3、ゲストIDをapplovinの収集イベントに設定
[ALSdk shared].userIdentifier = distinctId;
// 4、applovin 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をApplovinの収集イベントに設定
MaxSdk.SetUserId(distinctId);
// 4、Applovin SDKを初期化
// 。。。
2. プランの設定
SDKの設定が完了したら、次にAEシステムの管理画面にログインし、「サードパーティ統合」モジュールでAppLovin MAX S2S Impression Revenue APIの設定を行います。下図はAppLovinの設定画面です：
2.1 ユーザー識別フィールド
AppLovinがコールバックするのはユーザーレベルのデータであるため、ユーザー識別ルール、つまりAppLovinのコールバックデータ内で#distinct_idと#account_idに対応するフィールドを設定する必要があります。AEシステムはこの設定に基づき、コールバックデータを変換する際に、これらのフィールドをデータのユーザー識別フィールドとして設定します。
本ドキュメントの前のステップに従ってクライアントSDKを設定した場合は、次の設定を使用してください：
- アカウントID関連フィールド：なし
- ゲストID関連フィールド：user_id
2.2 イベントデータの格納設定
「イベントデータの格納設定」スイッチをオンにすると、コールバックされたデータはすべてイベントテーブルに書き込まれます。イベントデータの格納を有効にすることをお勧めします。
2.3 ユーザープロパティの格納設定
デフォルトでは、AEシステムはAppLovinのコールバックデータをユーザープロパティに書き込みません。一部のフィールドをユーザーテーブルに書き込みたい場合は、まずルールをオンにして実行状態にしてから、プロパティのマッピング機能でユーザーテーブルに書き込むフィールドを追加してください。ソースプロパティ名にはフィールドの格納名を入力する必要があります。3.1節の内容を参照してください：
2.4 統合構成
統合構成モジュールで、データ取得の詳細な設定を制御できます。たとえば、格納後のイベント名などです。
| モジュール | 名前 | 意味 |
|---|---|---|
| sink_event | event_name | 格納後のイベント名。カスタマイズ可能 |
2.5 ターミナルアドレス
ターミナルアドレスには、AEシステムがAppLovinのコールバックデータを受信するアドレスが表示されます。このアドレスをそのままコピーし、この後のAppLovinのコールバック設定で、コールバックのメインアドレスとして使用してください：
ここにアドレスが表示されない場合は、右上のメニュー「プロジェクト管理 → プロジェクト設定 → プロジェクト構成」でパブリックネットワークURLを設定してください。このアドレスは、AE SDKで設定するデータ受信URLです。設定後、AppLovin設定ページの「ターミナルアドレス」に戻ってターミナルアドレスをコピーしてください。
3. AppLovinコールバックの設定
3.1 コールバックマクロの設定
最後に、コールバックアドレスの設定を行います。コールバックデータで受け取れるフィールドを「マクロ」と呼びます。デフォルトでは、すべてのフィールドを取得する（つまりすべてのマクロを設定する）ことをお勧めします。次の表は、MAX S2S Impression Revenue APIが対応しているすべてのマクロです：
| マクロ | 格納名 | 説明 | 必須／任意 |
|---|---|---|---|
| {AD_UNIT_ID} | ad_unit_id | MAX広告ID | |
| {AD_UNIT_NAME} | ad_unit_name | MAX広告名 | |
| {AD_UNIT_TEST_NAME} | ad_unit_test_name | 広告テストグループの名前 | |
| {ALL_REVENUE} | all_revenue | 推定収益。FB Bidding時の収益を含む | はい |
| {CC} | cc | 2文字のCountry Code | |
| {CUSTOM_DATA} | custom_data | SDKで設定したカスタムデータ | |
| {EVENT_ID} | event_id | イベントの一意のID | |
| {EVENT_TOKEN} | event_token | イベントToken（イベントの一意のIDから生成） | |
| {EVENT_TOKEN_ALL} | event_token_all | グローバルイベントToken（イベントの一意のIDとすべてのリクエストパラメータマクロから生成） | |
| {FORMAT} | format | 広告タイプ | |
| {IDFA} | idfa | iOSのIDFAまたはAndroidのGoogle Advertising ID | |
| {IDFV} | idfv | IDFV | |
| {IP} | ip | ユーザーのIPアドレス | |
| {NETWORK} | network | 広告を表示したAd Network | |
| {NETWORK_PLACEMENT} | network_placement | Ad Networkの内部Placement名 | |
| {PACKAGE_NAME} | package_name | パッケージ名。AndroidのApp Package NameとiOSのBundle ID (iOS) | |
| {PLACEMENT} | placement | SDKでカスタマイズしたPlacement名 | |
| {PLATFORM} | platform | プラットフォーム | |
| {PRECISION} | precision | 収益データの精度。データのソースによって異なります：
| |
| {REVENUE} | revenue | 推定収益。FB Biddingの場合、この値は0です | はい |
| {TS} | ts | 広告の露出時間 | はい |
| {USER_ID} | user_id | SDKで設定したユーザーID。AEプロジェクトのゲストIDに対応します | はい |
| {WATERFALL_NAME} | waterfall_name | 広告Waterfallの名前 |
以下は推奨するコールバックマクロです。前半部分は2.5節で取得したコールバックアドレスです。「?」とそれ以降の内容をターミナルアドレスの後ろに追加し、AppLovinのスタッフに提供してコールバックアドレスの設定を依頼してください（Server-to-Server Impression Revenue APIを使用してください）：
https://{receiver-host}/attribution/callback/applovin/{app-id}?ad_unit_id={AD_UNIT_ID}&ad_unit_name={AD_UNIT_NAME}&ad_unit_test_name={AD_UNIT_TEST_NAME}&all_revenue={ALL_REVENUE}&cc={CC}&custom_data={CUSTOM_DATA}&event_id={EVENT_ID}&event_token={EVENT_TOKEN}&event_token_all={EVENT_TOKEN_ALL}&format={FORMAT}&idfa={IDFA}&idfv={IDFV}&ip={IP}&network={NETWORK}&network_placement={NETWORK_PLACEMENT}&package_name={PACKAGE_NAME}&placement={PLACEMENT}&platform={PLATFORM}&precision={PRECISION}&revenue={REVENUE}&ts={TS}&user_id={USER_ID}&waterfall_name={WATERFALL_NAME}
3.2 データの格納ルール
- データ内のuser_idをデータのゲストIDとして使用します。このフィールドはAEプロジェクトのゲストIDに対応している必要があります
- データ内のtsフィールド、つまり広告の表示時間をイベントの#event_timeとして使用します
- デフォルト設定を使用する場合のイベント名は -- applovin_max_s2s_impression_revenue
- コールバックリンクで設定したその他のフィールドはすべて格納されます
3.3 標準化フィールド
次のイベントプロパティは標準化処理されます：
| 元フィールド | 標準化フィールド | 意味 |
|---|---|---|
| network_name | te_ads_object.media_source | メディアチャンネル |
| ad_mediation_platform | te_ads_object.media_source | マネタイズチャンネル |
| campaign_name | te_ads_object.campaign_name | 広告キャンペーン名 |
| google_ads_campaign_name | te_ads_object.campaign_name | 広告キャンペーン名（Google Adsデータのみ） |
| google_ads_campaign_id | te_ads_object.campaign_id | 広告キャンペーンID（Google Adsデータのみ） |
| adgroup_name | te_ads_object.ad_group_name | 広告グループ名 |
| google_ads_adgroup_name | te_ads_object.ad_group_name | 広告グループ名（Google Adsデータのみ） |
| google_ads_adgroup_id | te_ads_object.ad_group_id | 広告グループID（Google Adsデータのみ） |
| creative_name | te_ads_object.ad_name | 広告名 |
| google_ads_creative_id | te_ads_object.ad_id | 広告ID（Google Adsデータのみ） |
| ad_revenue_placement | te_ads_object.placement | マネタイズ広告の配置 |
| google_ads_placement | te_ads_object.placement | 広告の配置（Google Adsデータのみ） |
| cost_amount | te_ads_object.cost | 配信コスト |
| cost_currency | te_ads_object.currency | ユーザー獲得配信の通貨 |
| revenue_usd | te_ads_object.revenue | マネタイズ収益 |
| 【USD】固定値 | te_ads_object.currency | マネタイズ収益の通貨 |
| country | te_ads_object.country | 国・地域コード |
| os_name | te_ads_object.platform | プラットフォーム（Android、iOSなど） |
| app_id | te_ads_object.app_id | アプリID |
| app_name | te_ads_object.app_name | アプリ名 |