分析リポーティングAPI

この API は非推奨となりました。新しい Marketing API に移行する猶予期間として短期間は使用可能な状態を継続します。

1. 概要

Tapjoy 分析リポートAPIは広告オファー(ad_groups)についての情報をオプションで国別分析を含む形で取得できる REST APIです。分析レポートAPIは過去2年にわたる情報を取得できます。

このAPIはリアルタイムのデータを返します。データはほぼリアルタイムで集められ、通常数分以上の遅れはありません。最悪のシナリオでは一時間近く遅延する場合があるため、前日までのデータを参照するためのデータソースとして使う事をお勧めします。

2. 分析リポートエンドポイント

リクエストを下記のエンドポイントに送ります:

https://api.tapjoy.com/v1/ad_groups/{id}/insights

"id" はデータをリクエストするオファーのオファーIDになります。オファーIDを取得する必要がある場合はレガシー分析リポーティングAPIを参照ください。

3. アクセス要求

ダッシュボードの 設定 -> アプリ設定 -> アプリ情報 -> API Keys にある パブリシャーレポートAPIキー が必要になります。

古い "V2″ Tapjoy ダッシュボード (dashboard.tapjoy.com) をお使いの場合、 https://dashboard.tapjoy.com/reporting/api の "Insights Reporting API Key" を使用して下さい。

注: この値は Legacy Reporting API Key とは異なります

4. 認証と認可

リクエストはOAuth2の標準的な二層認可フローを使用します。Publisher Reporting API Key を利用してアクセストークンを要求し、アクセストークンを利用してその後のリクエストの認証として使用します。

アクセストークンの有効期間は一時間で、更新はできません。トークンが無効になった場合には、Publisher Reporting API Keyを利用して新しいアクセストークンを取得して下さい。

A. アクセストークンの取得

アクセストークンを取得する場合、Authorization ヘッダに Publisher Reporting API Key を指定したPOST リクエストを送ります。認証情報が正しい場合、レスポンスにはアクセストークンとトークンが向こうとなるまでの秒数が含まれます。

リクエスト例

POST /v1/oauth2/token
Host: api.tapjoy.com
Authorization: Basic <Publisher Reporting API Key> 
Accept: application/json; */*

成功時のレスポンス

status 200
{
    “access_token”: “token_string”,
    “token_type”: “bearer”,
    “expires_in”: 3600,
    “refresh_token”: null
}

認証情報が正しくない場合のレスポンス

status 401
{
    “error”: “Unauthorized”
}

B. アクセストークンを使用する

取得したアクセストークンは以降のAPIリクエストに利用できます。アクセストークンはすべてのリクエストの Authorizationヘッダに"Bearer"タイプとして送られる必要があります。アクセストークンが無効であったり含まれない場合は、レスポンスは401 Unauthorized ステータスとなります。

リクエスト例

GET /v1/ad_groups/bdbcfcc0-2e39-0133-d996-6c4008927a44/insights
Host: api.tapjoy.com
Authorization: Bearer 
Accept: application/json; */*

トークンが無効な場合のレスポンス例

status 401
{
    “error”: “Unauthorized”
}

5. サンプルリクエストscript

サンプルとしてアクセストークンを取得し、取得したアクセストークンであるアド グループの分析情報を取得するRubyコードを示します。なお、このコードではクライアントの認証情報は正しいものとし、またエラー処理は省略しています。

require 'base64'
require 'json'
require 'net/https'

http = Net::HTTP.new('api.tapjoy.com', 443)
http.use_ssl = true

###
# アクセストークンの取得
###
request = Net::HTTP::Post.new('/v1/oauth2/token')
request['Authorization'] = "Basic #{publisher_reporting_api_key}"
response = http.request(request)
oauth = JSON.parse(response.body)
access_token = oauth['access_token']

###
# トークンを分析情報取得に利用する
###
path = "/v1/ad_groups/#{ad_group_id}/insights"
path << "?time_preset=yesterday&breakdowns=country_code"
request = Net::HTTP::Get.new(path)
request['Authorization'] = "Bearer #{access_token}"

response = http.request(request)
###
# レスポンス bodyを出力。データ整形等を行うには、移行の節のレスポンスの例を参照して下さい。
###
puts response.body

6. リクエストパラメータ

名称	値	説明
start\_time	例: 2015-08-01T00:00:00-04:00	取得する期間の開始日時をISO8601フォーマットで指定します。一時間単位での指定のみが可能です(例えば、2015-08-01T00:30:00-04:00 は正しい日時指定ではありません)。 start\_time は end\_time が指定されている場合は必須です。start/end\_time と time\_preset の利用は排他的です。
end\_time	例: 2015-08-01T00:00:00-04:00	取得する期間の終了日時をISO8601フォーマットで指定します。一時間単位での指定のみが可能です(例えば、2015-08-01T00:30:00-04:00 は正しい日時指定ではありません)。 end\_time は start\_time が指定されている場合は必須です。start/end\_time と time\_preset の利用は排他的です。
time\_increment	hourly, daily	集計データの分析期間を指定します。 “daily” に指定すると、一日単位の集計値となります
time\_preset	today, yesterday, last\_week	start/end\_time との利用は排他的です
breakdowns	country\_code	データをセグメント化する計測値。リクエストにつき一つのみ指定可能です。

7. レスポンス

HTTP Response Codes

200 - 成功: レスポンスがbodyに含まれます
403 - 認証失敗: 
422 - 不正: エラーメッセージがbodyに含まれます。
500 - サーバー内部エラー

レスポンスBody

オプションの"breakdowns"パラメータ(現時点では国別のみ)で詳細情報をリクエストしているかにより、レスポンスの構造は二種類あります。

ad_groupsにトラッキング用のセカンダリ オファーがある場合、レスポンスの"metadata"セクションにリクエストURLが別途用意されています。関連するスペンドデータはそちらから取得できます

"breakdowns" を指定すると分析値が国別にグループ化されます:

{
    "data": {
      "bdbcfcc0-2e39-0133-d996-6c4008927a44": {
      "insights": {
        "US":{
            "paid_clicks": [
                [ 1440115200, 34],
                [ 1440201600, 39]
            ],
            "global_renders": [
                [ 1440115200, 191]
                [ 1440201600, 120],
            ],
            "global_conversions": [
                [ 1440115200, 25]
                [ 1440201600, 28],
            ],
            "installs_spend": [
                [ 1440115200, -1401.38]
                [ 1440201600, -2435.12],
            ]
        },
        "CA":{
            "paid_clicks": [
                [ 1440115200, 12],
                [ 1440201600, 15]
            ],
            "global_renders": [
                [ 1440115200, 78]
                [ 1440201600, 85],
            ],
            "global_conversions": [
                [ 1440115200, 8]
                [ 1440201600, 12],
            ],
            "installs_spend": [
                [ 1440115200, -700.38]
                [ 1440201600, -543.12],
            ]
        }
    }
    "metadata": {
        "name": "AdGroup name",
        "platform": "iOS",
        "secondary_offer_id" : "2a27ecfe-a6fe-4f4f-a32f-727ef69823d1",
    },
    "rel" : {
            "link" : "https://api.tapjoy.com/v1/ad_groups/2a27ecfe-a6fe-4f4f-a32f-727ef69823d1"/insights"
   }
  }
 }
}

"breakdowns"パラメータを指定しない場合、分析値は"insights"節の直下に格納されます:

{
  "data": {
      "bdbcfcc0-2e39-0133-d996-6c4008927a44": {
      "insights": {
      "paid_clicks": [
          [ 1440115200, 34],
          [ 1440201600, 39]
      ],
      "global_renders": [
          [ 1440115200, 191]
          [ 1440201600, 120],
      ],
      "global_conversions": [
          [ 1440115200, 25]
          [ 1440201600, 28],
      ],
      "installs_spend": [
          [ 1440115200, -1401.38]
          [ 1440201600, -2435.12],
      ]
    }
  "metadata": {
      "name": "AdGroup name",
      "platform": "iOS"
      }
    }
  }
}

"insights"節内の分析値は二つの要素を持つ配列の配列になっています。一つ目の要素はepocからの秒数、二つ目の要素は時間区間内での分析値の値です。 上記の例では“time_increment”パラメータの値が"daily"に設定されているため、一日あたりのデータポイントはひとつとなります。

エラー時のBody

エラー時には422レスポンスコードと共にエラーメッセージをBodyに含む形式で送られます:

{
  "errors":[ "Explanation of the error condition" ]
}