ユーザーレベル収益APIの概要

1. 概要

Tapjoyは既存のリワードコールバックに加えて、パブリッシャーがオファーウォールでのユーザーレベルの広告収益データを取得できるユーザーレベル収益API を提供しています。このAPIにより、MMP(Mobile Measurement Partner)やパブリッシャーがAmazon Web Services (AWS) S3 に保存されたCSVを取得して直接ユーザーレベルの広告収益レポートを取得できるようになります。

リクエストを送る際には、Tapjoy App ID (Tapjoy LTV ダッシュボードに登録されているアプリ情報に含まれています) とデータを取得する日付が必要です。

APIを使用するためには、MMP/パートナーは Tapjoy OAuth endpoint に Marketing API Key を使用してアクセストークンを取得する必要があります。取得したアクセストークンを使って Tapjoy API を呼び出し、AWS S3にストアされるリポートの書名付きURLを取得します。この書名付きURLはその後5分間のみリポート取得のためにアクセス可能になります。このAWS S3のリポートURLにアクセスをすると、ユーザーレベル広告収益データを含むCSVリポートが取得できます。

2. リポート API

エンドポイント

https://api.tapjoy.com/api/client/publisher/apps/<app_id>/user_revenue_report

Marketing API key を使って OAuth で認証します。

必須パラメータ:

パブリッシャーの App ID
日付(UTC)

指定可能な日付のフォーマットは次の通りです: mm/dd、mm/dd/yyyy、mm/dd/yy、dd-mm yyyy-mm-dd、yy-mm-dd

戻り値は5分間有効なリポートのサイン付き認証トークンを含むURLの配列です。

リクエストの例

GET api/client/publisher/apps/<publisher_app_id>/user_revenue_report?date=<date> 
Host: api.tapjoy.com 
Authorization: Bearer <access_token_string> 
Accept: application/json

レスポンスの例

成功の場合


{
	"urls": [
	"https://tapjoy.amazon.s3.com/data/report.csv.gz&key=secure"
  	  ]
}

失敗の場合


status 404 
{ 
	“reason”: “No publisher app with id <publisher_app_id> found.” 
}

3. S3 API

データの SLA - x日のデータは、x+1日の 01:00 UTC までに取得可能になります

データ保持 SLA - リポートは14日分利用可能です(x+15日まで保持)

戻り値は、ユーザーレベル広告収益のCSV です。

リクエストの例

GET /data/report.csv.gz&key=secure
Host: tapjoy.amazon.s3.com 
Accept: application/json

レスポンスの例

成功


status 200 
{ 
	CSV File
}

失敗


status 401 
{ 
	“error”: “Unauthorized” 
}

status 404 
{ 
	“error”: “Not Found” 
}

4. フィールド概要

リポートに表示されるフィールドはそれぞれどういった内容ですか?

フィールド	説明
date_id and report_date	API リクエストに基づくユーザ別のリポート日付です。リポート内の測定値はこの日付に基づきます
partner_id	この値は Tapjoy 内部で設定される ID です。
app_name and appkey	これらはアプリの名前、および Tapjoy がアプリを区別するための値です。
IDFA/IDFV/GAID	プラットフォームにより、これらの値はそれぞれの値または UNKNOWN となります。
device_os_version	対象となる携帯端末のOSのバージョンです。
att_status	iOS 端末の App Tracking Transparency ステータスです。(判明している場合)
publisher_user_id	パブリッシャーが設定した端末に結びつく ID です。(利用可能な場合)
ad_unit	この値は常に “offerwall” で、MMP の処理のために使用されます。
placement	Tapjoy のプレイスメントの名前です。
content_card	Tapjoy のコンテンツカードの名前です。
geoip_country	端末に関連した国コードです。(IP アドレスから判別できた場合)
currency_sale	関連するコンバージョンがカレンシーセールの期間でない場合は "1" で、カレンシーセールの期間の場合はカレンシーセールの倍率となります。
conversion_rate	このトランザクションで使用された仮想通貨の変換レートです。
impressions	このデバイス ID と関連づけられた、指定期間の合計インプレッション数です。これは、ユーザーがコンバージョンした当日に、そのコンバージョン済みオファーを閲覧した回数を表します。
publisher_amount	このデバイス ID と関連づけられた、指定期間の収益の合計です。

5. FAQ

このレポートには動画の収益も含まれますか?

いいえ。このリポートはオファーウォールの広告収益のみが含まれます。ユーザーレベルの動画広告データが必要な場合、動画メディエーションパートナーに取得するAPI、または取得についてお訪ねください。

このリポートはいつまでのデータを取得できますか?

リポートはパブリッシャーに14日分アクセス可能です。前日のリポートは当日の01:00 UTCに取得可能になります。

ユーザーレベルリポートのいくつかの行で、インプレッションの列の値が0なのに収益の値が0ではないのはどうしてですか?

MR-CPE(マルチレベルCPE)のオファーでは、インプレッションが発生してから収益となるイベントが発生するまで数日(場合によっては数週間)の遅延が発生する場合がよくあるからです。

収益列の値の単位は何ですか?

アメリカドル(USD)です。

現在このAPIをサポートしているMMPはどこですか?

Appsflyer.

publisher_user_id や geoip_countries カラムに複数の値があるのはなぜですか?

同一のユーザーが、同じアプリ内で複数の異なる publisher_user_id や geoip_countries を使用してオファーを表示し、コンバートする場合があるためです。これらの ID は、 SDK の初期化時にパブリッシャーによって設定されるため、下記のような状況が発生する可能性があります：

ユーザーが publisher_user_id A で connect (初期化) します。
ユーザーは offer A を見ます。View 記録は publisher_user_id A となります。
同ユーザーは publisher_user_id B で connect します。
offer A を再度みます。この View 記録は publisher_user_id B となります。
ユーザーがコンバートします。コンバージョンの記録は publisher_user_id B となります。

同様の事態が geoip_countries でも起こる可能性があります。収益が複数回カウントされることを避けるには、これらの値を 1 つの行に集約する必要があります。

ユーザーレベル収益APIの概要
1. 概要
2. リポート API
3. S3 API
4. フィールド概要
5. FAQ

ユーザーレベル収益APIの概要

1. 概要

2. リポート API

リクエストの例

レスポンスの例

成功の場合

失敗の場合

3. S3 API

リクエストの例

レスポンスの例

成功

失敗

4. フィールド概要

5. FAQ

Contents