기술 자료

지원

오퍼월

Monetization 시작하기

UA 시작하기

Unity SDK 연동

오퍼월

리포트 API 베스트 프랙티스

탭조이 오퍼월 리포팅 API 엔드포인트, 요청 구조 및 오류 처리를 이해하여 정확한 수익화 데이터에 효과적으로 액세스합니다.
읽는 시간 2분최근 업데이트: 2일 전
리포트 API는 광고주와 퍼블리셔가 GraphQL 쿼리 언어를 사용하여 탭조이 플랫폼의 리포트 데이터에 접근하고 오퍼월 콘텐츠를 관리할 수 있도록 합니다. GraphQL에 대한 자세한 내용은 GraphQL의 공식 웹사이트를 참고하십시오. API 탐색기를 사용하여 쿼리 빌드를 지원할 수 있습니다. 왼쪽 상단의 책 아이콘을 클릭하여 기술 자료 탐색기를 확장하고 쿼리에서 사용할 수 있는 필드 및 메트릭에 대한 정보를 찾습니다.
리포트 API 탐색기에서 책 아이콘을 클릭한 후 표시되는 기술 자료 탐색기 패널

API 엔드포인트

리포트 API 단일 엔드포인트가 있습니다. 
https://api.tapjoy.com/graphql
엔드포인트는 수행되는 작업과 관계없이 동일하게 유지됩니다.

API와의 통신

액세스 토큰이 있으면 API에 요청을 보낼 수 있습니다. API 요청을 구성할 때는 쿼리나 변형을 실행하는지와 관계없이 JSON으로 인코딩된 본문을 HTTP POST를 통해 제공합니다. 요청 예시: 
POST /graphqlHost: api.tapjoy.comAuthorization: Bearer <OAuth Token>{  "query": "query { user { firstName } }"}

오류 처리

API 사용 시 발생할 수 있는 오류는 다음과 같은 범주로 구분됩니다.
  • 서버/네트워크 오류
  • 인증/권한 부여 오류
  • 쿼리 구문 오류
  • 데이터 유효성 검사 오류
시스템이 제대로 통합되도록 하려면, 시스템이 이러한 오류 범주 각각을 어떻게 처리해야 하는지 고려해야 합니다. 아래에 설명된 각 범주는 컨텍스트를 위해 다음 쿼리를 사용합니다. 
query {  user {    firstName    lastName  }}

서버/네트워크 오류

API 사용 중 복구 불가능한 서버/네트워크 오류가 발생할 수 있습니다. 이 경우 해당 시나리오에 맞는 적절한 HTTP 상태 코드가 반환됩니다. 예를 들어, API 문제로 쿼리 실행이 불가능할 경우 500 상태 코드가 포함된 HTTP 응답을 받게 됩니다. 이러한 상황을 처리하는 최선의 방법은 지수적 백오프를 적용한 재시도 동작을 사용하는 것입니다.

인증/권한 부여 오류

인증/권한 부여 오류 다음과 같은 몇 가지 이유로 발생할 수 있습니다.
  • OAuth 토큰이 만료됨
  • OAuth 토큰이 유효하지 않음
  • 기본 인증 시스템에 문제가 발생하고 있음
이러한 유형의 상황에서는 다음과 같은 데이터가 포함된 HTTP 200 OK 응답을 받게 됩니다. 
{  "errors": [    {      "message": "Authentication could not be verified. Please try again later.",      "code": 403    }  ]}
  • message
    - 사람이 이해할 수 있는 오류에 대한 설명
  • code
    - HTTP 상태 코드에 대응하는 GraphQL 상태 코드
이 상황을 처리하는 가장 좋은 방법은 새 액세스 토큰을 요청하고 요청을 다시 시도하는 것입니다.

쿼리 구문 오류

모든 쿼리와 변경 사항은 사전에 구문적으로 올바른지, 그리고 설명된 데이터 스키마를 따르는지 검증됩니다. 제공된 쿼리가 모든 스키마 유효성 검사를 통과하지 못하면, 다음 데이터를 포함한 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 기술 자료를 참고하고 인터랙티브 탐색기에서 쿼리를 테스트하는 것입니다.

데이터 유효성 검사 오류

필수 필드를 모두 포함하여 올바르게 구성된 변형을 제공하더라도 비즈니스 유효성 검사 때문에 실패할 수 있습니다. 예를 들어, 광고주가 다음과 같이 광고 세트의 입찰가를 최소 금액 미만으로 변경한다고 가정해 보겠습니다. 
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
    - HTTP 상태 코드에 대응하는 GraphQL 상태 코드
이 시나리오를 처리하는 가장 좋은 방법은 해당 필드(경로를 통해)와 함께 오류 메시지를 사용자에게 표시하는 것입니다.

제한 사항

리포트 API에는 과도하거나 악의적인 API 호출을 방지하기 위한 특정 보호 장치가 마련되어 있습니다. 연동이 설정된 한도를 초과하는 경우, 탭조이 세일즈 담당자(AM) 또는 지원팀에 문의하여 연동 최적화 방법이나 한도 증액 방법을 확인하십시오. 아래 예시는 광고주 환경을 기준으로 설명되었으나, 퍼블리셔 연동에도 동일하게 적용됩니다.

데이터 보관

리포트 API 지난 2년간의 데이터에 액세스할 수 있습니다.

페이지 매김

페이지 매김된 유형을 쿼리할 때 클라이언트는 다음을 준수해야 합니다. 
  • first
    또는 
    last
    인수 제공
  • 단일 페이지에 100개 노드를 초과하지 않음
최대값이 초과된 경우 결과는 잘려 나오며, 그 결과 요청된 첫 번째/마지막 인수는 무시됩니다. 예제는 아래와 같습니다. 
{  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 웹 사이트에서 확인할 수 있습니다.

호출 복잡도

스키마 유효성 검사를 통과하려면 모든 마케팅 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개의 광고 세트를 요청하고 있습니다. 각 광고 세트에 대해 3가지 지표와 1개의 세그먼트에 걸쳐 7일치 리포팅 데이터를 요청하고 있습니다. 총 호출 횟수를 계산하려면 다음과 같이 합니다. 
50      = 50 ad sets+50 x 7  = 350 insights        = 400 calls