开发者示例

1. 测试您的身份验证

要测试您的身份验证，您可以运行这个简单的查询，该查询将列出有关您的前 3 个应用程序的一些简要信息：

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

2. 创建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，默认即可。 （更多：[虚拟货币]（https://dev.tapjoy.com/en/support/Virtual-Currency-Overview））

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的同时为这个Placement创建一个广告内容contents。

广告内容定义了要展示的广告类型，以及 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

eCPM底价以美元为单位，因此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
        }
      }
    }
  }
}

您稍后将使用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 的 Publisher API 是原子的。 这意味着如果您在单个查询中执行多个操作，则如果任何组成步骤失败，则整个查询将失败。 例如，如果您尝试更新 4 个广告内容上的 eCPM 设置，并且其中一个 ID 出现拼写错误，则整个操作将失败并且不会进行任何更改。

7. 应用状态

如果您想查看应用的当前设置，只需查询其展示位置列表以及您感兴趣的属性：

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