Publisher API Overview

1. 시작하기

탭조이의 퍼블리셔 API는 앱 포트폴리오의 수익 창출 전략을 빠르게 설계하고 관리 할 수 있도록 도와줍니다. API는 GraphQL로 작성되었으며 토큰 기반 인증이 필요합니다. 자세한 내용은 이 항목을 참고해주세요.

짧은 시간 내에 많은 앱을 출시 할 계획이거나 자체 대시 보드를 통해 탭조이 수익화 설정을 관리하려는 경우 이 API를 사용할 수 있습니다.

다음 예시는 인증을 테스트하기 위해 처음 3개 앱에 대한 간단한 정보를 조회하는 쿼리입니다.

query apps {
  publisher {
    apps(first: 3) {
      nodes {
        id
        name
        sdkApiKey
        realWorldCurrency
        timezone        
      }
    }
  }
}

2. Creating an App

아직 대시 보드를 사용하여 앱을 설정하지 않은 경우, API의 첫 번째 단계는 수익을 창출 할 앱을 만드는 것입니다. 앱이 아직 App Store 또는 Google Play 스토어에 게시되어 있지 않아도 걱정하지 마세요. storeUrl, orientation와 함께 몇가지 파라미터는 선택 사항입니다.

mutation createPublisherAppWithStoreUrl {
  createPublisherApp(input: {
    name: "App Created With Store URL",
    platform: ANDROID,
    storeUrl: "https://play.google.com/store/apps/details?id=com.tapjoy.tapout&gl=us",
    orientation: PORTRAIT
  }) {
    app {
      id
      name
      timezone
      realWorldCurrency
    }
  }
}

mutation createPublisherAppWithoutStoreUrl {
  createPublisherApp(input: {
    name: "App Created WithOUT Store URL",
    platform: ANDROID,
    orientation: PORTRAIT,
    currency: KRW,
    timezone: TOKYO_SEOUL
  }) {
    app {
      id
      name
	  timezone
      realWorldCurrency
    }
  }
}

3. 가상화폐 생성

Tapjoy로 수익을 창출하려면 앱 자체가 사용자에게 가상 화폐를 노출하지 않더라도 가상 화폐를 생성해야합니다. 앱과 가상화폐 사이에는 일대다 관계가 있을 수 있습니다. 하지만 앱이 적어도 하나의 가상화폐는 가지고 있어야 합니다.

가상화폐는 광고의 매우 중요한 설정을 포함합니다. 가상화폐 생성 시 설정하는 제한연령에 따라 콘텐츠 노출에 연령제한이 적용됩니다. 여러분의 카운트 매니저가 연령제한에 대한 자세한 내용을 답할 수 있지만, 일반적으로 앱의 연령제한 등급과 유사한 가상화폐 연령제한 등급 선택하면 사용자에게 적합한 콘텐츠를 표시하면서 가능한 가장 높은 eCPM을 유도 할 수 있습니다.

앱이 사용자에게 가상화폐를 노출하지 않는 경우 앱 ID, 통화 이름, 환율 및 제한등급만 제공하면됩니다. 환율이 상관 없다면 기본값인 100을 설정하면 됩니다. (자세한 내용: 가상화폐)

mutation createCurrency {
  createCurrency(input: {
    appId: "<PASTE_YOUR_APP_ID_HERE>",
    name: "New Virtual Currency",
    exchangeRate: 100,
    maturity: MEDIUM
  }) {
    currency {
      id
      name
      exchangeRate
      initialBalance
      maturity
    }
  }
}

기존 가상화폐를 쉽게 편집 할 수도 있습니다.

mutation updateCurrency {
  updateCurrency(input: {
    id: "<CURRENCY_ID>",
    maturity: HIGH,
    name: "Shell Bells",
    initialBalance: 100
  }) {
    currency {
      id
      name
      exchangeRate
      initialBalance
      maturity
      callbackUrl
    }
  }
}

4. 플레이스먼트 및 콘텐츠 카드 생성

다음으로 하나 이상의 '플레이스먼트'를 만들어야합니다. '플레이스먼트'는 애플리케이션에서 사용자에게 탭조이 콘텐츠를 표시하게 해주는 개념적인 컨테이너입니다. API를 통해 '플레이스먼트'를 생성한 후 '콘텐츠' 카드를 생성하게됩니다.

콘텐츠 카드는 최소 eCPM과 같은 강력한 설정과 함께 표시 할 광고 유형을 정의합니다. 예를 들어 contentType을 'REWARDED_VIDEO'로 지정하여 동영상을 건너 뛸 수 없도록하고 국가별 최소 eCPM를 각각 지정할 수 있습니다. (현재 API는 'HARD' 설정만 지원합니다.)

콘텐츠 종류

Name	Skippable?	Rewarded?	Programmatic?
PROGRAMMATIC_REWARDED_VIDEO	No	Yes	Yes
PROGRAMMATIC_INTERSTITIAL_VIDEO	Yes	No	Yes
REWARDED_VIDEO	No	Yes	No
INTERSTITIAL_VIDEO	Yes	No	No

최소 CPM 설정은 미국 달러를 사용합합니다. (5.5 = $5.50).

최소 eCPM은 프로그래매틱 방식 콘텐츠 카드에는 적용 할 수 없습니다.

컨트리 코드 사용 시 XX는 “모든 지역”을 의미합니다.. XX 코드가 최소 eCPM 설정으로 사용되었다면, 이는 글로벌 설정으로 적용됩니다.다른 국가 코드가 지정된 경우 'XX' 코드는 다른 국가 설정을 제외한 다른 모든 국가를 포괄합니다.

mutation createPlacementAndContent {
  createPlacementsAndContents(input: {entries: [
    {
      appId: "<PASTE_YOUR_APP_ID_HERE>",
      placementName: "Placement from API",
      contentType: REWARDED_VIDEO,
      ecpmSettingsToAdd: [
        { price: 5.5, country: "US" },
        { price: 6.5, country: "KR", cpmFloorType: HARD },
        { price: 7.5, country: "JP", cpmFloorType: HARD },
        { price: 7.5, country: "CA", cpmFloorType: HARD }
      ]
    }
  ]}) {
    placements {
      id
      name
      description
      contents {
        id
        name
        type
        isSkippable
        ecpmSettings {
          price
          country
          cpmFloorType
        }
      }
    }
  }
}

place.id 및 content.id를 사용하여 나중에 각각의 플레이스먼트와 콘텐츠를 관리하게 됩니다.

5. 최소 eCPM 관리

최소 eCPM을 포함하여 콘텐츠 카드의 여러 설정을 쉽게 업데이트 할 수 있습니다.

다음 예시는 이탈리아의 최소 eCPM을 제거하고 일본 최소값을 14로 설정하는 내용입니다.

mutation updatePlacementAndContent {
  updatePlacementsAndContents(input: { entries: [
    {
      placementId: "<PLACEMENT ID>",
      contentId: "<CONTENT CARD ID>",
      ecpmSettingsToUpdate: [
        {country: "JP", price: 14.0}
      ],
      ecpmSettingsToDelete: [
        {country: "IT"}
      ]
    }
  ]}) {
    placements {
      id
      contents {
        id
        ecpmSettings {
          price
          country
        }
      }
    }
  }
}

새로 최소 eCPM을 쉽게 추가할 수 도 있습니다.

mutation updatePlacementAndContent {
  updatePlacementsAndContents(input: { entries: [
    {
      placementId: "<PLACEMENT ID>",
      contentId: "<CONTENT CARD ID>",
      ecpmSettingsToAdd: [
        {country: "ES", price: 7.0}
      ]
    }
  ]}) {
    placements {
      id
      contents {
        id
        ecpmSettings {
          price
          country
        }
      }
    }
  }
}

6. 오류 처리 및 원자성

API는 잘못된 입력이 제공되거나 유효성 검사가 실패하거나 기타 다양한 이유로 오류를 반환합니다.

탭조이의 퍼블리셔 API는 원자적입니다. 즉, 단일 쿼리에서 여러 작업을 수행하는 경우 구성 단계가 실패하면 전체 쿼리가 실패합니다. 예를 들어 콘텐츠 카드 4개의 최소 eCPM을 업데이트하려고 할 때 ID 중 하나에 오타가 있는 경우 전체 쿼리가 실패하고 변경되지 않습니다.

7. 앱 상태

앱의 현재 설정을 확인하려면 관심있는 속성과 함께 플레이스먼트 목록을 쿼리하면됩니다.

query placements {
  publisher {
    placements(appId: "<APP_ID>") {
      id
      name
      contents {
        id
        name
        type
        currencyId
        isSkippable
        ecpmSettings {
          price
          country
          cpmFloorType
        }
      }
    }
  }
}