InCost API:アドネットワーク向け

概要: AppsFlyerのXpendの機能の一部であるInCost APIを使用することで、アドネットワークは広告費のデータをAppsFlyerへ送信できるようになります。そうすることで、広告主はすべてのアドネットワークからのコストデータを一箇所にまとめることが可能になります。

InCost API 

アドネットワークパートナーは、InCost API を使用して詳細な広告費のコストデータを送信します。AppsFlyerはそのデータを取り込み、レポート、管理画面、AWS S3 バケットを通じて広告主やパートナーに提供します。

関連記事:コスト連携の方法:アドネットワーク向け

アドネットワーク向けの実装要件

表示されている順序で、ステップを完了してください。

# 作業 
1 AppsFlyerの担当PDMに連絡し、InCost APIの連携を実施したい旨をお知らせください。
2 あなたのアドネットワークの90%以上のトラフィックにおいて、計測URLにキャンペーン階層(キャンペーンID、アドセットID、アドID)の情報が含まれていることを確認してください。
3

アドネットワークのアドミン権限で、AppsFlyerの管理画面からV2.0 APIトークン を取得してください。 

4

この記事に記載されている方法を使って、InCostの連携とテストを完了してください。

5
  • テストが完了したことを、AppsFlyerの担当PDMへお知らせください。
  • PDM側で連携が機能していることを確認するまでお待ちください。
6

AppsFlyerのあなたのアドネットワークの連携済みパートナーのページ内にある、コストタブでコストデータの取得 を有効にするよう、広告主に伝えてください。 

InCostの実装のチェックリスト

データの送信と検証のプロセス

Copy_of_IncsostFlow__9_.png

  • この記事内の詳細にあるように、JSONで送信するためのコストデータを準備してください。 
  • アプリのタイムゾーンとコストデータの日付を合わせるために、アプリのタイムゾーンに注意してください。 
  • InCost uploaderを使って、コストデータを送信してください。 
  • InCostが返したjob IDを収集して保管してください。
  • 2分後に、job statusのメソッドを使ってジョブが正常に完了したことを確認してください。
  • 正常に完了したジョブのステータスは、applied です。 その後、AppsFlyerの管理画面上にデータが表示されるのは最大で5時間後です。

APIメソッド

InCostのメソッド
メソッド 説明 メソッド
Get app permission list
  • 広告主がInCostの連携を有効にしているアプリのapp_idのリストを取得します。 
  • コストデータを送信するアプリの一覧を更新するために、プログラムを組んでリストを定期的に確認することをオススメします。(広告主は定期的に新規アプリを追加するためです。)
  • このAPIは、app_idの他にアプリ名、AppsFlyerの管理画面上で設定されているタイムゾーンと通貨単位の情報を返します。
GET
InCost upload
  • コストデータをJSON形式で送信してください。
  • InCost uploaderはjob IDを返します。
  • このIDを、次のジョブステータスの確認で使用してください。
POST
Get job status
  • job IDを使って、ジョブステータスを照会します。
  • 送信したジョブのステータスがappliedであることを確認してください。
  • それ以外だった場合には、エラーを修正してJSONを再送信してください。
  • matched_records_percentageの値が100(%)未満の場合、不正確なデータを示す可能性があります。   
  • データのマッチングは、クリックなどのキャンペーンの計測情報と、送信されたキャンペーンのコストデータを使って行なわれます。
GET

APIの基本仕様

InCost APIの仕様
Path

https://hq1.appsflyer.com/api/incost-uploader/v1/data/app/app_id

Pathの必須パラメータ
  • app_id: AppsFlyer管理画面で表示されるアプリ識別子です。管理画面に表示されるとおりに正確に入力してください。
  • iOSの場合、冒頭にidもつけてアプリIDを記載してください。
ヘッダー
  • 受け入れ可能なcontent type: application/json
  • 認証:Bearer token 
  • 受け入れ: application/json

Authorization

  • AppsFlyerのV2.0 APIトークンは、パートナーアカウントのアドミン権限で管理画面から取得してください。すべてのアプリや広告主に対して、同じトークンが使用されます。
日付の制限
  • 過去データのサポート範囲:現在から90日前まで
  • 最新データのサポート範囲:現在の日付まで
レート制限

アドネットワークアカウント(トークン)毎のAPIコール数の制限:

  • 1分あたり150コールまで
  • 1日あたり1000コールまで 
  • ファイルサイズ上限:1MB
制限事項

InCost APIの機能は、代理店アカウントではご利用になれません。アドネットワークは、広告主へ費用を送信することが可能です。 

InCost uploadのメソッド 

コストデータを送信するには、InCost uploadのメソッドを使用します。  

APIリクエストは、以下の条件を満たしている必要があります: 

  • APIコールごとに1アプリのデータを送信してください。 
  • Curlのサンプルに示されているように、データ形式はJSONで送信してください。
  • 各JSONには、特定の日付のキャンペーンコストの詳細を記載してください。
  • 必須のフィールドはすべて入力されている必要があります。(空のフィールドは送信しないでください。 )
  • コスト情報を送信できるメディアソースは、あなたのアドネットワークアカウントに紐付いているメディアソースに限定されます。詳細は担当PDMに確認してください。
  • キャンペーンのコストレポートの階層の一部ではない項目がある場合には、リクエスト内に含めないでください。例:adset ID / adset name / ad ID / ad name
メソッド:InCost upload
Path

POST  https://hq1.appsflyer.com/api/incost-uploader/v1/data/app/app_id

パスのパラメータ (必須)
  • app_id: AppsFlyer管理画面で表示されるアプリ識別子です。管理画面に表示されるとおりに正確に入力してください。
  • iOSの場合、冒頭にidもつけてアプリIDを記載してください。
レスポンス 提供される
JSON内のコストのフィールド

項目

必須

備考

date

はい

  • コストの発生日
  • 形式: YYYY-MM-DD
  • 例:2019-12-30
app_id

 はい

  • AppsFlyerの管理画面上に表示されてるアプリID
  • フォーマット:文字列250文字まで
  • 例: Android:com.app.nameiOS: id123456789

media_source

はい

  • AppsFlyer上でアドネットワークのパートナーアカウントに紐付けられたユニークなネットワークの識別子(ID)
  • フォーマット:文字列50文字まで
  • 例:network_int

af_prt

いいえ*

  • AppsFlyerの代理店アカウントに紐づくデータをアップロードする場合には必須の情報です。
  • 代理店識別子は計測URL内に含まれており、AppsFlyerの各代理店アカウントに一意に紐付けられています。
  • フォーマット:文字列50文字まで
  • 例:agencya

campaign_id

はい

  • 計測URLでaf_c_idのパラメータに渡された値と一致している必要あり
  • 空(empty)の文字列は禁止
  • フォーマット:文字列24文字まで
  • 例: 123abc

campaign_name

はい

  • フォーマット:文字列100文字まで
  • 例: my_campagin123

adset_id

いいえ*
  • adset_name を送信する場合には必須
  • 計測URLでaf_adset_idのパラメータに渡された値と一致している必要あり
  • アドネットワークのコストレポート側でadset_idをサポートしていない場合には、送信禁止
  • フォーマット:文字列24文字まで
  • 例:123A

adset_name

いいえ

  • このフィールドを送信する場合、adset_idも送信する必要あり
  • フォーマット:文字列100文字まで
  • 例:my_adset_name

ad_id

いいえ*


  • ad_nameを送信する場合、このフィールドも送信する必要あり
  • 計測URLでaf_ad_idのパラメータに渡された値と一致している必要あり
  • アドネットワークのコストレポート側でadset_idをサポートしていない場合には、送信禁止
  • フォーマット:文字列24文字まで
  • 例:123AB

ad_name

いいえ

  • このフィールドを送信する場合、ad_idも送信する必要あり
  • フォーマット:文字列100文字まで
  • 例:Ad-name

geo

いいえ

  • コストに関連付けて記録された国情報
  • 可能であれば、広告が表示された国の情報を記載することを推奨
  • フォーマット: ISO 3166の2文字の国コード
  • 例:US, CN, ZA
currency

はい

  • コストの通貨単位
  • フォーマット: ISO 4217の3文字の通貨コード
  • 例: USD, EUR, ZAR
広告費  はい
  • 指定した通貨単位でのコストの合計金額 
  • 小数点以下5桁まで入力可能です。
  • 0 (ゼロ)の値も入力可能です。
  • マイナスの値も入力可能
  •  , (桁の区切り文字)は送信禁止
  • 値を引用符をつけて送信しないでください。 
  • フォーマット:10進数の値
  • 値の例: 1 1.2 1234.20 -1234.20
site_id いいえ
  • 計測URLで af_siteid のパラメータに渡された値と一致している必要あり
  • フォーマット: 文字列24文字まで
  • 例:1234mysiteid
channel いいえ
  • 計測URLで af_channel のパラメータに渡された値と一致している必要あり
  • フォーマット:文字列20文字まで
  • 例:my_channel
Keywords いいえ
  • フォーマット:文字列100文字まで
  • 例:abc app

* このフィールドを送信する必要がある場合もあるので、備考欄を参照してください。

InCost uploadのCurlサンプル

curl --location --request POST 'https://hq1.appsflyer.com/api/incost-uploader/v1/data/app/<app_id_placeholder>'\
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <api_token_placeholder. Note the token has more than 700 characters.>'\
--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で返します。

メソッド:Get jobs status
Path

GET https://hq1.appsflyer.com/api/incost-jobstatus/v1/data/app/app_id/job/job_id

メソッドがGETに設定されていることを確認してください。

Pathの必須パラメータ
  • app_id: AppsFlyerの管理画面上で使用されているアプリID。(管理画面に表示されるとおりに正確に入力してください。)
  • job_id: コストデータの送信時に返されたジョブごとの識別子。 
ジョブステータス
ステータス 説明
Applied
  • ジョブの登録が正常に完了しています。
  • 管理画面上の情報とレポート内のデータは、5時間以内に更新されます。
ジョブが進行中です。 ジョブがまだ完了していません。
検証エラー
  • データ検証のエラーです。
  • エラーメッセージの詳細を確認してください。
  • 修正して、リクエストを再送信してください。 
Error processing data AppsFlyerのシステム側で不具合が発生しています。15分後にもう一度やり直してください。それでもエラーが続いてしまう場合には、恐れ入りますがAppsFlyerのサポートまでお問い合わせください。 
Get job statusのCurlサンプル 
curl --location --request GET 'https://hq1.appsflyer.com/api/incost-mgmt/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のレスポンス例

job statusのレスポンス例
ステータス 説明

Applied

{ 
    "date_from": "2020-02-21",
    "date_to": "2020-02-28",    
    "matched_records_percentage" : 85,
    "app_id": "com.cost.app",
    "status": "Applied",
    "Uploaded request url": "https://domain/file.json"
}
Invalid date
{ 
      "id": "com.cost.app",
"status": "Failed",
"Uploaded request url": "https://domain/file2.json",
"error" : [ {
"af_error_code": “ic211”,
"error_message" : "Incorrect date format. Use the format yyyy-mm-dd."
}

InCost 連携のテスト

パートナーアカウント上で、以下アプリをテストに使用可能です。

  • Android: com.cost.app
  • iOS: id888123456

コスト連携をテストするには:

  1. [任意]End to Endでの計測テスト:
    1. 連携用に構成されたあなたのアドネットワークの計測リンクを使用して、テスト用アプリの計測リンクを準備してください。 
    2. コストデータとクリックデータを一致させるために、campaign、adset、ad IDを含めた状態でクリックのアトリビューショントラフィックを生成してください。
    3. 連携用に構成されたあなたのアドネットワークの計測リンクを使用して、テストアプリ用のクリックを生成してください。実際のトラフィックであるかのように、マクロに実際の値を入れることを忘れないでください。
  2. [必須]ベーシックなコスト連携:
    1. テストデータを準備してください。
    2. InCost uploaderを使って、コストデータを送信してください。
    3. 返ってきたjob IDを記録してください。
    4. 2分待ってください
    5. エラーが見つからなかったことを確認してください。get job statusのメソッドを使用してください。
      注意:アトリビューショントラフィック(=クリック)がないため、一致した行数のスコアが100未満になります。 
    6. エラーが見つかった場合には、データを修正して再送信してください。
    7. 5時間以内にコストデータが管理画面に表示されるので、データが正しいことを確認してください。

エラーメッセージ

以下のエラーコードとメッセージが返されます。

InCostのエラーメッセージ
カテゴリ 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を使って、コストデータの取得設定が 有効になっていることを確認してください。

アドネットワークからのコストデータの取得を有効にするには: 

  1. AppsFlyerにて、[設定] > [連携済みパートナー] へ進みます。
  2. 任意のアドネットワーク名を検索、選択してください。
  3. コストタブへ移動してください。

    InCostEnabled_us-en.jpg

  4. コストデータの取得を有効にしてください。
    これにより、AppsFlyerはパートナーから送信されたコストデータを記録することが許可されます。 
    疑義を避けるため、広告主アカウントのAPI トークンはアドネットワークに共有しないでください。彼らにとって広告主アカウントのAPIトークンは不要です。 
この記事は役に立ちましたか?