パブリッシャー向けの例

1. 認証をテストする

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

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

2. アプリの作成

まだダッシュボードでアプリを設定していない場合、本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を得る事が出来ます。

アプリ内でユーザーに仮想通貨を表示しない場合、必要な設定はapp 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. プレイスメントとコンテントカードの作成

次に、プレイスメントを一つ以上作る必要があります。プレイスメント(Placement) はTapjoyのコンテンツをユーザーに表示するための、アプリケーションで使用する特定の場所です｡ 本APIを使用して作成した場合、各 Placement とともにコンテンツカード content も作成する事になります。

コンテンツカードは、eCPMフロア値などの強力な設定とともにどのような種類の広告を表示するかを指定するものです。例えば、コンテンツ種別(contentType) を REWARDED_VIDEO と指定すれば動画はスキップができなくなり、国別のeCPMフロアを同時に設定することも可能です。(現時点では本APIは HARD eCPMフロアのみをサポートしています)

コンテンツ種別

値	スキップ可能?	リワード?	プログラマティック(bidding)?
PROGRAMMATIC_REWARDED_VIDEO	いいえ	はい	はい
PROGRAMMATIC_INTERSTITIAL_VIDEO	はい	いいえ	はい
REWARDED_VIDEO	いいえ	はい	いいえ
INTERSTITIAL_VIDEO	はい	いいえ	いいえ

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

eCPM フロア値はプログラマティック(bidding)コンテントカードには適用されない事にご留意ください。

実在の国コードではない 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
        }
      }
    }
  }
}

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は原子的です。つまり、一つのクエリで複数のアクションを実行した場合､含まれるどれか一つのステップが失敗した場合にはクエリ全体が失敗します。例えば、4つのコンテンツカードについてeCPMフロアを設定しようとした場合に、IDのどれか一つにでも入力間違いがあればクエリ全体が失敗し、いかなる変更も反映されません。

7. アプリの状態

現状のアプリの設定を確認したい場合は、アプリのプレイスメントのリストと、取得したい属性値に対してクエリを行って下さい:

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