パブリッシャAPIの概要

1. はじめに

TapjoyのパブリッシャAPIは、パブリッシャがもつアプリたちのマネタイゼーションの設定を素早く作成し、管理できるように設計されています。APIはGraphQLの形式で、トークンベースの認証をし移用します。詳細についてはインストラクションをご参照ください。

このAPIを使えば多数のアプリを短時間で登録したり、Tapjoyのマネタイズをカスタムダッシュボードから設定できるようになります。

認証をテストするには、次の短いクエリを実行してみましょう。これは最初の3つのアプリの簡単な情報を取得するクエリです:

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

2. アプリを登録する

Tapjoyダッシュボードでアプリを登録していない場合、まずこのAPIでマネタイズするアプリを登録します。

アプリがApp StoreやGoogle Play上でLIVEになっていない場合でも、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のマネタイズ機能を使用する場合、ユーザーに残高等を見せない場合でも仮想通貨を登録する必要があります。一つのアプリには複数の仮想通貨を登録できますが、かならず一つは登録する必要があります。

仮想通貨の設定には広告において非常に重要なものがあります。それはアプリに表示される広告の年齢制限(maturity)です。年齢制限に関する詳細はアカウントマネージャがお答えいたしますが、一般的には仮想通貨の年齢制限(maturity)の設定をアプリのプラットフォームの年齢制限設定と同様のものにすることで、ユーザーにとって適切なコンテンツを表示しつつeCPMを高く保てるようになります。

ユーザーに仮想通貨の内容を見せない場合、appId、仮想通貨の名前(name)、還元率(exchangeRate)および年齢制限(maturity)のみが必要な値です。還元率を特に設定する必要がない場合、デフォルト値の 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で作成された場合、contentsというコンテンツカードも作られそれぞれのPlacementに追加されます。

コンテンツカードはどういった種類の広告を見せるのかを、eCPMフロア等の強力な設定と共に決めるものです。例えば、コンテンツ種別(contentType)を REWARDED_VIDEO と指定して途中スキップのできない動画で、国別のeCPMフロア設定をしたコンテンツを作成できます。(現在のAPIでは、HARD eCPMフロアのみをサポートします)

コンテンツの種類

名前	スキップ可能?	リワード付?	プログラマティック?
PROGRAMMATIC_REWARDED_VIDEO	No	Yes	Yes
PROGRAMMATIC_INTERSTITIAL_VIDEO	Yes	No	Yes
REWARDED_VIDEO	No	Yes	No
INTERSTITIAL_VIDEO	Yes	No	No

CPMフロアの値はUSDで設定します。つまり、5.5 の設定値は $5.50 となります。

プログラマティックコンテンツカードにはeCPMフロア設定ができない点にご注意ください。

特別な国コード(country)XXは "指定した国以外のすべての国"を意味します。このため、XXに対してのみ eCPMフロア設定がされていた場合、全世界に対するフロア設定として動作します。それ以外の国コード(country)が指定されていた場合、 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
        }
      }
    }
  }
}

戻り値の placement.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は入力値が不正だった場合、検証が失敗した場合、その他何らかの問題があった場合はエラーを返します。

Tapjoy の パブリッシャAPI は原子的(atomic)に動作します。 つまり、一つのクエリで複数のアクションを実行する際に、どれかの構成要素が失敗した場合にはクエリ全体が失敗します。例えば、4つのコンテンツカードについてそれぞれeCPMを変更しようとしたときに、IDを一つだけ間違えた場合には、すべてのクエリが失敗して変更は行われません。

7. アプリの状態

アプリの現在の設定を確認したい場合、プレイスメントのリストと必要な属性をクエリに含めます:

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