Publisher Management API 1.1

版本历史

历史	备注
Ver 1.1	版本更新于 2020-06-02 主要更新Flat CPM相关API： Step 4. 创建Placements Step 5. 更新您的Placement (和设置Flat CPM)
Ver 1.0	文档创建于2020-03-05

概览

Vungle Publisher Management API允许您管理您的Vungle Dashboard应用。权限如下：

• 创建，修改 applications并获取其信息。
• 创建，修改placements并获取其信息。

您可以在Vungle Dashboard上查看您的创建的app或者placement。

准备

在使用Publisher Management API之前，请确保：

• 在 Vungle publisher dashboard拥有一个可用的账号
• 通读该API文档
• 使用在本文章附带的Vungle_Publisher_API_v1.1.yaml

API Endpoints

• https://auth-api.vungle.com/login
• https://publisher-api.vungle.com/api/v1/applications

API集成

Step 1. 登陆并获取Token

在您的电脑上使用Terminal，并根据文档，使用curl命令来登陆并获取Token。

• Token有效期为24小时。
• 每一次使用curl命令登陆，都会得到一个新的Token。

curl命令：

curl -X POST "https://auth-api.vungle.com/login" \
-H "accept: application/json" \
-H "vungle-source: api" \
-H "vungle-version: 1" \
-H "Content-Type: application/json" \
-d '{ "username": "your account email", "password": "your account password"}'

示例Token：

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkMWFkYWQyNDU5MzQ0MDAxMjA0Y2UzNSIsImFjY291bnQiOiI1ZDFhZGFkMjQ1OTM0NDAwMTIwNGNlMzMiLCJlbWFpbCI6ImFwaV90ZXN0QHRlc3QuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX0sImZsYXRfY3BtIjp7IndyaXRlIjp0cnVlLCJyZWFkIjp0cnVlfX19LCJyb2xlIjoid3JpdGUiLCJhcGlUb2tlbiI6IjFmMmI3NjcyN2YxMDkwZDliMDFhMmZmNmMwNmYwYmNmIiwiaWF0IjoxNTYyMDUwNDA3LCJleHAiOjE1NjIxMzY4MDd9.L7ooHi4_rMPd26QDTQrsW6jBiFympFM3GDRw3fTXSVs"

Step 2. 用您的Token来调用API

示例curl命令：

curl -X GET "https://publisher-api.vungle.com/api/v1/applications" \
-H "accept: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkZDI2OGM3YTQzMDVhMDAxNzNiYTEyYiIsImFjY291bnQiOiI1ZGQyNjhjN2E0MzA1YTAwMTczYmExMjkiLCJlbWFpbCI6ImFwaV90ZXN0QHRlc3QuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX19LCJwdWIiOnsiYWNjZXNzIjp0cnVlfX0sInJvbGUiOiJ3cml0ZSIsImFwaVRva2VuIjoiMzlkN2I5M2QxNWQxNDM0MjZhYzA1MzlmZDdmNmYwOTUiLCJpYXQiOjE1NzQwNzE2NDcsImV4cCI6MTU3NDE1ODA0N30.sMzguUat2RFJKMp1qx4FW_arTXDejm7ejjmDq_JWzaU"

Token来自 Step 1。

Step 3. 创建Applications

使用API创建Applications。返回数据会包含app名称， platform， Vungle app ID等。详情请查看response body：

Method: POST / applications

请求URL: https://publisher-api.vungle.com/api/v1/applications

示例：

{
  "platform": "ios",
  "name": "string",
  "store": {
    "id": "string",
    "category": "Battle Royale",
    "isPaid": true,
    "isManual": true,
    "url": "string",
    "thumbnail": "string"
  },
  "isCoppa": true
}

curl命令示例：

curl -X POST "https://publisher-api.vungle.com/api/v1/applications" \
-H "accept: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkZDI2OGM3YTQzMDVhMDAxNzNiYTEyYiIsImFjY291bnQiOiI1ZGQyNjhjN2E0MzA1YTAwMTczYmExMjkiLCJlbWFpbCI6ImFwaV90ZXN0QHRlc3QuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJmbGF0X2NwbSI6eyJ3cml0ZSI6dHJ1ZX0sImNwbV9mbG9vciI6eyJyZWFkIjpmYWxzZSwid3JpdGUiOmZhbHNlfX0sInB1YiI6eyJhY2Nlc3MiOnRydWV9fSwicm9sZSI6IndyaXRlIiwiYXBpVG9rZW4iOiIzOWQ3YjkzZDE1ZDE0MzQyNmFjMDUzOWZkN2Y2ZjA5NSIsImlhdCI6MTU4MjcxOTcwMCwiZXhwIjoxNTgyODA2MTAwfQ.4Puf39duKVhGP0wZfWkSGi3fPEnpAzdXSr4Tot8PljQ" -H "Content-Type: application/json" -d "{ \"platform\": \"ios\", \"name\": \"test_app_789\", \"store\": { \"id\": \"string\", \"category\": \"Battle Royale\", \"isPaid\": true, \"isManual\": true, \"url\": \"https://testmyapp.com\", \"thumbnail\": \"string\" }, \"isCoppa\": true}"

Response body:

{
  "isCoppa": true,
  "name": "Test_Creating_an_application",
  "platform": "ios",
  "store": {
    "category": "",
    "id": "1234567890",
    "isManual": true,
    "isPaid": false
  },
  "id": "5e56099c57d130000137da68",
  "owner": "5dd268c7a4305a00173ba129",
  "status": "test",
  "vungleAppId": "5e56099c57d130000137da68",
  "connection": "all",
  "defaultPlacement": "5e56099c57d130000137da6a",
  "forceView": {
    "nonRewarded": false,
    "rewarded": true
  },
  "maxVideoLength": 46,
  "minOs": 6,
  "orientation": "both",
  "tagFilters": {
    "blacklist": null
  },
  "testDevices": []
}

Step 4. 创建Placements

使用API创建Placements。返回数据会包含placement名称， placement ID,，Vungle app ID,，placement reference ID等。详情请查看response body：

Method: POST / placements

请求URL: https://publisher-api.vungle.com/api/v1/placements

示例：

{
  "application": "5e560cbb57d130000137da72",
  "name": "placement_creat_test_1",
  "type": "interstitial",
  "allowEndCards": true,
  "isSkippable": true
}

• 为了创建某个app下的placement，请使用app的vungleAppId。
• 对于非banner placements，您不需要传入 adRefreshDuration: 字段。在banner placement时，传入该字段值时，请确保该值大于等于10。

curl命令示例：

curl -X POST "https://publisher-api.vungle.com/api/v1/placements" \
-H "accept: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhMGIwM2RjMzM2NzUxMDAxMThiYWZhZSIsImFjY291bnQiOiI1YTBiMDNkYzMzNjc1MTAwMTE4YmFmYWQiLCJlbWFpbCI6Imhhbi5saUB2dW5nbGUuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX0sImZsYXRfY3BtIjp7IndyaXRlIjp0cnVlfX0sImFjY2Vzcy1ncm93LXZ1bmdsZS1jb20iOnRydWUsImFkbWluIjp7ImZsYXQtY3BtIjp0cnVlfSwiYWNjZXNzIjp7Im1pc3Npb24tY29udHJvbCI6dHJ1ZX0sImltcGVyc29uYXRlIjp0cnVlLCJnb2Rtb2RlIjp0cnVlfSwicm9sZSI6InZ1bmdsZXIiLCJhcGlUb2tlbiI6IjdiOGE3MmUyMjJlYzk0NjUzMDgyYjNlNDI1NTJhY2UxIiwiaWF0IjoxNTg5NTMyNzc5LCJleHAiOjE1ODk2MTkxNzl9.UGpsL8-6TvHzNg3DKTgjXWbqUzCC_z8iSwyz4mfOC0o" \
-H "Content-Type: application/json" \
-d "{ \"application\": \"5ebe5918c41de60001bbd250\", \"name\": \"api_inter_placement_20200515\", \"type\": \"interstitial\", \"allowEndCards\": true, \"isSkippable\": true, \"cpmFloor\": { \"default\": 0, \"geo\": { \"additionalProp1\": 0, \"additionalProp2\": 0, \"additionalProp3\": 0 } }, \"flatCPM\": { \"default\": 20, \"geo\": { \"CN\": 18, \"US\": 19, \"JP\": 20 } }, \"isFlatCPMEnabled\": true, \"banner\": { \"adRefreshDuration\": 10, \"isRefreshEnabled\": true }}"

Response body:

{
  "allowEndCards": true,
  "application": {
    "isCoppa": true,
    "name": "test_app_20200515",
    "platform": "ios",
    "store": {
      "category": "",
      "id": "string",
      "isManual": true,
      "isPaid": false
    },
    "id": "5ebe5918c41de60001bbd250",
    "mutable": false,
    "owner": "5a0b03dc33675100118bafad",
    "status": "test",
    "vungleAppId": "5ebe5918c41de60001bbd250"
  },
  "id": "5ebe59be5e11600001aa6454",
  "isSkippable": true,
  "mutable": true,
  "name": "api_inter_placement_20200515_2",
  "referenceID": "API_INTER_PLACEMENT_20200515_2-2202429",
  "status": "active",
  "type": "interstitial",
  "banner": {
    "adRefreshDuration": 10,
    "isRefreshEnabled": true
  },
  "flatCPM": {
    "default": 22,
    "geo": {
      "CN": 21,
      "JP": 19,
      "US": 20
    }
  },
  "flatCPMCap": {
    "default": 25
  },
  "flatCPMCd": "2020-05-18T08:58:38.646Z",
  "isFlatCPMEnabled": true,
  "videoOrientationOverride": "none"
}

Step 5. 更新您的Placement (并选择性的设置Flat CPM)

使用该API来更新您的Placements设置并设置Flat CPM。返回数据包含placement ID，the Vungle app ID和the placement reference ID等。详情请查看Response body 。

Method: PATCH / placements/{id}

请求URL: https://publisher-api.vungle.com/api/v1/placements/5e560daf57d130000137da76

示例：

{
  "name": "api_inter_placement_20200515",
  "allowEndCards": true,
  "isSkippable": true,
  "_isSkippable": true,
  "videoOrientationOverride": "none",
  "status": "active",
  "banner": {
    "adRefreshDuration": 10,
    "isRefreshEnabled": true
  },
  "flatCPM": {
    "default": 22,
    "geo": {
      "CN": 19,
      "JP": 22,
      "US": 21
    }
  },
  "isFlatCPMEnabled": true
}

• Flat CPM目前只开发给部分的开发者。请联系您的Account Manager来激活Flat CPM。
• Put your placement name in the PATCH call instead of leaving it as "string".

  示例，在API中，用户可以修改placement设置。但是请保证name字段值为String，而非placment名。

  

 

curl命令示例：

curl -X PATCH "https://publisher-qa-api.vungle.io/api/v1/placements/5ebe596c5e11600001aa6452" \
-H "accept: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhMGIwM2RjMzM2NzUxMDAxMThiYWZhZSIsImFjY291bnQiOiI1YTBiMDNkYzMzNjc1MTAwMTE4YmFmYWQiLCJlbWFpbCI6Imhhbi5saUB2dW5nbGUuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX0sImZsYXRfY3BtIjp7IndyaXRlIjp0cnVlfX0sImFjY2Vzcy1ncm93LXZ1bmdsZS1jb20iOnRydWUsImFkbWluIjp7ImZsYXQtY3BtIjp0cnVlfSwiYWNjZXNzIjp7Im1pc3Npb24tY29udHJvbCI6dHJ1ZX0sImltcGVyc29uYXRlIjp0cnVlLCJnb2Rtb2RlIjp0cnVlfSwicm9sZSI6InZ1bmdsZXIiLCJhcGlUb2tlbiI6IjdiOGE3MmUyMjJlYzk0NjUzMDgyYjNlNDI1NTJhY2UxIiwiaWF0IjoxNTkxMjY0NTg4LCJleHAiOjE1OTEzNTA5ODh9.OvZWB386UUoppLwSzqpGC-oQ4aMRV1kJu6t2PGN28jc" \
-H "Content-Type: application/json" -d "{ \"name\": \"string\", \"allowEndCards\": true, \"isSkippable\": true, \"_isSkippable\": true, \"videoOrientationOverride\": \"none\", \"status\": \"active\", \"banner\": { \"adRefreshDuration\": 10, \"isRefreshEnabled\": true }, \"flatCPM\": { \"default\": 25, \"geo\": { \"CN\": 21, \"JP\": 22, \"US\": 23 } }, \"isFlatCPMEnabled\": true}"

Response body:

{
  "allowEndCards": true,
  "application": {
    "isCoppa": true,
    "name": "test_app_20200515",
    "platform": "ios",
    "store": {
      "category": "",
      "id": "string",
      "isManual": true,
      "isPaid": false
    },
    "id": "5ebe5918c41de60001bbd250",
    "mutable": false,
    "owner": "5a0b03dc33675100118bafad",
    "status": "test",
    "vungleAppId": "5ebe5918c41de60001bbd250"
  },
  "id": "5ebe596c5e11600001aa6452",
  "isSkippable": true,
  "mutable": true,
  "name": "api_inter_placement_20200515",
  "referenceID": "API_INTER_PLACEMENT_20200515-2630554",
  "status": "active",
  "type": "interstitial",
  "banner": {
    "adRefreshDuration": 10,
    "isRefreshEnabled": true
  },
  "flatCPM": {
    "default": 22,
    "geo": {
      "CN": 19,
      "JP": 22,
      "US": 21
    }
  },
  "flatCPMCap": {
    "default": 25
  },
  "flatCPMCd": "2020-05-25T04:33:01.856Z",
  "isFlatCPMEnabled": true,
  "videoOrientationOverride": "none"
}

其他API

获取Application

Method: GET /applications/{id}

请求URL: https://publisher-api.vungle.com/api/v1/applications/5e65ebcd688ef40001e7f436

curl命令示例：

curl -X GET "https://publisher-api.vungle.com/api/v1/applications/5e65ebcd688ef40001e7f436" \
-H "accept: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhMGIwM2RjMzM2NzUxMDAxMThiYWZhZSIsImFjY291bnQiOiI1YTBiMDNkYzMzNjc1MTAwMTE4YmFmYWQiLCJlbWFpbCI6Imhhbi5saUB2dW5nbGUuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX19LCJhY2Nlc3MtZ3Jvdy12dW5nbGUtY29tIjp0cnVlLCJnb2Rtb2RlIjp0cnVlLCJpbXBlcnNvbmF0ZSI6dHJ1ZSwiYWNjZXNzIjp7Im1pc3Npb24tY29udHJvbCI6dHJ1ZX19LCJyb2xlIjoidnVuZ2xlciIsImFwaVRva2VuIjoiN2I4YTcyZTIyMmVjOTQ2NTMwODJiM2U0MjU1MmFjZTEiLCJpYXQiOjE1ODM3Mzc2NDgsImV4cCI6MTU4MzgyNDA0OH0.EFtjHvwusymKq5jwoFemDEBexJUzExNlwtVYApY5if0"

Response body:

{
  "isCoppa": true,
  "name": "test_app_hanli_api_production",
  "platform": "ios",
  "store": {
    "category": "",
    "id": "string",
    "isManual": true,
    "isPaid": false
  },
  "id": "5e65ebcd688ef40001e7f436",
  "owner": "5a0b03dc33675100118bafad",
  "placement_count": 1,
  "status": "test",
  "vungleAppId": "5e65ebcd688ef40001e7f436",
  "connection": "all",
  "forceView": {
    "nonRewarded": false,
    "rewarded": true
  },
  "maxVideoLength": 46,
  "minOs": 6,
  "orientation": "both",
  "tagFilters": {
    "blacklist": []
  },
  "testDevices": []
}

获取Placement

Method: GET/ placements/{id}

请求URL: https://publisher-api.vungle.com/api/v1/placements/520d751489e451af34000028

curl命令示例：

curl -X GET "https://publisher-api.vungle.com/api/v1/placements/520d751489e451af34000028" \
-H "accept: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhMGIwM2RjMzM2NzUxMDAxMThiYWZhZSIsImFjY291bnQiOiI1YTBiMDNkYzMzNjc1MTAwMTE4YmFmYWQiLCJlbWFpbCI6Imhhbi5saUB2dW5nbGUuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX19LCJhY2Nlc3MtZ3Jvdy12dW5nbGUtY29tIjp0cnVlLCJnb2Rtb2RlIjp0cnVlLCJpbXBlcnNvbmF0ZSI6dHJ1ZSwiYWNjZXNzIjp7Im1pc3Npb24tY29udHJvbCI6dHJ1ZX19LCJyb2xlIjoidnVuZ2xlciIsImFwaVRva2VuIjoiN2I4YTcyZTIyMmVjOTQ2NTMwODJiM2U0MjU1MmFjZTEiLCJpYXQiOjE1ODM3Mzg2NTYsImV4cCI6MTU4MzgyNTA1Nn0.oJH2btCK_54C64s25Ls-Ez4pp0DZG4WudXS3YL32-NE"

Response body:

{
  "application": {
    "platform": "ios",
    "name": "string",
    "store": {
      "id": "string",
      "category": "Battle Royale",
      "isPaid": true,
      "isManual": true,
      "url": "string",
      "thumbnail": "string"
    },
    "isCoppa": true,
    "id": "520d751489e451af34000028",
    "vungleAppId": "string",
    "owner": "string",
    "placement_count": 0,
    "status": "active"
  },
  "name": "string",
  "type": "interstitial",
  "allowEndCards": true,
  "isSkippable": true,
  "referenceID": "string",
  "id": "520d751489e451af34000028",
  "status": "active",
  "videoOrientationOverride": "none",
  "defaultCPMFloor": 0,
  "defaultFlatCPM": 0,
  "isFlatCPMEnabled": true,
  "geoConfigs": {
    "additionalProp1": {
      "cpm_floor": 0,
      "flat_cpm": 0
    },
    "additionalProp2": {
      "cpm_floor": 0,
      "flat_cpm": 0
    },
    "additionalProp3": {
      "cpm_floor": 0,
      "flat_cpm": 0
    }
  },
  "isRefreshEnabled": true,
  "adRefreshDuration": 0
}

最佳实现

阅读文档

阅读Vungle Publisher API YAML文件，同时阅读整篇Publisher Management API文档。

Optional Fields

有些字段，如果是非必须的，则会在Vungle Publisher API YAML文件中用 x-omitempty 或 x-nullable标识。如果你不传值，则默认为Flase，NULL或0。

非必须字段 (x-omitempty 和 x-nullable):

  nonRewarded:
    type: boolean
    x-omitempty: false
minOs:
  type: number
          
maxVideoLength:
  type: integer
  minimum: 15
  maximum: 60
  x-nullable: true

修改设置

为了通过API来修改设置，我们强烈建议使用GET 方法来获取数据，然后修改后通过API来修改设置。

设置Flat CPM（请联系Account Manager）

• 请联系Account Manager来开启Flat CPM。
• 通过API来设置Flat CPM。非必须字段在Vungle Publisher API YAML文件中用x-omitempty 或 x-nullable 标识。
• 当创建Placement时，Flat CPM默认是关闭状态的。要开启Flat CPM，请按照Step 5 来操作。
• 要修改设置，请查阅Editing or Updating Fields。