组 API v4
使用 组 API v4 通过创建、更新、获取和删除组组织和管理用户细分段。
阅读时间10 分钟最后更新于 1 个月前
重要
API 版本 3 及更低版本从 2025 年 3 月 开始弃用。更新到最新版本以避免中断。
使用此 API 可在 LevelPlay 后台上管理聚合组。API 支持以下内容：
- 管理聚合组设置
- 管理每个聚合组的瀑布流
每个调用的请求限制为 1 个应用程序。
速率限制
如果请求在 30 分钟内超过 4000 个请求，API 将返回 429 HTTP 状态代码。
身份验证类型
GET
描述
获取应用程序组的列表。
方法
请求参数
Name（名称） | 类型 | 描述 | 示例 |
|---|---|---|---|
| appKey | 字符串 | 应用程序密钥（在我们的平台上显示） | 142401ac1 |
请求示例 URL
响应参数
Name（名称） | 描述 | 示例 |
|---|---|---|
| groupId | LevelPlay 平台在创建组时生成的唯一组 ID | 2432228 |
| groupName | 组名称 | SpeakingEnglish |
| mediationAdUnitId | 组所属的广告单元的 ID | fgx25t56dq201bd2 |
| mediationAdUnitName | 组所属的广告单元的名称 | interstitial-1 |
| adFormat | 奖励、插页式、横幅或原生 | 间隙 |
| abTest | 与其相关的组测试 | A |
| position | 组在列表中的位置 | 1 |
| floorPrice | 每个展示的最低出价，以 CPM 表示 | 1.3 |
| countries | 属于该组的国家/地区代码列表 | 美国、GB |
| 细分段 | 属于该组的细分段名称列表 | 30歲以下女性 |
| 实例 | 属于该组的实例列表 | |
| 这些是“instances”数组中的以下实例字段 | ||
| id | LevelPlay 实例 API 中发送的实例 ID | 128395 |
| name | 实例名称 | 奖励50 |
| networkName | 实例所属的广告网络 | unityAds |
| isBidder | 投标人实例为 true，否则为 false | false |
| groupRate | 用于确定瀑布流中实例的优先级。应在 0.01-3000 范围内。请参阅调解管理。 | 11.9 |
| countriesRate | 与组级别速率不同的国家/地区速率列表 | |
| 以下是“ countriesRate”数组中的 countryRate 字段 | ||
| countryCode | 根据ISO 3166-1 Alpha-2由 2 个字母的国家代码定义的国家代码 | GB |
| 速率 | 用于确定瀑布流中实例的优先级并用于报告。应在 0.01-3000 范围内。请参阅调解管理。 | 9 |
响应示例
[ { "groupId":12673, "groupName": "newGroup", "mediationAdUnitId": "fgx25t56dq201bd2", "mediationAdUnitName": "interstitial-1", "adFormat": "interstitial", "abTest":"A", "countries": ["FR","US"], "position": 1, "segments": [], "floorPrice":0.3, "instances": [ { "id": 3681, "name": "", "networkName": "ironSource", "isBidder": true }, { "id": 2, "name": "Default", "isBidder": false, "networkName": "unityAds", "groupRate":5, "countriesRate": [ { "countryCode":"FR", "rate":1 } ] } ] }]
创建
使用此 API 可创建聚合组。此 API 允许您通过单个 API 调用创建多个组。使用“instances”参数可确定要在组中包含/排除的每个实例。可使用 Instances API 访问实例 ID 值。
- 此 API 允许您通过单个 API 调用创建多个组。
- 使用此 API 的 Get 调用可访问 Group Id 值
- 可使用 Instances API 访问实例 ID 值。
方法
请求参数
Name（名称） | 类型 | 描述 | 示例 |
|---|---|---|---|
| appKey | 字符串 | 应用程序密钥（在我们的平台上显示） | 142401ac1 |
请求示例 URL
支持的参数
Name（名称） | 类型 | 描述 | 必需 | 示例 |
|---|---|---|---|---|
| groupName | 字符串 | 新创建的组的名称长度应在 1 到 32 范围内。 | ✓ | 第 1 层 |
| adFormat | 字符串 | 奖励、插页式、横幅、原生 | ✓ | 间隙 |
| mediationAdUnitId | 字符串 | 组所属的广告单位的 ID 如果广告格式存在多个广告单位，则为必填项 | x | fgx25t56dq201bd2 |
| position | 数字 | 组在组列表中的位置应在 1 到列表中的最大组之间（所有Countries 组除外） | ✓ | 2 |
| abTest | 字符串 | 与其相关的 AB 测试组。"A", "B" | x | B |
| floorPrice | 数字 | 每个展示的最低出价（以 CPM 表示） | x | 15 |
| countries | 字符串数组 | 国家代码数组，由 2 个字母的国家代码定义，符合 ISO 3166-1 Alpha-2。如果未指定，默认认将包含 allCountries | x | 美国、GB |
| 细分段 | 字符串数组 | 细分段名称数组 | x | 30歲以下女性 |
| 实例 | 数组 | 要更新的实例列表。如果未指定，则默认将包含配置为广告格式的所有实例 | x | |
| 这些是“instances”数组中的以下实例字段 | ||||
| id | 数字 | LevelPlay 实例 API 中发送的实例 ID | ✓ | 124526 |
| groupRate | 数字 | 用于确定瀑布流中实例的优先级。应在 0.01-3000 范围内。请参阅调解管理。 | x | 0.6 |
| countriesRate | 数组 | 要更新的国家/地区速率列表 | x | |
| 以下是“ countriesRate”数组中的 countryRate 字段 | ||||
| countryCode | 字符串 | 国家代码。根据 ISO 3166-1 Alpha-2 由 2 个字母的国家代码定义 | ✓ | AU |
| 速率 | 数字 | 仅用于确定瀑布流中实例的优先级。应在 0.01-3000 范围内。请参阅调解管理。 | ✓ | 2.4 |
请求示例
[ { "groupName": "new group", "adFormat": "rewarded", "mediationAdUnitId": "fgx25t56dq201bd2", "countries": ["FR","US"], "position": 1, "segments": ["nonPaying"], "abTest":"B", "floorPrice":0.3, "instances": [ { "id": 7983541, "groupRate":2, "countriesRate": [ { "countryCode":"FR", "rate":1 } ] }, { "id": 4896357 }, { "id": 62624583, "countriesRate": [ { "countryCode":“US”， "rate":5.3 } ] } ] }]
更新
使用此 API 可更新聚合组设置配置和瀑布流
- 通过单个 API 调用即可更新多个组
- 要删除 groupRate/countryRate，请添加具有 null 值的字段参数。
- 要更新数组字段，请包含所有值（新的和现有的）。
方法
请求参数
Name（名称） | 类型 | 描述 | 示例 |
|---|---|---|---|
| appKey | 字符串 | 应用程序密钥（在我们的平台上显示） | 142401ac1 |
请求示例 URL
支持的参数
Name（名称） | 类型 | 描述 | 必需 | 示例 |
|---|---|---|---|---|
| groupId | 数字 | GET 请求中发送的组 ID | ✓ | 12673 |
| groupName | 字符串 | 新创建的组的名称长度应在 1 到 32 范围内 | x | 说英语 |
| position | 数字 | 组在组列表中的位置应在 1 到列表中的最大组之间（所有Countries 组除外） | x | 2 |
| floorPrice | 数字 | 每个展示的最低出价，以 CPM 表示 | x | 15 |
| countries | 字符串数组 | 根据 ISO 3166-1 Alpha-2 由 2 个字母的国家代码定义的国家代码数组。如果未指定，默认认将包含 allCountries | x | 美国、GB |
| 细分段 | 字符串数组 | 细分段名称数组 | x | 30歲以下女性 |
| 实例 | 数组 | 要更新的实例列表。如果未指定，则默认将包含配置为广告格式的所有实例 | x | |
| 这些是“instances”数组中的以下实例字段 | ||||
| id | 数字 | LevelPlay 实例 API 中发送的实例 ID | ✓ | 123658 |
| groupRate | 数字 | 仅用于确定瀑布流中实例的优先级。应在 0.01-3000 范围内。请参阅调解管理。 | x | 0.6 |
| countriesRate | 数组 | 要更新的 countryRate 列表 | x | |
| 以下是“ countriesRate”数组中的 countryRate 字段 | ||||
| countryCode | 字符串 | 根据ISO 3166-1 Alpha-2由 2 个字母的国家代码定义的国家代码 | ✓ | AU |
| 速率 | 数字 | 仅用于确定瀑布流中实例的优先级。应在 0.01-3000 范围内。请参阅调解管理。 | ✓ | 2.5 |
请求示例
[ { "groupId":123, "groupName": "new group", "countries": ["FR","US"], "position": 1, "segments": [], "floorPrice":0.3, "instances": [ { "id": 1, "groupRate": null, "countriesRate": [ { "countryCode":"FR", "rate":1 } ] }, { "id": 2, "countriesRate": [ { "countryCode":"FR", "rate":1.4 } ] } ] }]
成功
成功响应将随 HTTP 代码 200 一起发送。
删除
使用此 API 可删除实例。
- 无法删除 AllCountries 组。
- 无法恢复已删除的组。
方法
请求参数
Name（名称） | 类型 | 描述 | 示例 |
|---|---|---|---|
| appKey | 字符串 | 应用程序密钥（在我们的平台上显示） | 142401ac1 |
请求示例 URL
支持的参数
Name（名称） | 类型 | 描述 | 必需 | 示例 |
|---|---|---|---|---|
| id | 数字数组 | GET 请求中发送的组 ID | ✓ | 12473, 47238 |
请求正文示例
{ "ids": [1458, 5769]}
成功
成功响应将随 HTTP 代码 200 一起发送。
报错
如果在请求中发送的组之一失败，则会发送带有 HTTP 代码 400 的报错数组，并导致整个请求被拒绝。
每个报错后都会有报错消息。
示例
{ "errorsArray": [ { "code": ERR-208, "errorMessage":"Group name value is required", "params": { "[0].groupName": "" } }, { "code": ERR-311, "errorMessage":"Group position value is not valid", "params": { "[0].position": "" } } ], "code": 400}