菜单

聚合管理的广告源管理

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

1. 指定流量分组下的所有广告源(不包括adx广告源)

注意：暂时不支持获取有在做实验的流量分组下的广告源，待升级，否则报错：{"errors":"code: 4602, msg: the mediation connection not found"}

1.1 请求URL

https://openapi.toponad.com/v3/waterfall/:mediation_group_id/segment_id/:segment_id/units

1.2 请求方式

GET

1.3 请求参数

字段类型是否必传备注
ecpm_currencyStringNecpm币种单位，不传时默认为开发者账号币种，可选USD，CNY，返回参数ad_source_list中的ecpm和auto_ecpm价格根据该字段传对应单位值

1.4 返回参数

字段类型是否必传备注
offer_list_switchIntY
ecpm_currencyStringYecpm币种单位，对应请求时的参数ecpm_currency，返回参数ad_source_list中的ecpm和auto_ecpm价格根据该字段传对应单位值
parallel_request_numberIntY并发请求数
offer_listArray[Object]Y正在使用的交叉推广列表
offer_list.offer_idStringY交叉推广ID
offer_list.offer_nameStringY交叉推广名称
ad_source_listArray[Object]Y启用的广告源信息列表
ad_source_list.ad_source_idIntY广告源ID
ad_source_list.nameStringY广告源名称
ad_source_list.header_bidding_switchIntY是否支持Header Bidding，广告源创建时已确定
1：表示不支持
2：表示支持
ad_source_list.ecpmStringYeCPM价格
ad_source_list.auto_ecpm_switchIntY自动优化ECPM
1：表示不开启自动优化，
2：表示开启自动优化
ad_source_list.auto_ecpmStringY流量分组ID自动eCPM价格
ad_source_list.ecpm_rankIntY同价格广告源展示优先级，值范围：[1,99]，值越大优先级越高
ad_source_list.bid_floorStringN竞价广告源竞价底价
ad_source_list.hour_capIntY展示上限（小时），-1 表示无限制
ad_source_list.day_capIntY展示上限（天），-1 表示无限制
ad_source_list.pacingIntY展示间隔（秒），-1 表示无限制
free_ad_source_listArray[Object]Y关闭的广告源信息列表
free_ad_source_list.ad_source_idIntY广告源ID
free_ad_source_list.nameStringY广告源名称
free_ad_source_list.header_bidding_switchIntY是否支持Header Bidding，广告源创建时已确定
1：表示不支持
2：表示支持
free_ad_source_list.ecpmStringYeCPM价格
free_ad_source_list.auto_ecpm_switchIntY1：表示不开启自动优化，
2：表示开启自动优化
free_ad_source_list.auto_ecpmStringY流量分组ID自动eCPM价格
free_ad_source_list.bid_floorStringN竞价广告源竞价底价

1.5 样例

请求参例：

curl --location --request GET 'https://openapi.toponad.com/v3/waterfall/116112/segment_id/600262/units?ecpm_currency=USD' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0===b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626056011000' \
--header 'Content-Type: application/json' \
--data-raw ''

返回样例：

{
    "offer_list_switch": 2,
    "ecpm_currency": "USD",
    "parallel_request_number": 2,
    "offer_list": [],
    "ad_source_list": [
        {
            "ad_source_id": 681853,
            "name": "Chartboost_int_2",
            "header_bidding_switch": 1,
            "ecpm": "66",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0",
            "ecpm_rank": 1,
            "hour_cap": -1,
            "day_cap": -1,
            "pacing": -1
        },
        {
            "ad_source_id": 681852,
            "name": "Sigmob_int_2",
            "header_bidding_switch": 1,
            "ecpm": "20",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0",
            "ecpm_rank": 1,
            "hour_cap": 4,
            "day_cap": 5,
            "pacing": 6
        }
    ],
    "free_ad_source_list": [
        {
            "ad_source_id": 681851,
            "name": "Kuaishou Ads_int_2",
            "header_bidding_switch": 1,
            "ecpm": "50",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0",
            "ecpm_rank": 1,
        },
        {
            "ad_source_id": 681850,
            "name": "Mintegral_int_1",
            "header_bidding_switch": 1,
            "ecpm": "100",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0",
            "ecpm_rank": 1,
        },
        {
            "ad_source_id": 681854,
            "name": "Facebook_int_2",
            "header_bidding_switch": 1,
            "ecpm": "22",
            "auto_ecpm_switch": 1,
            "auto_ecpm": "0",
            "ecpm_rank": 1,
        }
    ]
}

2. 批量修改广告源在waterfall的属性（过期，请使用Api5）

2.1 请求URL

https://openapi.toponad.com/v3/waterfall/:mediation_group_id/segment_id/:segment_id/units

2.2 请求方式

PUT

2.3 请求参数

字段类型是否必传备注
parallel_request_numberIntY并发请求数
offer_switchIntN交叉推广开关
ad_source_listArray[Object]Y要启用的广告源信息列表，注意：默认广告源如果还未绑定到segment_id，则修改属性的同时也绑定到流量分组
ad_source_list.ad_source_idIntY广告源ID
ad_source_list.ecpmStringYeCPM价格，竞价广告源传“0”即可
ad_source_list.auto_ecpm_switchIntY是否开启自动优化，注意：广告源关联的平台账号必须是开启报表api【广告位管理Api1的is_open_report参数】后才可以开启自动优化
1：表示不开启自动优化，
2：表示开启自动优化
ad_source_list.hour_capIntN展示上限（小时），-1 表示无限制， 注意：不传时默认为-1，和传-1是一样的意义
ad_source_list.day_capIntN展示上限（天），-1 表示无限制 注意：不传时默认为-1，和传-1是一样的意义
ad_source_list.pacingIntN展示间隔（秒），-1 表示无限制 注意：不传时默认为-1，和传-1是一样的意义
ad_source_list.ecpm_rankIntN同价格广告源展示优先级，值范围：[1,99]，值越大优先级越高，注意：不传默认为不修改 注意：暂时ad_source_list里面每个item要么都设置ecpm_rank，要么都不设置，某些广告源不关心ecpm_rank设置1即可
ad_source_list.bid_floorStringN竞价广告源竞价底价 注意：暂时ad_source_list里面每个item要么都设置bid_floor，要么都不设置，非竞价广告源设置"0"即可
unbind_ad_source_listArray[Int]N要关闭的广告源ID列表
ecpm_currencyStringNecpm币种单位，不传时默认为开发者账号币种，可选USD，CNY，返回参数ad_source_list中的ecpm和auto_ecpm价格根据该字段传对应单位值

2.4 返回参数

字段类型是否必传备注
mediation_group_idIntY聚合分组ID
segment_idIntY流量分组ID

2.5 样例

请求样例：

curl --location --request PUT 'https://openapi.toponad.com/v3/waterfall/116112/segment_id/600262/units' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "parallel_request_number" : 1,
    "offer_switch" : 1,
    "ad_source_list": [
            {
                "ad_source_id": 681853,
                "header_bidding_switch": 1,
                "ecpm": "66",
                "auto_ecpm_switch": 1,
                "hour_cap": -1,
                "day_cap": -1,
                "pacing": -1,
                "ecpm_rank": 1
            },
            {
                "ad_source_id": 681852,
                "header_bidding_switch": 1,
                "ecpm": "20",
                "auto_ecpm_switch": 1,
                "hour_cap": 4,
                "day_cap": 5,
                "pacing": 6,
                "ecpm_rank": 1
            }
        ],
    "unbind_ad_source_list" : [
        681851,
        681850,
        681854
    ]
}'

返回样例：

{
    "mediation_group_id": 116112,
    "segment_id": 600262
}

3. 批量开启/关闭waterfall广告源

注意：暂时不支持获编辑在做实验的流量分组下的广告源，待升级，否则报错：{"errors":"code: 4602, msg: the mediation connection not found"}

3.1 请求URL

https://openapi.toponad.com/v3/waterfall/units/status

3.2 请求方式

PUT

3.3 请求参数

字段类型是否必传备注
placement_idStringY广告位ID
mediation_group_idIntY聚合分组ID
segment_idIntY流量分组ID，0代表默认分组
ad_source_idsArray[Int]Y广告源ID列表
statusIntY操作状态，注意：开启或关闭操作时，传的广告源id必须是已绑定到流量分组segment_id（即只能开启或关闭已绑定的广告源），枚举说明： 1: 关闭
3: 开启
11: 解绑

3.4 返回参数

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

3.5 样例

请求样例：

curl --location --request PUT 'https://openapi.toponad.com/v3/waterfall/units/status' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "placement_id" : "34343943uucce33",
    "mediation_group_id" : 100000,
    "segment_id" : 100000,
    "ad_source_ids": [232,435],
    "status": 1       
}'

返回样例：

{
    "items": [
        {
            "id": 232,
            "err_code": 4000
            "err_msg": "the unit not found"
        }
    ]
}

4. 获取广告源所有waterfall属性

注意：流量分组做了实验，同一个segment_id可能会有多条（对应不同的实验组abtest_group_item_id），文档暂时不体现，待升级

4.1 请求URL

https://openapi.toponad.com/v3/waterfall/units

4.2 请求方式

GET

4.3 请求参数

字段类型是否必传备注
idsArray[Int]Y广告源ID列表，数量最大限制为100，最小限制为1
currencyStringYecpm,bid_floor等对应的币种单位，可选USD，CNY

4.4 返回参数

字段类型是否必传备注
idIntY广告源ID
itemsArray[Object]Y广告源所有waterfall信息列表
items.mediation_group_idIntY聚合分组ID
items.segment_idIntY流量分组ID，0代表默认分组
items.ecpmDoubleYeCPM价格, 币种单位为请求参数的currency
items.ecpm_rankIntY同价格广告源展示优先级，值范围：[1,99]，值越大优先级越高
items.auto_ecpm_switchIntY是否开启自动ECPM优化
1：不开启
2：开启
items.auto_ecpmDoubleY开启自动ECPM优化后的自动ecpm，0代表不生效自动ecpm
items.show_delayIntY延迟展示时间，单位毫秒，范围[5000]，注意：一些样式才有，比如插屏，不关注或非插屏是传0即可
items.show_delay_rateIntY延迟展示概率，范围[1,100]，注意：一些样式才有，比如插屏, 不关注或非插屏是传0即可
items.bid_floorDoubleY竞价底价，币种单位为请求参数的currency，非竞价或不关注传0即可
items.setup_swIntY广告源在该流量分组是否是开启状态的，枚举说明：
1：是
2：否
items.cap_hourIntY小时展示上限，-1代表不限制，注意：开启的广告源才有的属性，关闭状态时传-1即可
items.cap_dayIntY天展示上限，-1代表不限制，注意：开启的广告源才有的属性，关闭状态时传-1即可
items.pacingIntY展示间隔，-1代表不限制，注意：开启的广告源才有的属性，关闭状态时传-1即可

4.5 样例

请求样例：

curl --location --request GET 'https://openapi.toponad.com/v3/waterfall/units?ids=417018,2280206¤cy=CNY' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0===b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626056011000' \
--header 'Content-Type: application/json' \
--data-raw ''

返回样例：

[
    {
        "id": 2280206,
        "items": [
            {
                "mediation_group_id": 273234,
                "segment_id": 0,
                "ecpm": 2,
                "ecpm_rank": 1,
                "remark": "",
                "setup_sw": 1,
                "auto_ecpm_switch": 1,
                "auto_ecpm": 0,
                "cap_hour": -1,
                "cap_day": -1,
                "pacing": -1,
                "show_delay": 0,
                "show_delay_rate": 100,
                "bid_floor": 0
            }
        ]
    }
]

5. 编辑（绑定+开启）广告源所有waterfall属性

注意：暂时不支持获编辑在做实验的流量分组下的广告源，待升级，否则报错：{"errors":"code: 4602, msg: the mediation connection not found"}

5.1 请求URL

https://openapi.toponad.com/v3/waterfall/units

5.2 请求方式

PUT

5.3 请求参数

字段类型是否必传备注
placement_idStringYTaku的广告位ID
currencyStringYecpm,bid_floor等对应的币种单位，可选USD,，CNY
itemsArray[Object]Y多个广告源所有waterfall信息列表，注意：默认广告源如果还未绑定到segment_id，则修改属性的同时也绑定到流量分组
items.idIntYTaku广告源ID
items.itemsArray[Object]Y对应每个广告源ID下的所有waterfall信息列表
注意：相同属性，所以item要么一起修改，要么一起不修改
items.items.mediation_group_idIntY聚合分组ID
items.items.segment_idIntY流量分组ID，0代表默认分组
items.items.ecpmDoubleYeCPM价格, ，竞价广告源传0即可，币种单位为请求参数的currency
注意：竞价类型没有ecpm可传0，非竞价类型最小ecpm为0.01
items.items.ecpm_rankIntY同价格广告源展示优先级，值范围：[1,99]，值越大优先级越高
items.items.auto_ecpm_switchIntY是否开启自动ECPM优化 (开启广告源关联的平台账号必须是开启报表api）
1：不开启 2：开启
注意：只有部分类型广告源广告源（常规非竞价，兜底广告源）才能开启指定价格
items.items.show_delayIntY延迟展示时间，单位毫秒，注意：一些样式才有，比如插屏，不关注或非插屏是传0即可

-1代表设置不延迟（0延迟）
items.items.show_delay_rateIntY延迟展示概率，范围[1,100]，注意：一些样式才有，比如插屏，不关注或非插屏是传0即可

-1代表设置不延迟（0延迟）
items.items.bid_floorDoubleY竞价底价，币种单位为请求参数的currency
注意：非竞价广告源或无竞价底价传0即可， 设置竞价底价范围，美元：[0.01,10000]；人民币：[0.1,10000]
items.items.setup_swIntY广告源在该流量分组是否是开启状态的，枚举说明： 1：是 2：否
items.items.cap_hourIntY小时展示上限，-1代表不限制，注意：开启的广告源才有的属性，关闭状态时传-1即可
items.items.cap_dayIntY天展示上限，-1代表不限制，注意：开启的广告源才有的属性，关闭状态时传-1即可
items.items.pacingIntY展示间隔，-1代表不限制，注意：开启的广告源才有的属性，关闭状态时传-1即可

5.4 返回参数

字段类型是否必传备注
itemsArray[Object]N错误广告源信息列表，注意： 1. 列表为空，则标识操作成功 2. 列表不为空，则列表标识哪些item校验不通过，所有item（包括校验通过）操作失败
items.indexIntY错误item所在的索引，从0开始
items.err_codeIntY错误码
items.err_msgStringY错误信息

5.5 样例

请求样例：

curl --location --request PUT 'https://openapi.toponad.com/v3/waterfall/units' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
	"placement_id":"qdfji3434====",
	"currency":"USD",
	"items":[
		{
			"id": 2280206,
			"items": [
				{
					"mediation_group_id": 273234,
					"segment_id": 0,
					"ecpm": 2,
					"ecpm_rank": 1,
					"remark": "",
					"setup_sw": 1,
					"auto_ecpm_switch": 1,
					"auto_ecpm": 0,
					"cap_hour": -1,
					"cap_day": -1,
					"pacing": -1,
					"show_delay": 0,
					"show_delay_rate": 100,
					"bid_floor": 0
				}
			]
		}		
	]     
}'

返回样例：

{

}

上一个
聚合管理的AB测试及流量分组管理
下一个
广告源管理（过期）
最近修改: 2025-08-21Powered by