This API is now deprecated. It will remain available in the short term to allow you to transition to our Marketing API .
Tapjoy Insights API是用于获取广告(ad_groups)统计数据的REST API。数据可以选择是否基于国家统计。Insights API可以获取到广告最近两年内的数据。
API实时返回数据。 数据是准实时收集的,延迟不超过几分钟。 在最坏的情况下,它可能最多延迟一个小时,因此建议您将作为隔天数据源。
使用如下链接请求数据:
https://api.tapjoy.com/v1/ad_groups//insights
请“id”是所请求广告的id。请参考Legacy Reporting API文档 获取广告id,即Legecy Reporting API返回数据中的“AppKey”。
您需要Publisher Reporting API密钥来请求数据。您可以在开发者控制面板的设置->应用设置->应用信息->API 密钥:
如果您正在使用Tapjoy控制面板的“V2”版本(dashboard.tapjoy.com),您可以通过在如下链接中获取密钥https://dashboard.tapjoy.com/reporting/api。在这里,密钥称为"Insights Reporting API Key"。
请注意,这个密钥不同于Legacy Reporting API密钥。
请求将使用标准的两层OAuth2流程进行身份验证。通过Publisher Reporting API密钥可以得到access token,这个access token将会用于接下来请求的授权。
Access tokens只有一个小时有效期。一旦token过去,您需要通过Publisher Reporting API密钥获取新的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”
}
一旦得到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”
}
这是请求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
名称 | 值 | 描述 |
---|---|---|
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 | 用于细分数据的指标。每个请求仅支持一次细分。 |
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" ]
}