菜单

广告位管理

注意：接入Api前请先熟悉api签名机制（参考接口鉴权说明）, 即Api请求样例中的一些http请求头的来源

1. 批量创建和修改广告位

1.1 请求URL

https://openapi.toponad.com/v1/deal_placement

1.2 请求方式

POST

1.3 请求参数

字段	类型	是否必传	备注
count	Int	Y	创建或修改的广告位数量
app_id	String	Y	创建或修改的广告位的应用ID
placements	Array[Object]	Y	创建或修改的广告位信息列表，列表长度最大限制为100
placements.placement_name	String	Y	广告位名称，注意：名称前后不允许空格，长度不允许超过100个字符
placements.placement_id	String	N	广告位id，注意： 1.修改操作传入 2.创建操作不传，此时如果placement_name已存在，则也标识为修改操作，即不允许在同一个应用下创建相同名字的广告位
placements.adformat	String	Y	广告样式，创建后不可修改，枚举值：native、banner、rewarded_video、interstitial、splash
placements.reward_s2s_sw	Int	N	服务端激励回调开关，注意：只有激励视频样式才有的属性，非激励视频不传即可，激励视频创建时默认是关闭，编辑时不不传代表不修改枚举说明： 1：开启 2：关闭
placements.reward_rule_id	Int	N	激励回调规则ID，服务端激励回调开启时必传，非激励视频或激励回调关闭时不传即可, 0代表自定义规则，大于0代表已有的回调规则规则ID具体看：服务端回调规则管理
placements.reward_s2s	Object	N	服务端激励回调开启时（reward_s2s_sw=1）并且选择了自定义规则（reward_rule_id=0）时必传属性，非激励视频或激励回调关闭时不传即可，结构如下
placements.reward_s2s.number	Int	Y	激励数量，有效范围[1:10000000]
placements.reward_s2s.name	String	Y	激励名称
placements.reward_s2s.url	String	Y	激励回调地址，注意：请输入有效地址，Taku会在操作时回调该地址（增加参数is_test=1）测试是否正常，正常需要返回200状态码
placements.template（已废弃无效）	Int	N	针对native广告才有的配置，默认为标准，创建后不可修改，枚举值说明： 0: 标准 1: 原生Banner 2: 原生开屏
placements.template_extra（已废弃无效）	Object	N	针对native广告必传的模板额外信息
placements.template_extra.cdt（已废弃无效）	Int	N	template为原生开屏时：倒计时时间，单位为秒，默认5秒
placements.template_extra.ski_swt（已废弃无效）	Int	N	template为原生开屏时：是否可跳过，默认不可跳过，枚举值说明： 0: 表示No 1: 表示Yes
placements.template_extra.aut_swt（已废弃无效）	Int	N	template为原生开屏时：是否自动关闭，默认不自动关闭，枚举值说明： 0: 表示No 1: 表示Yes
placements.template_extra.auto_refresh_time（已废弃无效）	Int	N	template为原生Banner时：是否开启自动刷新+自动刷新的时间，秒为单位，建议至少间隔10秒，注意：小于等于0标识不开启自动更新
placements.remark	String	N	备注
placements.status （已废弃，勿传）	Int	N	广告位状态（后期不再维护，请使用下面Api4接口），默认正常，注意：设置1,2会影响广告位使用，枚举值说明： 1: 锁定 2: 等待审核 3: 正常
placements.share_pl_id	string	N	绑定共享位ID,不传递不更新，传递空字符串""做解绑

1.4 返回参数

字段	类型	是否必传	备注
-	Array[Object]	Y	广告位信息列表
-.app_id	String	Y	开发者后台的应用ID
-.app_name	String	Y	应用名称
-.placement_name	String	Y	广告位名称
-.placement_id	String	Y	开发者后台的广告位ID
-.adformat	String	Y	广告样式，枚举值：native、banner、rewarded_video、interstitial、splash
-.reward_s2s_sec_key	String	N	激励是否服务端回调的安全密钥，注意：只有开启服务端激励（reward_s2s_sw=1）并且选择了自定义规则（reward_rule_id=0）时才回传
-.template	Int	N	针对native广告才有的配置，默认为标准，创建后不可修改，枚举值说明： 0: 标准 1: 原生Banner 2: 原生开屏
_.template_extra	Object	N	针对native广告的模板额外信息
-.template_extra.cdt	Int	N	template为原生开屏时：倒计时时间，单位为秒，默认5秒
-.template_extra.ski_swt	Int	N	template为原生开屏时：是否可跳过，默认不可跳过，枚举值说明： 0: 表示No 1: 表示Yes
-.template_extra.aut_swt	Int	N	template为原生开屏时：是否自动关闭，默认不自动关闭，枚举值说明： 0: 表示No 1: 表示Yes
-.template_extra.auto_refresh_time	Int	N	template为原生Banner时：自动刷新的时间，秒为单位
_.template_extra.auto_refresh	Int	N	template为原生Banner时：是否自动刷新, 枚举值说明: 0: 关闭自动刷新 1: 开启自动刷新
-.remark	String	N	备注
-.status	Int	N	广告位状态
-.errors	String	N	错误信息（错误时返回）,部分错误描述如下： 1. “xxx of the placement is error“: 请求参数数值错误

1.5 样例

请求样例：

curl --location --request POST 'https://openapi.toponad.com/v1/deal_placement' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0675b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "count": 1,
    "app_id": "a5c41a9ed1679c",
    "placements": [
        {
            "placement_name": "6",
            "adformat": "native",
            "remark": "remark",
            "template":2,
            "template_extra":{
                "cdt":55,
                "ski_swt":1,
                "aut_swt":1
            }

        }

    ]
}'

返回样例：

[
    {
        "app_name": "我要翘课",
        "app_id": "a5c41a9ed1679c",
        "platform": 2,
        "placement_id": "b1bv57tielnlts",
        "placement_name": "6",
        "adformat": "native",
        "remark": "remark",
        "template": 2,
        "template_extra": {
            "cdt": 55,
            "ski_swt": 1,
            "aut_swt": 1
        }
    }
]

2. 获取广告位列表

2.1 请求URL

https://openapi.toponad.com/v1/placements

2.2 请求方式

POST

2.3 请求参数

字段	类型	是否必传	备注
app_ids	Array[String]	N	应用ID列表，默认所有应用ID，数量最大限制为100
placement_ids	Array[String]	N	广告位ID列表，默认所有广告位ID，数量最大限制为100 注意：和start, limit参数一起使用时，以start+limit条件获取到的广告位个数为准
type	Int	N	按类型筛选：1=普通位，2=共享位；不传返回全部
start	Int	N	起始偏移量，默认0
limit	Int	N	起始偏移量，默认100, 最大一次性获取100

2.4 返回参数

字段	类型	是否必传	备注
-	Array[Object]	Y	广告位信息列表
_.app_id	String	Y	开发者后台的应用ID
_.app_name	String	Y	应用名称
_.platform	Int	Y	应用平台，枚举值说明： 1: 安卓平台 2: iOS平台
_.placement_name	String	Y	广告位名称
_.placement_id	String	Y	开发者后台的广告位ID
_.adformat	String	Y	广告样式，枚举值：native、banner、rewarded_video、interstitial、splash
_.reward_s2s_sw	Int	N	激励视频样式服务端回调开关，枚举说明： 1：开 2：关
_.reward_rule_id	Int	N	激励回调规则ID, 0（不返回）代表自定义规则，大于0代表已有的回调规则
_.reward_s2s	Object	N	激励视频样式服务端回调开启时并且是自定义规则（reward_rule_id=0）时，才返回的一些配置属性
_.reward_s2s.number	Int	N	激励数量
_.reward_s2s.name	String	N	激励名称
_.reward_s2s.url	String	N	激励回调地址
_.reward_s2s.sec_key	String	N	激励安全密钥
_.template	Int	N	针对native广告才有的配置，默认为标准，创建后不可修改，枚举值说明： 0: 标准 1: 原生Banner 2: 原生开屏
_.template_extra	Object	N	针对native广告的模板额外信息
_.template_extra.cdt	Int	N	template为原生开屏时：倒计时时间，单位为秒，默认5秒
_.template_extra.ski_swt	Int	N	template为原生开屏时：是否可跳过，默认不可跳过，枚举值说明： 0: 表示No 1: 表示Yes
_.template_extra.aut_swt	Int	N	template为原生开屏时：是否自动关闭，默认不自动关闭，枚举值说明： 0: 表示No 1: 表示Yes
_.template_extra.auto_refresh_time	Int	N	template为原生Banner时：自动刷新时间，秒为单位
_.template_extra.auto_refresh	Int	N	template为原生Banner时：是否自动刷新, 枚举值说明: 0: 关闭自动刷新 1: 开启自动刷新
_.remark	String	N	备注
_.status	Int	N	广告位状态（后期不再维护，使用status_v2）
_.status_v2			广告位开启、关闭等状态，枚举说明 1: 关闭 3: 开启
-.errors	String	N	错误信息（错误时返回）,部分错误描述如下： 1. “No placements could be matched“: 请求参数app_ids，placement_ids和start，limit混用错误
_.type	int	N	1 普通广告位，2 共享广告位
_.share_pl_sw	int	N	接入共享位状态：1 开，2 关
_.share_pl_id	string	N	绑定的共享位 id
_.share_pl_name	string	N	普通广告位绑定的共享位名称
_.app_version	string	N	共享位应用版本

2.5 样例

请求样例：

curl --location --request POST 'https://openapi.toponad.com/v1/placements' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0675b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "placement_ids":["b5bc9bc2951216"]
}'

返回样例：

[
    {
        "app_name": "topontest",
        "app_id": "a5bc9921f7fdb4",
        "platform": 2,
        "placement_id": "b5bc9bc2951216",
        "placement_name": "topontest_rewardvideo",
        "adformat": "rewarded_video"
    }
]

3. 批量删除广告位

3.1 请求URL

https://openapi.toponad.com/v1/del_placements (该接口已废弃)

3.2 请求方式

POST

3.3 请求参数

字段	类型	是否必传	备注
placement_ids	Array[String]	Y	广告位id列表，数量最大限制为100

3.4 返回参数

字段	类型	是否必传	备注
msg	String	N	结果描述，比如"suc"代表删除成功

3.5 样例

请求样例：

curl --location --request POST 'https://openapi.toponad.com/v1/del_placements' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0675b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "placement_ids":["b5bc9bc2951216"]
}'

返回样例：

{
    "msg": "suc"
}

4. 批量开启/关闭广告位

4.1 请求URL

https://openapi.toponad.com/v3/placements/status

4.2 请求方式

PUT

4.3 请求参数

字段	类型	是否必传	备注
ids	Array[String]	Y	广告位ID列表，最大批量100个，例如：["34343943uucce33"]
status	Int	Y	操作状态，枚举说明： 1: 关闭 3: 开启

4.4 返回参数

字段	类型	是否必传	备注
items	Array[Object]	N	错误广告源信息列表，注意： 1. 列表为空，则标识操作成功 2. 列表不为空，则列表标识哪些广告位校验不通过，所有广告位（包括校验通过）操作失败
items.id	String	Y	广告位ID
items.err_code	Int	Y	错误码
items.err_msg	String	Y	错误信息，部分描述如下 1. "the unit is not yet bind to the segment": 开启或关闭操作时传参存在未绑定的广告源

4.5 样例

请求样例：

curl --location --request PUT 'https://openapi.toponad.com/v3/placements/status' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0675b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ids": ["34343943uucce33"],
    "status": 1   
}'

返回样例：

{

}

5. 创建共享广告位

注意：目前该功能为白名单机制，如需使用，请联系Taku客户经理进行开通。

5.1 请求URL

https://openapi.toponad.com/v3/shared_placement

5.2 请求方式

POST

5.3 请求参数

字段	类型	是否必传	备注
app_id	string	Y	应用 id
name	string	Y	共享位名称，1–100 字符
adformat	string	Y	广告样式：native,rewarded_video,banner,interstitial,splash
placement_ids	string[]	Y	待绑定的普通广告位 id 列表，至少 1 个，最多 99 个
unbind_others_on_share	bool	N	false:增量，true:全量同步解绑(默认) 全量同步，不在placement_ids 的普通广告位则会解绑
remark	string	N	备注
app_version	string	N	应用版本

5.4 返回参数

字段	类型	备注
placement_id	string	新建的共享位 id
placement_name	string	共享位名称
app_id	string	应用 id
adformat	string	广告样式
type	int	固定 2（共享位）
remark	string	备注
app_version	string	应用版本
bound_placements	array	绑定结果列表
bound_placements[].placement_id	string	普通广告位id
bound_placements[].status	string	success / fail
bound_placements[].err_msg	string	失败原因

5.5 样例

请求样例：

curl --location --request PUT 'https://openapi.toponad.com/v3/shared_placement' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0675b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "app_id": "a5f2d0807c75e3",
  "name": "share_pool_1",
  "adformat": "banner",
  "placement_ids": ["b1hle3r3hbgqpe"],
  "remark": "共享池1",
  "app_version": ""
}'

返回样例：

{
  "placement_id": "b1hle3r3vpjint",
  "placement_name": "share_pool_1",
  "app_id": "a5f2d0807c75e3",
  "adformat": "banner",
  "type": 2,
  "remark": "共享池1",
  "bound_placements": [
    { "placement_id": "b1hle3r3hbgqpe", "status": "success" }
  ]
}

最近修改: 2026-09-23Powered by

大纲