# 广告位 API

> 使用 Placements API 创建、检索、更新或删除广告位，从而管理 AIR app 中的放置/位置配置。

使用此 API 可管理 LevelPlay 帐户中广告单元级别的广告位。此 API 将启用：

* 获取广告位列表的完整详细信息
* 创建新的放置位置，并定义放置/位置广告服务交付设置
* 更新现有广告位
* 删除（存档）广告位

有关更多信息，请参阅[广告位](/grow/levelplay/platform/settings/placements.md)。

> **Note:**
>
> 必须使用 [Bearer API Authentication](/grow/levelplay/platform/api/authentication.md) 对每个 API 请求进行身份验证。

## Get 方法##get-method

### 描述##description

提供放置/位置设置信息

### 请求##request

#### 请求网址示例##request-url-example

\[[https://platform.ironsrc.com/partners/publisher/placements/v1/?appKey=\\](https://platform.ironsrc.com/partners/publisher/placements/v1/?appKey=\\)[REPLACE](https://platform.ironsrc.com/partners/publisher/placements/v1/?appKey=\\\[REPLACE)]

#### 请求参数##request-parameters

| **密钥** | **类型** | **描述**    | **值** | **必需** |
| ------ | ------ | --------- | ----- | ------ |
| appKey | 字符串    | 应用程序唯一标识符 |       | v      |

### 响应##response

#### 响应参数##response-parameters

| **密钥**           | **类型** | **描述**                                        | **必需**    |
| ---------------- | ------ | --------------------------------------------- | --------- |
| adUnit           | 字符串    | ad-unit name: rewardVideo interstitial banner | v         |
| name             | 字符串    | 放置/位置唯一名称                                     | v         |
| id               | 整数     | 放置/位置唯一标识符                                    | v         |
| adDelivery       | 整数     | 如果已开启放置/位置广告投放，则为 1，否则为 0                     | v         |
| itemName         | 字符串    | 奖励名称（最多 30 个字符）                               | v（仅限奖励视频） |
| rewardAmount     | 整数     | 单个广告视图要赠送的商品数量（最多 2000000000）                 | v（仅限奖励视频） |
| capping.已启用      | 整数     | 1 表示启用上限，否则为 0                                |           |
| capping.limit    | 整数     | 每个封顶间隔投放的广告服务的最大数量（最多 1000）                   |           |
| capping.interval | 字符串    | 封顶间隔：d - 天 h - 小时                             |           |
| pacing.已启用       | 整数     | 1 表示启用 pacinhg，否则为 0                          |           |
| pacing.minutes   | 浮点     | 广告投放之间的最小间隔（以分钟为单位）（最大 1000）                  |           |

#### 响应正文示例##response-body-example

```jsonp
[
    {
        "name": "Home_Screen",
        "id": 12,
        "adUnit": "rewardedVideo",
        "itemName":"Coins",
        "rewardAmount":3,
        "adDelivery":1,
        "capping": {
            "enabled":1,
            "cappingLimit":3,
            "cappingInterval": "h"
        },
        "pacing": {
            "enabled":1,
            "pacingMinutes":12.5
        },
        "abVersion":"A"
    }
]
```

## Post 方法##post-method

使用此方法可在应用程序帐户中创建新的广告位，包括设置上限和节奏

广告位是按广告单元类型创建的，每个放置/位置只能按 1 个广告单元添加。API 支持在以下广告单位下创建：

奖励视频广告

* 插页式视频

* 横幅广告

* 每个广告单元类型的放置/位置名称必须唯一

* 支持在单个 POST 调用中创建多个广告位

* 作为响应，您将收到 placementId。ironSource 平台中未显示此参数。您需要将此参数用于 PUT 和 DELETE 方法

### 请求##request

#### 请求正文参数##request-body-parameters

| **密钥**                           | **类型** | **描述**                                        | **必需**    |
| -------------------------------- | ------ | --------------------------------------------- | --------- |
| appKey                           | 字符串    | 要为其创建广告位的应用程序密钥                               | v         |
| "placements":                    | 数组     | 要创建的广告位列表                                     | v         |
| **这些是“placements”数组中的以下放置/位置字段** |        |                                               |           |
| adUnit                           | 字符串    | ad-unit name: rewardVideo interstitial banner | v         |
| name                             | 字符串    | 放置/位置唯一名称                                     | v         |
| adDelivery                       | 波利恩    | 如果广告放置/位置广告投放开启，则为 1，否则为 0（默默认为 1）            |           |
| itemName                         | 字符串    | 奖励名称（最多 30 个字符）                               | v（仅限奖励视频） |
| rewardAmount                     | 整数     | 单个广告视图要赠送的商品数量（最多 2000000000）                 | v（仅限奖励视频） |
| capping.已启用                      | 整数     | 1 表示启用上限，否则为 0                                |           |
| capping.limit                    | 整数     | 每个封顶间隔投放的广告服务的最大数量（最多 1000）                   |           |
| capping.interval                 | 字符串    | 封顶间隔：d - 天 h - 小时                             |           |
| pacing.已启用                       | 整数     | 1 表示启用 pacinhg，否则为 0                          |           |
| pacing.minutes                   | 浮点     | 广告投放之间的最小间隔（以分钟为单位）（最大 1000）                  |           |

#### 请求正文示例##request-body-example

```json
{
  "appKey":"28cd2e39",
  "placements": [
    {
      "adUnit": "rewardedVideo", // rewardedVideo / interstitial / banner
      "name": "Main_Menu", // 唯一放置/位置名称
      "itemName": "coin", // the rewarded item name
      "rewardAmount":25, // 每个广告视图的奖励金额
      "capping": {
        	"enabled":1、// 1 - 启用上限，否则为 0（默认：1）
		"cappingLimit":3、// 每个 CappingInterval 的广告服务限制
		"cappingInterval": "h" // interval type. "h"-hours, "d"-days (default: “d”)
      }
    },
    {
      "adUnit": "banner",
      "name": "Custom_Pause",
      "pacing": {
      	"enabled":0, // 1 - 启用节奏，否则为 默认：1）
	  	"pacingMinutes":3、// 以分钟为单位的节奏间隙
      }
    }
  ]
}

```

### 响应##response

成功响应将具有新创建的放置/位置标识符。此参数不会显示在 ironSource 平台中，您可以使用 GET 方法获取该参数。编辑/删除广告位时，需要使用 id。

#### 响应参数##response-parameters

| **密钥** | **类型** | **描述**    | **值**                       | **必需** |
| ------ | ------ | --------- | --------------------------- | ------ |
| appKey | 字符串    | 应用程序唯一标识符 |                             | v      |
| adUnit | 字符串    | 广告单元的名称   | rewardVideo interstitial 横幅 | v      |
| name   | 字符串    | 放置/位置的名称  | 最多 30 角色符                   | v      |
| id     | 字符串    | 放置/位置 ID  |                             |        |

#### 响应正文示例##response-body-example

```json
{
    "appKey":"28cd2e39",
    "placements": [
        {
            "adUnit": "rewardedVideo",
            "id": 2、// 放置/位置的唯一 ID
            "name": "Main_Menu"
        },
        {
            "adUnit": "banner",
            "id": 4,
            "name": "Custom_Pause"
        }
    ]
}
```

## Put 方法##put-method

更新现有广告位，包括应用程序中的上限和节奏 API 支持以下广告单位：

* 奖励视频广告
* 插页式视频
* 横幅广告

无法关闭默认放置/位置广告投放。

要启用上限/节奏，必须提供 amount 字段。

### 请求##request

#### 请求网址示例##request-url-example

`https://dev-php-ssp5.supersonicads.com/partners/publisher/placements/v1?appKey=132deb27d`

#### 请求正文参数##request-body-parameters

| **密钥**                     | **类型** | **描述**                                        | **必需** |
| -------------------------- | ------ | --------------------------------------------- | ------ |
| appKey                     | 字符串    | 要更新广告位的应用程序密钥                                 | v      |
| "placements":              | 数组     | 要更新的广告位列表                                     | v      |
| 以下是“placements”数组中的放置/位置字段 |        |                                               |        |
| adUnit                     | 字符串    | ad-unit name: rewardVideo interstitial banner | v      |
| id                         | 整数     | 放置/位置唯一 ID                                    | v      |
| adDelivery                 | 整数     | 如果已开启放置/位置广告投放，则为 1，否则为 0                     |        |
| itemName                   | 字符串    | 奖励名称（最多 30 个字符）                               |        |
| rewardAmount               | 整数     | 单个广告视图要赠送的商品数量（最多 2000000000）                 |        |
| capping.已启用                | 整数     | 1 表示启用上限，否则为 0                                |        |
| capping.limit              | 整数     | 每个封顶间隔投放的广告服务的最大数量（最多 1000）                   |        |
| capping.interval           | 字符串    | 封顶间隔：d - 天 h - 小时                             |        |
| pacing.已启用                 | 整数     | 1 表示启用 pacinhg，否则为 0                          |        |
| pacing.minutes             | 浮点     | 广告投放之间的最小间隔（以分钟为单位）（最大 1000）                  |        |

#### 请求正文示例##request-body-example

```json
{
    "appKey":"28cd2e39",
    "placements": [
        {
            "adUnit": "rewardedVideo", // rewardedVideo / interstitial / banner
            "id": 1、// 唯一放置/位置 ID
            "rewardAmount":25, // 更改要给予的奖励金额
            "adDelivery":1、// 切换广告投放，1 - 启用，否则为 0
            "capping": {
                "cappingInterval": "h" // 将上限间隔更新为小时
            }
        },
        {
            "adUnit": "interstitial",
            "id": 3,
            "pacing": {
                "enabled":1、// 1 - 启用节奏，否则为 0
                "pacingMinutes":15, // 以分钟为单位的节奏间隙
            }
        }
    ]
}
```

### 响应##response

如果更新成功，HTTP 代码“200”将以消息“true”进行响应

## 删除方法##delete-method

存档应用程序中的现有广告位 API 支持以下广告单位：

* 奖励视频广告
* 插页式视频
* 横幅广告

> **Note:**
>
> 无法存档默认广告放置/位置

### 请求##request

#### 请求正文参数##request-body-parameters

| **密钥** | **类型** | **描述**                                        | **必需** |
| ------ | ------ | --------------------------------------------- | ------ |
| appKey | 字符串    | 用于存档放置/位置的应用程序密钥                              | v      |
| adUnit | 字符串    | ad-unit name: rewardVideo interstitial banner | v      |
| id     | 整数     | 放置/位置唯一 ID                                    | v      |

#### 请求正文示例##request-body-example

```json
{
    "appKey":"28cd2e39",
    "adUnit": "rewardedVideo", // rewardedVideo / interstitial / banner
    "id": 1 // 唯一放置/位置 ID
}
```

### 响应##response

如果更新成功，HTTP 代码“200”将以消息“true”进行响应