主题
创建广告单元
需要携带 Token，详情看 Token
通过此接口可用于创建广告单元。广告单元需要与已创建成功的广告关联。
请求地址
https://{BASE_URL}/api/open/v3/offer
请求方法
POST
请求示例
json
POST /api/open/v3/offer
HTTP/1.1 Host: {BASE_URL}
Content-Type: application/json
{
"campaign_id": "25",
"offer_name": "cqf_testtttt",
"promote_timezone": 7,
"start_time": 1578455012,
"target_geo": "ALL",
"billing_type": "CPI",
"bid_rate": 5,
"daily_cap_type": "BUDGET",
"daily_cap": "50",
"total_budget": "50",
"settlement_event": "",
"os_version_min": "8.8",
"custom_ad_schedule": {"1":"0,1,23","2":"3,4,5","3":"3,6,5"},
"network": "WIFI",
"target_ad_type": "BANNER",
"creative_sets": [
{"creative_set_name":"demo1","geos":["ALL"],"ad_outputs":[111],"creatives":[{"creative_name":"material1","creative_md5":"c09d944dcf2d6ded1acd6eb2237f8bad"},{"creative_name":"icon_512x512","creative_md5":"5a42fed89d97cfe253c2f7b6be86f8ed"},{"creative_name":"1200x627","creative_md5":"ea5c9ca2f16cace9c133bb327e1c83dd"}]}
],
"target_device": "PHONE"
}请求参数
| 字段 | 类型 | 说明 | 默认值 | 例子 |
|---|---|---|---|---|
campaign_id | int | 广告 ID，必须是已存在且可投放的广告。 | — | 1234 |
offer_name | string | 广告单元名称，唯一。只允许数字字母下划线，字符长度 3~95。 | "" | "offer_test" |
promote_timezone | number | 广告单元投放时间对应的时区。可选值：枚举值 - 时区 | "" | 5.5 |
start_time | int | 广告单元开始投放时间的时间戳，时间不早于 2000 年（时间戳为 946656000）。如果填写了 end_time 的话，start_time 必须小于 end_time。 | — | 1578455012 |
end_time 选填 | int | 广告单元结束投放时间的时间戳，必须晚于 start_time。 | 0 | 1578455169 |
target_geo | string | 广告单元投放的地区，全部地区则写 “ALL”，分地区用,分隔 | — | "CN" |
billing_type | string | 结算方式，可选值：枚举值 - 结算方式。与 bid_type 二者必填其一（同时传时以 billing_type 为准）。注：可选值受权限管控，权限不足时返回 "Permission denied"。 | "" | "CPI" |
bid_goal billing_type为OCPI时必填 | string | 优化目标类型，取值与 billing_type 的对应关系见下方「billing_type 与 bid_goal 对应关系」。 | — | "Target-ROAS" |
target_agg_event bid_goal为Target-ROAS、Target-CPE时必填 | array<string> | 需要优化的目标，取值见获取允许配置优化目标的事件。 | — | ["Ad Revenue"] |
target_original_event bid_goal为Target-CPE时必填 | string | 需要优化的原始目标，取值见获取允许配置优化目标的事件。 | — | "ad_revenue" |
target_goal_window bid_goal为Target-ROAS、Target-CPE时必填 | string | 优化目标的时间窗。枚举值：D0、D7（Target-ROAS、Target-CPE 均支持 D0、D7）。 | — | "D0" |
target_goal bid_goal为Target-ROAS、Target-CPE时必填 | double | offer 维度优化目标值。Target-ROAS：取值范围 [1, 1000]，保留两位小数，单位为百分比；Target-CPE：取值范围 [0.1, 2000]，保留三位小数。 | — | 80 |
target_goal_by_geo 选填 | array<json> | geo 维度优化目标值。数组元素含子字段 geo(string，geo 编码) 与 target_goal(double，该 geo 的优化目标值)。 | — | [{"geo":"US","target_goal":80}] |
bid_rate billing_type为CPI/CPE/CPM/CPC时必填 | number | 广告单元结算价格，默认针对广告单元中所有地区生效。价格必须大于 0，精度为 3 位小数。CPE、CPI、CPM 价格不能小于 0.01，CPC 不能小于 0.001。billing_type=OCPI 时无需传。 | "" | 0.04 |
daily_cap_type 选填 | string | 预算设置类型。可选值："BUDGET"、"CONVERSION"。 | "BUDGET" | "CONVERSION" |
daily_cap 选填 | number | 预算设置类型下的每天预算限制。不传则表示不设预算限制。如果 daily_cap_type 为 BUDGET，精度为 3 位小数，最小值为 50。如果 daily_cap_type 为 CONVERSION，格式必须是整数，最小值为 10。 | — | 100 |
total_budget 选填 | number | 总预算。精度为 3 位小数。不传则表示不设预算限制。如果 daily_cap_type 为 BUDGET，最小值为 10。 | — | 50.12 |
settlement_event billing_type为CPE时必填 | string | 结算事件。只允许数字字母下划线，最少 3 个字符，最长 50 字符。billing_type 非 CPE 时传入将被忽略。 | "" | "purchase" |
os_version_min 选填 | string | 投放设备要求的系统最低版本。格式为 /^[0-9](\.[0-9]){0,2}$/。如果没传，默认使用关联广告的 min_version。若不限制最低版本，传值需为 "0.0.0"。 | — | "9.0" |
os_version_max 选填 | string | 投放设备要求的系统最高版本。格式为 /^[0-9](\.[0-9]){0,2}$/。如果没传，默认使用关联广告的 max_version。若不限制最高版本，传值需为 "99.0.0"。 | — | "9.0" |
custom_ad_schedule 选填 | json | 广告投放的日程。key 表示周一到周日(1-7)，value 表示 0 点到 23 点(0-23)。默认为空值，代表所有。 | — | {"1":"0,1,23","2":"3,4,5"} |
network 选填 | string | 网络类型定向。可选值：枚举值 - 网络类型 | — | "2G,3G,4G,5G" |
target_ad_type billing_type为CPI/CPE/CPM/CPC时必填 | string | 广告展示类型。多个用,号分隔。可选值：枚举值 - 广告展示类型（图片）、枚举值 - 广告展示类型（视频）。billing_type=OCPI 时由系统自动填充，无需传。 | — | "REWARDED_VIDEO,INTERSTITIAL_VIDEO" |
target_device 选填 | string | 设备类型定向。多个用,号分隔。可选值："PHONE"、"TABLET"。 | — | "PHONE" |
creative_sets | array<json> | 创意组信息。子字段协议见接口协议 - 创建创意组。 | — | [{"creative_set_name":"demo1","geos":["ALL"],"ad_outputs":[111],"creatives":[{"creative_name":"icon_512x512","creative_md5":"5a42fed89d97cfe253c2f7b6be86f8ed"}]}] |
billing_type 与 bid_goal 对应关系
bid_goal（优化目标类型）的可选取值取决于 billing_type（结算方式）：
| billing_type | 对应可选的 bid_goal |
|---|---|
| OCPI | Target-ROAS、Target-CPE |
| CPI | Install |
| CPM | Impression |
| CPE | Event |
当
billing_type=OCPI时，bid_goal必填；其余结算方式下系统按上表自动对应，无需单独传bid_goal。
响应结果
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 200 表示成功，其他表示失败 |
| msg | string | 成功，返回"success"，失败返回相应的错误信息 |
| data | json | 成功，返回广告单元信息，失败返回具体的错误信息 |
| campaign_id | int | 广告 ID |
| offer_id | int | 广告单元 ID |
| offer_name | string | 广告单元名称 |
| promote_timezone | number | 广告单元投放时间对应的时区 |
| start_time | int | 广告单元开始投放时间的时间戳 |
| end_time | int | 广告单元结束投放时间的时间戳 |
| target_geo | string | 广告单元投放的地区 |
| bid_type | string | 结算方式 |
| bid_rate | string | 广告单元结算价格 |
| daily_cap_type | string | 预算设置类型 |
| daily_cap | string | 预算设置类型下的每天预算限制 |
| total_budget | string | 总预算 |
| settlement_event | string | 结算事件 |
| os_version_min | string | 投放设备要求的系统最低版本 |
| os_version_max | string | 投放设备要求的系统最高版本 |
| custom_ad_schedule | string | 广告投放的日程 |
| network | string | 网络状态定向 |
| target_ad_type | string | 展示类型 |
| creative_sets | array<json> | 创意组信息 |
| target_device | string | 设备类型定向 |
应答示例
json
{
"code": 200,
"msg": "success",
"data": {
"campaign_id": "25",
"offer_id": 18496,
"offer_name": "cqf_testtttt",
"promote_timezone": 7,
"start_time": "1578455012",
"end_time": "0",
"target_geo": "ALL",
"bid_type": "CPI",
"bid_rate": "5",
"daily_cap_type": "BUDGET",
"daily_cap": "50",
"total_budget": "50",
"settlement_event": "",
"os_version_min": "8.8",
"custom_ad_schedule": {
"1": "0,1,23",
"2": "3,4,5",
"3": "3,6,5"
},
"network": "WIFI",
"target_ad_type": "BANNER",
"creative_sets": [
{
"creative_set_name": "demo1",
"geos": [
"ALL"
],
"ad_outputs": [
111
],
"creatives": [
{
"creative_name":"material1",
"creative_md5": "c09d944dcf2d6ded1acd6eb2237f8bad"
},
{
"creative_name": "icon_512x512",
"creative_md5": "5a42fed89d97cfe253c2f7b6be86f8ed"
},
{
"creative_name": "1200x627",
"creative_md5": "ea5c9ca2f16cace9c133bb327e1c83dd"
}
]
}
],
"target_device": "PHONE"
}
}