开发者API介绍

1. 入门

Tapjoy的Publisher API旨在帮助您快速创建和管理一系列应用程序中的变现。它是用GraphQL编写的，并且需要基于令牌的授权。有关详细信息，请参考这些说明。

如果您打算在短时间内启动许多应用程序，或者希望通过自定义控制管理Tapjoy变现设置，则可能需要使用此API。

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

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

2. 创建App

如果您尚未在控制面板中创建App，首先您可以通过API创建您需要变现的App。

如果您的App尚未在Apple应用商店或者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
    }
  }
}

You can also easily edit existing currencies:

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

4. 创建展示位置和广告内容

接下来，您需要创建一个或多个展示位置。 “展示位置”是应用程序中的特定区域，您可能希望在其中向用户展示Tapjoy广告内容。通过API创建时，您将为每个“展示位置”一起创建“广告内容”。

广告内容定义了要展示的广告类型，以及相关设置（例如eCPM floors）。例如，我们可以将contentType指定为“REWARDED_VIDEO”来设置视频广告，同时为一些国家/地区设置eCPM floors。（当前，API仅支持“HARD” floors）。

广告内容类型

名称	是否可跳过?	是否是激励?	是否是程式化?
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 floors不能适用于程式化广告内容。

非国家代码“XX”用作“世界其他地方”。如果“XX”是唯一的eCPM floor，则该设置将用作全局设置。如果指定了其他国家/地区代码，“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 Floors

您可以很方便的管理广告内容的很多方面，包括eCPM floors.

例如，我们来设置意大利的eCPM floor同时提高日本到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 floor:

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将会返回对应的错误。

TapjoyPublisher API是原子的。这意味着，如果您在单个查询中执行多个操作，则如果任何组成步骤失败，则整个查询将失败。例如，如果您尝试更新4个内容卡上的eCPM floors，并且其中一个ID中有错别字，则整个查询将失败，并且不会进行任何更改。

7. App状态

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

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

开发者API介绍
1. 入门
2. 创建App
3. 创建虚拟货币
4. 创建展示位置和广告内容
5. 管理eCPM Floors
6. 错误处理
7. App状态