概要: AppsFlyerのXpendの機能の一部であるInCost APIを使用することで、アドネットワークは広告費のデータをAppsFlyerへ送信できるようになります。そうすることで、広告主はすべてのアドネットワークからのコストデータを一箇所にまとめることが可能になります。
InCost API
アドネットワークパートナーは、InCost API を使用して詳細な広告費のコストデータを送信します。AppsFlyerはそのデータを取り込み、レポート、管理画面、AWS S3 バケットを通じて広告主やパートナーに提供します。
関連記事:コスト連携の方法:アドネットワーク向け
アドネットワーク向けの実装要件
表示されている順序で、ステップを完了してください。
# | 作業 |
---|---|
1 | InCost連携の申込みフォームを入力してください。 |
2 | AppsFlyerの担当PDMに連絡し、InCost APIの連携を実施したい旨をお知らせください。 |
3 | あなたのアドネットワークの90%以上のトラフィックにおいて、計測URLにキャンペーン階層(キャンペーンID、アドセットID、アドID)の情報が含まれていることを確認してください。 |
4 |
アドネットワークのアドミン権限で、AppsFlyerの管理画面からV2.0 APIトークン を取得してください。 |
5 |
この記事に記載されている方法を使って、InCostの連携とテストを完了してください。 |
6 |
|
7 |
AppsFlyerのあなたのアドネットワークの連携済みパートナーのページ内にある、コストタブでコストデータの取得 を有効にするよう、広告主に伝えてください。 |
データの送信と検証のプロセス
- この記事内の詳細にあるように、JSONで送信するためのコストデータを準備してください。
- アプリのタイムゾーンとコストデータの日付を合わせるために、アプリのタイムゾーンに注意してください。
- InCost uploaderを使って、コストデータを送信してください。
- InCostが返したjob IDを収集して保管してください。
- 2分後に、job statusのメソッドを使ってジョブが正常に完了したことを確認してください。
- 正常に完了したジョブのステータスは、applied です。 その後、AppsFlyerの管理画面上にデータが表示されるのは最大で5時間後です。
APIメソッド
メソッド | 説明 | メソッド |
---|---|---|
Get app permission list |
|
GET |
InCost upload |
|
POST |
Get job status |
|
GET |
APIの基本仕様
Path |
|
Pathの必須パラメータ |
|
ヘッダー |
|
Authorization |
|
日付の制限 |
|
レート制限 |
アドネットワークアカウント(トークン)毎のAPIコール数の制限:
|
InCost uploadのメソッド
コストデータを送信するには、InCost uploadのメソッドを使用します。
APIリクエストは、以下の条件を満たしている必要があります:
- APIコールごとに1アプリのデータを送信してください。
- Curlのサンプルに示されているように、データ形式はJSONで送信してください。
- 各JSONには、特定の日付のキャンペーンコストの詳細を記載してください。
- 必須のフィールドはすべて入力されている必要があります。(空のフィールドは送信しないでください。 )
- コスト情報を送信できるメディアソースは、あなたのアドネットワークアカウントに紐付いているメディアソースに限定されます。詳細は担当PDMに確認してください。
- キャンペーンのコストレポートの階層の一部ではない項目がある場合には、リクエスト内に含めないでください。例:adset ID / adset name / ad ID / ad name
Path |
POST |
パスのパラメータ (必須) |
|
レスポンス | 提供される |
項目 |
必須 |
備考 |
---|---|---|
date |
はい |
|
app_id |
はい |
|
media_source |
はい |
|
af_prt |
いいえ* |
|
campaign_id |
はい |
|
campaign_name |
はい |
|
adset_id |
いいえ* |
|
adset_name |
いいえ |
|
ad_id |
いいえ* |
|
ad_name |
いいえ |
|
geo |
いいえ |
|
currency |
はい |
|
広告費 | はい |
|
channel | いいえ |
|
Keywords | いいえ |
|
* このフィールドを送信する必要がある場合もあるので、備考欄を参照してください。 |
InCost uploadのCurlサンプル
curl --location --request POST 'https://hq1.appsflyer.com/api/incost-uploader/v1/data/app/'\
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data-raw
'[{
"date": "2020-02-28",
"app_id": "com.cost.app",
"media_source": "example_int",
"campaign_id": "1236678",
"campaign_name": "example_campaign",
"geo": "ZA",
"currency": "ZAR",
"spend": 123.12
},
{
"date": "2020-02-29",
"app_id": "com.cost.app",
"media_source": "exmaple_int",
"campaign_id": "123",
"campaign_name": "Campaign123",
"geo": "IL",
"currency": "USD",
//make sure the value for "spend" does NOT have quotation marks, as indicated below.
"spend": 2400
}]'
Get job statusのメソッド
このメソッドは、これまでに送信したコストデータのコールのステータス/エラーのメッセージを、JSONで返します。
Path |
メソッドがGETに設定されていることを確認してください。 |
Pathの必須パラメータ |
|
ステータス | 説明 |
---|---|
Applied |
|
ジョブが進行中です。 | ジョブがまだ完了していません。 |
検証エラー |
|
Error processing data | AppsFlyerのシステム側で不具合が発生しています。15分後にもう一度やり直してください。それでもエラーが続いてしまう場合には、恐れ入りますがAppsFlyerのサポートまでお問い合わせください。 |
curl --location --request GET 'https://hq1.appsflyer.com/api/incost-jobstatus/v1/data/app/<app_id_placeholder>/job/<job_idplaceholder>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '<api_token_placeholder.Note the token has more than 700 characters.>'
Get job statusのレスポンス例
ステータス | 説明 |
---|---|
Applied |
|
Invalid date |
|
InCost 連携のテスト
パートナーアカウント上で、以下アプリをテストに使用可能です。
- Android: com.cost.app
- iOS: id888123456
コスト連携をテストするには:
- [任意]End to Endでの計測テスト:
- 連携用に構成されたあなたのアドネットワークの計測リンクを使用して、テスト用アプリの計測リンクを準備してください。
- コストデータとクリックデータを一致させるために、campaign、adset、ad IDを含めた状態でクリックのアトリビューショントラフィックを生成してください。
- 連携用に構成されたあなたのアドネットワークの計測リンクを使用して、テストアプリ用のクリックを生成してください。実際のトラフィックであるかのように、マクロに実際の値を入れることを忘れないでください。
-
[必須]ベーシックなコスト連携:
- テストデータを準備してください。
- InCost uploaderを使って、コストデータを送信してください。
- 返ってきたjob IDを記録してください。
- 2分待ってください
- エラーが見つからなかったことを確認してください。get job statusのメソッドを使用してください。
注意:アトリビューショントラフィック(=クリック)がないため、一致した行数のスコアが100未満になります。 - エラーが見つかった場合には、データを修正して再送信してください。
- 5時間以内にコストデータが管理画面に表示されるので、データが正しいことを確認してください。
エラーメッセージ
以下のエラーコードとメッセージが返されます。
カテゴリ | HTTPのリターンコード | InCostのエラーコード | エラーメッセージ |
---|---|---|---|
レート制限 | 429 | ic111 | Exceeded API-rate limit. Wait one minute and try again. (APIレートの上限を超えています。1分待ってから再送信してください。) |
データ検証 | 422 | ic211 | Incorrect date format. Use the format yyyy-mm-dd. (日付のフォーマットが正しくありません。yyyy-mm-ddのフォーマットを使用してください。) |
データ検証 | 422 | ic212 | XXX is in the future. Future dates are not allowed. (XXXは将来の日付です。将来の日付は使用できません。) |
データ検証 | 422 | ic213 | media_source XXX was not found. Verify and resubmit. (media_source XXXが見つかりませんでした。確認して再送信してください。) |
データ検証 | 422 | ic215 | app_id was not found. Verify and resubmit. (app_idが見つかりませんでした。確認して再送信してください。) |
データ検証 | 422 | ic217 | Insufficient cost amount. Spend amount must be greater than 0. (コストの合計金額が不十分です。合計金額は0以上である必要があります。) |
データ検証 | 422 | ic218 | Reserved |
データ検証 | 422 | ic219 | Geo (country) code was not found. Use an ISO 3166 2-letter code. (地域(国)コードが見つかりませんでした。ISO 3166の2文字のコードを使用してください。) |
データ検証 | 422 | ic220 | Currency code was not found. Use an ISO 4217 2-letter code. (通貨コードが見つかりませんでした。ISO 4217の2文字のコードを使用してください。) |
データ検証 | 422 | ic221 | Request had 2 or more currencies. Send 1 currency per app per request. (リクエストに2つ以上の通貨単位が含まれています。1つのリクエストにつき、1つのアプリ、1つの通貨単位で送信してください。) |
データ検証 | 422 | ic222 | Request had 1 or more duplicate records. Remove file duplication/s. (リクエストに1つ以上の重複したデータが含まれていました。重複したデータを除外してください。) |
データ検証 | 422 | ic224 | Job ID was not found. Verify and resubmit. (Job IDが見つかりませんでした。確認して再送信してください。) |
データ検証 | 422 | ic225 | Status was not found. Verify and resubmit. (ステータスが見つかりませんでした。確認して再送信してください。) |
データ検証 | 422 | ic226 | Incorrect count value. Use a number between 1-1000. (countの値が正しくありません。1-1000の数値を使用してください。) |
データ検証 | 422 | ic227 | Incorrect cursor. Use the cursor from the last response. (cursorが正しくありません。最後のレスポンスのcursorを使用してください。) |
ファイルサイズ | 413 | ic311 | File exceeds 25MB. Split the file into multiple requests. (ファイルが25MBを超えています。ファイルを複数のリクエストに分割してください。) |
認証 | 401 | ic414 | Partner account lacks permissions. Partner account must be enabled to upload cost for this app. (パートナーアカウントに付与されている権限が要件を満たしていません。このアプリのコストをアップロードするために、パートナーアカウントを有効にする必要があります。) |
フォーマット | 400 | ic416 | Incorrect JSON format. Verify and resubmit. (JSONフォーマットが正しくありません。確認して再送信してください。) |
General error (一般的なエラー) | 500 | ic300 | There is a server issue. Try again in 10 minutes. (サーバーに問題があります。10分後にやり直してください。) |
Authorization | 401 | ic415 | App and job IDs don't match. Verify and try again. (アプリとjob IDが一致していません。確認して、再度お試しください。) |
データ検証 | 422 | ic228 | Request had 2 or more app IDs; the maximum is 1 per request. Split the request and resubmit. (リクエストに2つ以上のアプリIDが含まれています。1リクエストにつき1アプリIDのみ含めることができます。リクエストを分割して再送信してください。) |
データ検証 | 422 | ic229 | Request and URL app IDs don't match. Verify the app IDs match and resubmit. (リクエストとURL内のapp IDが一致していません。app IDが一致していることを確認して再送信してください。) |
データ検証 | 422 | ic230 | |
データ検証 | 422 | ic231 | Request included data of varying granularity; the data must be uniform. If varying granularity is required, split the request and resubmit. (様々な粒度のデータがリクエストに含まれてしまっています。データは統一されている必要があります。様々な粒度のデータの送信が必要な場合には、リクエストを分割して送信してください。) |
データ検証 | 200 | ic232 | Some request data was outside the allowed time range; the data must be from the last 90 days. Verify the data and resubmit. (リクエストのデータの中に、受け取り可能な日付範囲外のものが含まれています。過去90日間までのデータのみ受け取り可能です。データを確認して、再送信してください。) |
データ検証 | 200 | ic241 | Incorrect click values. Use positive numbers only. Verify and resubmit. (click数の値が正しくありません。正の数値だけを使用してください。確認して再送信してください。) |
データ検証 | 200 | ic242 | Incorrect impression values. Use positive numbers only. Verify and resubmit. (impression数の値が正しくありません。正の数値だけを使用してください。確認して再送信してください。) |
データ検証 | 200 | ic243 | Incorrect time zone code. Use a valid AppsFlyer code per http://www.thefulllist.com/. (タイムゾーンのコードが正しくありません。正しいタイムゾーンのコードを使用してください。) |
Authorization | 404 | ic301 | Incorrect agency name. Use a valid agency name in the URL, then make an upload request. (代理店識別子が正しくありません。計測URL内に含まれている正しい代理店識別子を確認して、再送信してください。) |
Authorization | 401 | ic302 | App ID is not enabled for Xpend. The agency can only share cost data with an advertiser who has the Xpend feature. (このアプリIDでは、Xpendの機能が利用できません。Xpendの機能を契約している広告主のコストデータしか、代理店は共有することができません。) |
Authorization | 401 | ic302 | App ID is not enabled for cost integration. The agency must enable the cost toggle, then resend the data. (このアプリIDでは、コスト連携が有効になっていません。コスト連携を有効にしてもらった上で、データを再送信してください。) |
データ検証 | 422 | ic244 | Incorrect partner name. Enter a valid name in the partner field and resubmit. (パートナー名が間違っています。正しいパートナー名を入力して、再送信してください。) |
データ検証 | 200 | ic245 | Campaign ID can't be sent in the request. Remove the campaign ID and resubmit. (キャンペーンIDをリクエストで送信することができません。キャンペーンIDを削除して再送信してください。) |
データ検証 | 200 | ic246 | Campaign name was not found. Verify and resubmit. (キャンペーン名が見つかりませんでした。確認して再送信してください。) |
広告主側でのコストデータの取得の有効化の作業
- 広告主は、以下の手順に沿ってAppsFlyerの管理画面上でコストデータの取得 を有効にします。
- 広告主は、アプリ毎に個別にコストデータの取得設定を有効にする必要があります。InCostを有効にしたアプリの一覧を取得するAPIを使って、コストデータの取得設定が 有効になっていることを確認してください。
アドネットワークからのコストデータの取得を有効にするには:
- AppsFlyerにて、[設定] > [連携済みパートナー] へ進みます。
- 任意のアドネットワーク名を検索、選択してください。
- コストタブへ移動してください。
- コストデータの取得を有効にしてください。
これにより、AppsFlyerはパートナーから送信されたコストデータを記録することが許可されます。
疑義を避けるため、広告主アカウントのAPI トークンはアドネットワークに共有しないでください。彼らにとって広告主アカウントのAPIトークンは不要です。