빠른 시작

빠른 시작

GraphQL 리포팅 API 는 광고주와 퍼블리셔에게 리포트 데이터에 접근할 수 있도록 하는 Tapjoy 플랫폼 입니다. GraphQL 리포트 API 내 마케팅 API를 통한 광고주의 케이스에 대하서는 이 링크를 참조해 주시길 바랍니다. 퍼블리셔의 사용자 케이스는 퍼블리셔 API 항목이 설명된 이 링크에서 확인하실 수 있습니다.

1. 인증

마켓팅 퍼블리셔 API 에 접근하기 위해서는 먼저 API Key 가 필요합니다. Ad 대시보드 사용자의 경우 이 링크에서 key 를 확인할 수 있습니다. https://dashboard.tapjoy.com/reporting/api

LTV 플랫폼 사용자라면 마케팅 API Key 가 필요하며 이는 LTV 플랫폼에서 확인하실 수 있습니다. 이 키는 App -> Settings -> App Settings -> App Info -> API Keys -> Marketing API Key 를 통해 확인하실 수 있습니다.

API 요청은 표준 two-legged OAuth2 를 사용하여 인증합니다. 모든 토큰은 API Key 를 통해 요청되며 이를 통해 받은 토큰은 향후 요청시 인증을 위해 사용합니다.

인증 토큰을 발급받는 방법은 이 링크를 참고해 주시길 바랍니다..

2. GraphQL 엔드포인트

API 는 하나의 엔드포인트만 존재합니다.

https://api.tapjoy.com/graphql

엔드포인트는 어떠한 작업을 요청하더라도 변경되지 않습니다.

3. GraphQL 연결

인증 토큰 발급이 완료되면 API를 통해 요청할 수 있습니다. API 요청을 위해서는 HTTP POST 로 JSON 형식의 Body 로 요청하셔야 합니다.

예시:

POST /graphql
Host: api.tapjoy.com
Authorization: Bearer <OAuth Token>

{
  "query": "query { user { firstName } }"
}

4. 에러 관리

API 사용시 다음 항목의 에러가 나오는 상황이 있을 수 있습니다.

1. 서버 / 네트워크 에러
2. 인증 관련 에러
3. 쿼리 구문 관련 에러
4. 데이터 관련 에러

API 가 정상적으로 연동된 것인지 확인하기 위해서는 이들 항목의 에러에 대하여 관린해야할 필요가 있습니다.

각각의 항목에 대해서는 아래의 쿼리를 기준으로 설명할 것입니다.

query {
  user {
    firstName
    lastName
  }
}

서버 / 네트워크 에러

간혈적으로 복구할 수 없는 서버 / 네트워크 에러가 API 를 통해 발생할 수 있습니다. 이 경우 API를 통해 전달받은 http 상태 코드에 따라 시나리오를 새워 대응할 수 있습니다. 예를 들어 API 에 문제가 생겨 쿼리 실행을 막는다면 HTTP 500 상태 코드를 받아 대응할 수 있습니다.

아 시나리오에서 가장 좋은 대응 방법은 API 호출을 재시도 하는 것입니다.

인증 관련 에러

인증과 관련된 에러는 아래와 같은 이유로 발생합니다.

• OAuth token 기한 만료
• 잘못된 OAuth token
• 인증 관련 시스템 오류

이 상황이 발생했을 경우 HTTP 200 OK 응답과 함께 아래의 데이터를 받습니다.

{
  "errors": [
    {
      "message": "Authentication could not be verified. Please try again later.",
      "code": 403
    }
  ]
}

• message - 에러 관련 설명 메시지
• code - HTTP 상태 코드

이 시나리오에서 가장 좋은 대응 방법은 새로운 토큰을 발급받고 API를 재시도 하는 것입니다.

쿼리 구문 에러

모든 쿼리는 구문이 정확한지 여부 및 데이터 스키마를 따르는지 사전에 검증됩니다. 만약 해당 쿼리가 스키마 검증을 통과하지 못할 경우 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 문서를 기준으로 쿼리를 테스트하는 것입니다. 온라인 도구.

데이터 관련 에러

API 와 관련한 모든 설정을 완료하였더라도 여저히 에러가 발생할 수 있습니다. 예를 들어 여러분이 광고주이고 아래 API 를 통해 AdSet의 최소 비딩 값을 설정한다고 가정해 봅시다.

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 상태 코드

이 시나리오에서 가장 좋은 대응방법은 사용자에게 해당 필드 (경로값)에 대한 메세지를 확인 후 수정하는 것입니다.