JPNユーザーレベル収益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 つの行に集約する必要があります。