Insights 리포팅 API

1. 개요

Tapjoy Insights API는 선택적인 국가별 분류와 함께 오퍼(ad_groups)에 대한 지표을 검색하기위한 REST API입니다. Insights API는 지난 2년간의 데이터에 대한 액세스를 제공합니다. 이 API는 리얼타임으로 데이터를 리턴합니다. 데이타 수집은 리얼타임에 근접하게 수집되고, 지연 시간은 수분이내 입니다. 최악의 시나리오에서는 한시간정도의 지연이 발생할 수 있으므로 전달 데이타를 기준으로 활용하기를 권장합니다.

2. Insights 엔드포인트

인사이트 요청은 다음과 같습니다.

https://api.tapjoy.com/v1/ad_groups/insights/<id>

여기서 "id"는 데이터를 요청하는 오퍼 ID입니다. 오퍼 ID를 검색해야하는 경우 레거시 리포트 API를 참조하십시오.

3. 액세스 요청

대시보드의 "설정-> 앱 설정-> 앱 정보-> API Keys" 항목에서 "Publisher Reporting API Key"를 찾을 수 있습니다.

"V2" Tapjoy 대시보드 (dashboard.tapjoy.com)를 사용하는 경우 https://dashboard.tapjoy.com/reporting/api 페이지에서 "Insights Reporting API" 키를 찾을 수 있습니다.

이 키는 레거시 리포트 API키와 다릅니다.

4. 인증 및 승인

리포트 요청은 표준 2-legged OAuth2 방식을 사용하여 인증됩니다. 퍼블리셔 리포팅 API 키를 사용하여 액세스 토큰을 요청하고, 리턴된 액세스 토큰을 사용하여 향후 요청에 대해 인증합니다.

액세스 토큰의 수명은 1시간이며 연장할 수 없습니다. 토큰이 만료되면 Publisher Reporting API Key를 사용하여 새 토큰을 요청하면 됩니다.

A. 액세스 토큰 요청

액세스 토큰을 요청하려면 Publisher Reporting API Key를 사용하여 Authorization header와 함께 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에 대해 요청할 수 있습니다. 액세스 토큰은 "Bearer" 유형으로 Authorization 헤더에 추가하여 모든 요청과 함께 전송되어야 합니다. 액세스 토큰이 만료되었거나 존재하지 않는 경우 응답 상태는 401 Unauthorized입니다.

요청 예

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

만료된 토큰 응답

status 401
{
    “error”: “Unauthorized”
}

5. 예제 요청 스크립트

다음은 예제는 액세스 토큰을 요청한 다음 이를 사용하여 ad group에 대한 통계를 요청하는 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. 요청 파라미터

Name	Values	Description
start\_time	e.g. 2015-08-01T00:00:00-04:00	The start time of the query range in ISO8601 format, now only hourly rounding time supported, for example 2015-08-01T00:30:00-04:00 is not eligible. start\_time requires end\_time if provided. start/end\_time and time\_preset are mutually exclusive.
end\_time	e.g. 2015-08-01T00:00:00-04:00	The end time of the query range in ISO8601 format, now only hourly rounding time supported, for example 2015-08-01T00:30:00-04:00 is not eligible. end\_time requires start\_time if provided. start/end\_time and time\_preset are mutually exclusive.
time\_increment	hourly, daily	The increment by which data points will be split. “daily” will result in one data point per day.
time\_preset	today, yesterday, last\_week	Mutually exclusive with start/end\_time.
breakdowns	country\_code	A metric to segment the data by. Only one breakdown per request is supported.

7. 응답

HTTP 응답 코드

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

응답 바디

"breakdowns" 파라미터를 통해 요청되는 값에 따라, 국가별로 두 가지 가능한 응답 구조가 있습니다.

세컨드리 트래킹 오퍼가 있는 ad_group의 경우 응답의 "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" 부분의 각 지표는 이중 배열의 형태입니다. 첫 번째 요소는 기간에 대한 시간(초)이고 두 번째 요소는 해당 기간에 대한 지표 값입니다.

위의 예에서 "time_increment" 파라미터는 "daily"로 설정되어 하루에 하나의 데이터 포인트가 있습니다.

** 오류 본문 **

오류 본문은 다음 같은 형식으로 422 응답 코드와 함께 리턴됩니다.

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

Insights 리포팅 API
1. 개요
2. Insights 엔드포인트
3. 액세스 요청
4. 인증 및 승인
5. 예제 요청 스크립트
6. 요청 파라미터
7. 응답