Platform:

Insights Reporting API

1. 简介

Tapjoy Insights API是用于获取广告（ad_groups）统计数据的REST API。数据可以选择是否基于国家统计。Insights API可以获取到广告最近两年内的数据。

API实时返回数据。数据是准实时收集的，延迟不超过几分钟。在最坏的情况下，它可能最多延迟一个小时，因此建议您将作为隔天数据源。

2. Insights 用法

使用如下链接请求数据：

https://api.tapjoy.com/v1/ad_groups//insights

请“id”是所请求广告的id。请参考Legacy Reporting API文档获取广告id，即Legecy Reporting API返回数据中的“AppKey”。

3. 请求权限

您需要Publisher Reporting API密钥来请求数据。您可以在开发者控制面板的设置->应用设置->应用信息->API 密钥:

如果您正在使用Tapjoy控制面板的“V2”版本(dashboard.tapjoy.com)，您可以通过在如下链接中获取密钥https://dashboard.tapjoy.com/reporting/api。在这里，密钥称为"Insights Reporting API Key"。

请注意，这个密钥不同于Legacy Reporting API密钥。

4. 验证与授权

请求将使用标准的两层OAuth2流程进行身份验证。通过Publisher Reporting API密钥可以得到access token，这个access token将会用于接下来请求的授权。
Access tokens只有一个小时有效期。一旦token过去，您需要通过Publisher Reporting API密钥获取新的token。

A. 获取Access Token

通过使用Publisher Reporting API密钥作为Authorization头部信息数据的POST请求可以请求获得access token。一旦验证通过，在Response信息中将会包括access token和token以秒为单位的有效期时间。

请求示例

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. 如何使用access token

一旦得到access token，可以继续后续API。在每次请求中，都需要将access token填入到：“Bearer”类型的Authorization头部信息。如果access token已经过期或者不存在，将会返回状态码 401 Unauthorized.

请求示例

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

token过期返回

status 401
{
    “error”: “Unauthorized”
}

5. 请求示例脚本

这是请求access token和使用access token获取广告数据的Ruby示例代码。注意在这个代码中，我们假设客户获取到信息都是正确的，我们忽略了错误信息处理。

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

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

###
# Request an access token
###
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']

###
# Use the token to request insights
###
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)
###
# Output response body, see examples in Responses section below for data formatting
###
puts response.body

6. 请求参数

名称	值	描述
start_time	e.g. 2015-08-01T00:00:00-04:00	查询的开始时间范围为ISO8601格式，现在仅支持整小时时间，比如2015-08-01T00:30:00-04:00是不合规的。如果使用start_time则同时需要使用end_time。 start_time/end_time和time_preset是互斥的。
end_time	e.g. 2015-08-01T00:00:00-04:00	查询的结束时间范围为ISO8601格式，现在仅支持整小时时间，比如2015-08-01T00:30:00-04:00是不合规的。如果使用end_time则同时需要使用start_time。start_time/end_time和time_prese是互斥的。
time_increment	hourly, daily	数据按照什么统计。“daily”表示按照每天统计数据。
time_preset	today, yesterday, last_week	和start_time/end_time是互斥的。
breakdowns	country_code	用于细分数据的指标。每个请求仅支持一次细分。

7. 响应

HTTP Response Codes

200 - Successful request accompanied by a response body
403 - Unauthorized
422 - Invalid parameters accompanied by error message body
500 - Internal server error

Response Body

根据细分数据参数“breakdowns”，比如按国家，返回两个不同的数据格式。

对于包含secondary tracking offer的ad_groups，在返回数据的“metadata”中包括一个独立的请求URL，可以通过这个URL来获取secondary offer的花费。

使用国家细分参数的情况下，数据返回格式：

{
    "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"
   }
  }
 }
}

不使用国家细分参数的情况下，数据返回全部在“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”每个统计维度下，数据是由两个元素数组组成的多维数组。第一个元素是Unix时间戳；第二个元素是这个时间戳下对应的数据。

在上面的示例中，“time_increment” 参数设置为了“daily”，所以数据是按天返回的。

Error Body

错误信息会通过422相应代码以如下格式返回：

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

Insights Reporting API
1. 简介
2. Insights 用法
3. 请求权限
4. 验证与授权
5. 请求示例脚本
6. 请求参数
7. 响应