KOR리포트 API 사용 예시
마지막 업데이트: 12/11/2024
광고주와 퍼블리셔는 리포트 API를 통해 Tapjoy 플랫폼 내 리포트 데이터와 오퍼월 콘텐츠를 GraphQL를 통해 관리할 수 있습니다. GraphQL에 대한 자세한 내용은 GraphQL website를 참고하시길 바랍니다.
API Explorer를 이용하시면 쿼리를 만드는데 도움을 받을 수 있습니다. 화면 좌측 책 아이콘을 클릭하면 쿼리와 관련한 자세한 정보와 문서를 확인하실 수 있습니다.
1. API 엔드포인트
리포트 API는 하나의 엔드포인트로 설정되어 있습니다.
https://api.tapjoy.com/graphql
이 API는 어떤 작업을 진행하든 동일하게 적용됩니다.
2. API와 통신하기
토큰을 발급받으시면 API를 통한 통신이 가능합니다. API요청을 생성하기 위해서는 JSON body 와 POST를 통해 요청을 주셔야 합니다.
예시:
POST /graphql
Host: api.tapjoy.com
Authorization: Bearer <OAuth Token>
{
"query": "query { user { firstName } }"
}
3. 에러 관리
API 사용시 다양한 카테고리의 에러가 발생할 수 있습니다.
- 서버 / 네트워크 에러
- 인증 에러
- 쿼리 관련 에러
- 데이터 관련 에러
시스템 내 API가 적절히 연동되었는지 확인하기 위해서는 해당 카테고리의 에러에 대해 대비가 되어있어야 합니다.
주의: 만약 단일 쿼리로 여러 액션을 실행하고자 할 경우 하나의 에러만 발생해도 쿼리가 종료됩니다.
각 카테고리에 대한 설명은 아래의 예시 쿼리를 기준으로 설명합니다.
query {
user {
firstName
lastName
}
}
서버 / 네트워크 에러
간혈적으로 도저히 해결할 수 없는 서버 / 네트워크 에러를 경험하실 수 있습니다. 이 경우 API를 통해 시나리오 별 http response code 를 받을 수 있습니다. 예를 들어 API가 해당 쿼리의 실행을 막은 경우 http response code 500을 받을 수 있습니다. 이 시나리오에서 가장 좋은 해결방법은 쿼리를 다시 설정 후 API를 다시 요청하는 것입니다.
인증 에러
인증 관련 에러는 아래의 이유로 나타압니다.
- OAuth 토큰 만료
- OAuth 토큰 이상
- Tapjoy 내 인증 관련 이슈
이 경우 아래와 같이 http 200 OK 와 함께 아래의 메시지를 받게 됩니다.
{
"errors": [
{
"message": "Authentication could not be verified. Please try again later.",
"code": 403
}
]
}
message- 에러 관련 상세 메시지code- http 응답 코드
이 경우 토큰을 새로 발급받아 새로 요청을 진행해 보십시오.
쿼리 관련 에러
모든 쿼리는 데이터 스키마를 통해 검증을 받습니다. 만약 해당 쿼리가 검증을 통과하지 못한 경우 http 200 OK 와 함께 아래와 같은 메시지를 받게 됩니다.
{
"errors": [
{
"message": "Field 'user' doesn't exist on type 'Query'",
"locations": [
{
"line": 2,
"column": 3
}
],
"fields": [
"query",
"user"
]
}
]
}
message- 에러 관련 상세 메시지locations- 에러 관련 위치fields- 해당 에러가 적용된 곳
이에 대한 해결책으로 API문서를 참고하여 해당 쿼리의 스키마 및 데이터 관련 내용을 확인 후 다시 쿼리를 생성하여 요청하는 것입니다. Interactive Explorer.
데이터 관련 에러
쿼리의 데이터 스크마 관련 모든 검증을 거쳤음에도 비지니스 로직에 의한 에러가 발생할 수 있습니다. 예를 들어 아래롸 같이 광고주가 비딩가를 수정하고자 하는 경우.
mutation {
updateAdSet(input: {
id: "00000000-0000-0000-0000-000000000000",
bidding: {amount: 10000}
}) {
adSet {
id
}
}
}
이 시나리오에서는 http 200 Ok 와 함께 아래의 메시지를 받게 됩니다.
{
"data": {
"updateAdSet": null
},
"errors": [
{
"message": "Amount is below the minimum (20000 micros)",
"locations": [
{
"line": 2,
"column": 3
}
],
"path": [
"updateAdSet",
"input",
"bidding",
"amount"
],
"code": 422
}
]
}
message- 에러 관련 상세 메시지locations- 에러 관련 위치path- 에러가 발생한 레퍼런스 위치code- GraphQL HTTP status codes
이 시나리오의 경우 메시지를 참고하여 에러가 발생한 데이터 스키마의 값을 수정하는 것입니다.
4. 제한사항
리포트 API는 API의 과도한 혹은 불법적인 사용을 막기위해 일부 제한사항을 두고 있습니다. 이러한 제한사항에 대해 일부 해지를 하고자 하시는 경우 Tapjoy 어카운트 메지너를 통해 연락을 주시길 부탁드립니다. 아래의 예시는 광고주에 대한 예시이나 퍼블리셔에게도 동일하게 적용됩니다.
데이터 제한
리포트 API는 최대 2년치의 데이터를 가져올 수 있습니다.
페이징
쿼리를 페이징하고자하는 경우:
firstorlast필요- 한 페이지에 최대 100개 까지의 노드를 설정 가능
최대 한도 이상으로 쿼리가 발생할 경우 first / last 요청은 무시되며 데이터 역시 일부 누락된체 전달 됩니다.
예시:
{
advertiser {
adSets(first: 50) {
edges {
node {
id
name
ads(first: 50) {
edges {
node {
id
name
}
}
}
}
}
}
}
}
이 쿼리에서는 첫 50개의 에드셋이 50개의 광고를 통해 데이터가 표시됩니다.
이에 대한 페이징을 하고자 하는 경우 after 또는 before가 아래 예시와 같이 추가합니다.
{
advertiser {
adSets(first: 50, after: "Mg==") {
edges {
node {
id
name
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
위의 쿼리는 "Mg=="라는 커서 위치에서 시작하여 최대 50개의 광고 세트를 반환합니다. 이 위치는 이전 쿼리에서 반환된 endCursor를 기반으로 결정됩니다. hasNextPage가 false일 때 페이징이 완료된 것으로 간주해야 합니다. 페이징과 관련한 자세한 사항은 GraphQL website 참고 부탁드립니다..
복잡도
스키마 검증을 통과하려면 모든 API 호출은 10,000 "호출"을 초과해서는 안 됩니다. 여기서 "호출"은 리소스 요청을 의미합니다. GraphQL은 여러 호출을 단일 쿼리로 결합할 수 있으므로, API는 쿼리가 실행되기 전에 단일 쿼리에 대한 총 호출 수를 미리 계산합니다.
호출 수는 결과에서 선택된 리소스 수(예: 캠페인, 광고 세트, 광고, 앱, 인사이트 등)와 대략적으로 동일합니다 예시 :
{
advertiser {
adSets(first: 50) { # <= 50 calls
edges {
node {
id
name
ads(first: 50) { # <= 50 calls
edges {
node {
id
name
}
}
}
}
}
}
}
}
이 예시에서 한 번에 최대 50개의 광고 세트를 요청하고 있으며, 각 광고 세트에 대해 최대 50개의 광고를 요청하고 있습니다.
총 호출 수를 계산하면:
50 = 50 ad sets
+
50 x 50 = 2500 ads
= 2550 calls
분석 복잡성
어느 수준에서든 리포트 인사이트를 쿼리할 경우 기본 계산에 반영되지 않은 추가 복잡도 비용이 발생합니다. 쿼리되는 각 날짜에 대해 계산에 1회의 추가 호출이 추가됩니다. 예시:
{
advertiser {
# 50 calls
adSets(first: 50) {
edges {
node {
id
name
# 7 calls
insights(timeRange: {from: "2024-03-01T00:00:00Z", until: "2024-03-08T00:00:00Z"}) {
timestamps
reports {
country
impressions
conversions
spend
}
}
}
}
}
}
}
이에 대한 최종 호출 횟수는
50 = 50 ad sets
+
50 x 7 = 350 insights
= 400 calls