您可以使用函数和信号来创建自定义出价脚本。此脚本将通过优化目标关键绩效指标 (KPI) 来帮助您构建自定义出价模型。
本页内容
语法规则
您可以使用第一方数据为自定义出价脚本提供相关信息，从而提高展示机会价值。Display & Video 360 支持以下来源的第一方数据：
创建自定义出价脚本时，您应使用以下语法规则：
- 将所有条件放置在方括号
[ ]中 - 逗号
,也表示“and”
criteria_a 和 criteria_b 均为 true 时，criteria1 才会返回 true；而当 criteria_a 为 true 时，criteria2 会返回 true：([([criteria_a, criteria_b], score), #criteria1([criteria_a], score) #criteria2])注释
您可以使用注释为脚本添加上下文。例如，您可以添加注释来传达脚本的意图。
您可以使用如下语法添加注释：
- 如需添加单行注释，请使用
#。 - 如需添加多行注释，请使用
"""或'''将注释括起来。
示例
# 这是一条单行注释
"""
这是一条多行注释
"""
'''
这也是一条多行注释
'''
运算符
您可以在脚本中使用以下运算符：
- 算术运算符：
+、-、*、/、%、**、// - 赋值运算符：
=、+=、-=、*=、/=、%=、**=、//= - 比较运算符：
==、!=、<、>、>=、<= - 逻辑运算符：
and、or、not - 成员资格运算符：in、not in
成员资格运算符
您可以在脚本中使用 in 和 not in 成员资格运算符，以检查某一元素是否在某个字段中。
in：如果在目标字段中找到了相应元素，会返回 true。not in：如果在目标字段中找不到相应元素，会返回 true。
if 123 in channel_id: #检查 123 是否在渠道 ID 中return y比较运算符
您可以使用比较运算符向模型中添加或从中排除某个元素。
# 排除日期
if date == 20180711:
return None
可以通过返回 None 的方式来指定要在训练自定义出价模型时排除的展示数据。在训练自定义出价模型时，您可以使用返回 None 的语句来指定要排除的展示数据。
以下脚本从自定义出价模型中排除了一种广告类型：
# 排除一个细分 (ad_type == 1 表示“视频”)
if ad_type != 1:
return None
可用的函数和信号
下面列出了您可以在自定义出价脚本中使用的函数。这些表格包含以下信息：
- 字段：您在脚本中使用的函数或信号名称。
- 类型：相应输出数据的类型。自定义出价支持以下数据类型：
- 布尔值：包含
true或false值。 - 二进制：包含二进制数据。
- 双精度：包含一个浮点数值。例如
1.0。 - 整数列表：包含一组整数。
- 整数：包含正整数或负整数。例如
1或-1。 - 字符串：包含长度至少为 0 的 UTF-8 字符。例如，
country_code会输出字符串“US”。
- 布尔值：包含
- 详细信息：包含更多信息和示例链接。
有关详情，请前往 Display & Video 360 API 或下载结构化数据文件 (SDF)。
函数
Display & Video 360 自定义出价支持以下函数：
这些函数接受一个或多个信号，以便在您的自定义出价脚本中准确体现您的关键绩效指标 (KPI)。
| 类别 | 函数 | 类型 | 具体说明 |
|---|---|---|---|
| 汇总函数 | first_match_aggregate |
双精度 | 返回条件数组中会返回 true 的第一个条件的权重赋值。 |
max_aggregate |
双精度 | 返回条件数组中会返回 true 的条件的最高权重赋值。 |
|
sum_aggregate |
双精度 | 返回条件数组中会返回 true 的所有条件的赋值总和。 |
|
| 类型转换函数 | 布尔值 |
bool(x) | 返回布尔值：true 或 false。 |
float |
float(x) | 转换数字或字符串数据类型：返回一个浮点数。
示例： |
|
int |
int(x) | 转换数字或字符串数据类型，并返回一个整数。
示例： |
|
str |
str(object) | 转换数据类型，并返回字符串。
示例： |
|
| 数学函数 | log |
log(x[, base]) | 使用 1 个实参：返回 x 的自然对数（以 e 为底数）。
使用 2 个实参：返回 x 的对数（使用给定底数），计算方式为 log(x)/log(base)。 |
信号
Display & Video 360 自定义出价函数接受以下信号类别的数据：
- 维度变量：在基于变量进行评分的脚本中使用的信号。
- 转化：在基于转化结果进行评分的脚本中使用的信号。
- Google Analytics：在基于 Google Analytics 数据进行评分的脚本中使用的信号。
维度变量
| 类别 | 信号 | 类型 | 详细信息 |
| 常规 | advertiser_id |
整数 | Display & Video 360 中的广告客户标识符。 |
|---|---|---|---|
insertion_order_id |
整数 | Display & Video 360 中的广告订单标识符。 | |
line_item_id |
整数 | Display & Video 360 中的订单项标识符。 | |
| 日期/时间 | date |
整数 | 相应展示的发生日期。
格式：yyyymmdd |
day_of_week |
整数 | 与相应展示发生于周几对应的数字代码。
|
|
hour_of_day |
整数 | 相应展示的发生时段，以浏览器的本地时区表示，采用 24 小时制格式。
有效输入：0 - 23 |
|
utc_date |
整数 | 相应展示的发生日期，以世界协调时间 (UTC) 表示。
格式：yyyymmdd |
|
utc_hour_of_day |
整数 | 相应展示的发生时段，以世界协调时间 (UTC) 表示，采用 24 小时制格式。
有效输入：0 - 23 |
|
| 地理位置 | city_id |
整数 | 城市标识符。
您可以通过使用 Display & Video 360 API 或下载 SDF 元数据，生成 city_id。 |
country_code |
字符串 | 国家/地区代码。
您可以下载一个包含国家/地区代码对应关系的 PDF 文件作为参考。 |
|
country_id |
整数 | 国家或地区标识符。
您可以下载一个包含国家/地区 ID 对应关系的 PDF 文件作为参考。 |
|
dma_id |
整数 | 特定媒体市场区域 (DMA) 标识符。 下载自定义出价 ID 表格（.xlsx 格式）即可获取这些 ID。 |
|
zip_postal_code |
字符串 | 邮政编码。
您可以通过使用 Display & Video 360 API 或下载 SDF 元数据查找可用邮政编码的列表。 |
|
| 广告素材（常规） | ad_type |
整数 | 用于表示广告格式的数值代码：
|
creative_height |
整数 | 广告素材高度（以像素为单位）。
注意：仅适用于展示广告素材。 |
|
creative_id |
整数 | Display & Video 360 中显示的广告素材 ID。 | |
creative_width |
整数 | 广告素材宽度（以像素为单位）。
注意：仅适用于展示广告素材。 |
|
| 计算机系统 | browser_reportable_id |
整数 | 浏览器标识符。
下载自定义出价 ID 表格（.xlsx 格式）即可获取这些 ID。 使用公共 API ID。 您也可在最新的 SDF 元文件中或通过使用数据传输文件找到 ID。 注意：为了使整个 Display & Video 360 中的 ID 空间保持一致， |
browser_timezone_offset_minutes |
整数 | 浏览器所用的有效时区与 GMT-12 之间的时差（以分钟为单位）。
示例： 1320 表示浏览器时区为 GMT+10 |
|
device_type |
整数 | 用于表示设备类型的数值代码：
|
|
环境 |
整数 | 用于表示广告投放环境的数值代码。
|
|
isp_reportable_isp |
整数 | 互联网服务提供商 (ISP) 标识符。
下载自定义出价 ID 表格（.xlsx 格式）即可获取这些 ID。 使用公共 API ID。 您也可在最新的 SDF 元文件中或通过使用数据传输文件找到 ID。 注意：为了使整个 Display & Video 360 中的 ID 空间保持一致， |
|
language |
字符串 | 浏览器的语言设置。 下载自定义出价 ID 表格（.xlsx 格式）即可获取这些 ID。 |
|
mobile_make_reportable_id |
整数 | 移动设备品牌标识符。
下载自定义出价 ID 表格（.xlsx 格式）即可获取这些 ID。 使用公共 API ID。 您也可在最新的 SDF 元文件中或通过使用数据传输文件找到 ID。 注意：为了使整个 Display & Video 360 中的 ID 空间保持一致， |
|
mobile_model_reportable_id |
整数 | 移动设备型号标识符。
下载自定义出价 ID 表格（.xlsx 格式）即可获取这些 ID。 使用公共 API ID。 您也可在最新的 SDF 元文件中或通过使用数据传输文件找到 ID。 注意：为了使整个 Display & Video 360 中的 ID 空间保持一致， |
|
net_speed |
整数 |
用于表示在相应展示发生时检测到的网速的数值代码：
|
|
operating_system_reportable_id |
整数 | 操作系统标识符。
下载自定义出价 ID 表格（.xlsx 格式）即可获取这些 ID。 使用公共 API ID。 您也可在最新的 SDF 元文件中或通过使用数据传输文件找到 ID 注意：为了使整个 Display & Video 360 中的 ID 空间保持一致， |
|
| 投放（常规） | ad_position |
整数 | 用于表示广告展示位置的数值代码：
|
adx_page_categories |
整数列表 | 网页类别标识符。
如需查看类别 ID 对应关系的完整列表，请访问 AdWords API 参考文档。 |
|
channels |
整数列表 | Display & Video 360 中的渠道标识符。 | |
domain |
字符串 | 注意：联网电视订单项不支持域名。 对于联网电视订单项，请使用 site_id。
根域名，由域名和顶级域名组成。 此信号会映射到报告维度“应用/网址”。 示例：网址 http://www.domain.com 的根域名是 domain.com。 |
|
exchange_id |
整数 | 广告交易平台标识符。 下载自定义出价 ID 表格（.xlsx 格式）即可获取这些 ID。 |
|
site_id |
整数 | 网站标识符。
此信号会映射到报告维度“应用/网址 ID”。 |
|
| Active View | active_view_measurable |
布尔值 | 如果广告投放时相应展示可由 Active View 衡量，会返回 1 表示 true。
某些因素可能会导致系统无法统计展示次数。如果相应展示不可衡量，会返回 |
active_view_viewed |
布尔值 | 一旦 Active View 检测到相应广告已被观看，就会返回 1 表示 true。否则，会返回 0 表示 false。 |
|
| 事件 | click |
布尔值 | 如果相应广告被点击了，会返回 1 表示 true。否则，会返回 0 表示 false。 |
time_on_screen_seconds |
整数 | 相应广告在屏幕上的展示时长（以秒为单位）。 | |
| 视频 | audible |
布尔值 | 注意：仅适用于实时出价 (RTB) 视频广告
如果相应视频广告在被观看时处于有声状态，会返回 |
completed_in_view_audible |
布尔值 | 注意：仅适用于实时出价 (RTB) 视频广告
如果相应视频广告在被观看时处于有声状态，会返回 |
|
video_completed |
布尔值 | 注意：仅适用于视频广告类型。非视频广告展示不会带有标签。
如果相应视频广告被完整播放了，会返回 |
|
video_player_height_start |
整数 | 视频播放器在播放第一帧时的高度（以像素为单位）。 | |
video_player_size |
整数 | 用于表示基于视频播放器尺寸定位到的视频广告资源的数值代码。
如需了解详情，请参阅视频广告定位。 |
|
video_player_width_start |
整数 | 视频播放器在播放第一帧时的宽度（以像素为单位）。 | |
video_resized |
二进制 | 如果视频播放器在播放过程中被调整大小了，会返回 1 表示 true。否则，会返回 0 表示 false。 |
|
viewable_on_complete |
布尔值 | 注意：仅适用于实时出价 (RTB) 视频广告。
如果相应视频在播放完毕时被观看了，会返回 |
|
video_content_duration_bucket |
整数 | 注意：仅适用于视频广告类型。非视频广告展示不会带有标签。
表示视频时长范围的数值代码，用于根据视频时长对视频进行分类。上限范围不包括在内。 对于时长为 1 分钟的视频：
示例
|
|
video_genre_ids |
整数列表 | 注意：仅适用于视频广告类型。非视频广告展示不会带有标签。
表示视频类型 ID 的列表，用于根据相关的音频和视频广告资源组定位广告。 详细了解类型定位。 |
|
video_livestream |
布尔值 | 注意：仅适用于视频广告类型。非视频广告展示不会带有标签。
如果是直播视频，则返回 |
|
| 音频 | audio_completed |
布尔值 | 注意：仅适用于音频广告。
如果用户听完了整个音频广告，系统会返回 |
browser_id、isp_id、mobile_make_id、mobile_model_id 和 operating_system_id 不再受支持。请更新脚本，改用 browser_reportable_id、isp_reportable_id、mobile_make_reportable_id、mobile_model_reportable_id 和 operating_system_reportable_id。此项更改可使“自定义出价”机制中使用的 ID 空间与 Display & Video 360 的其余部分（包括最新的 SDF 文件、API 和 Data Transfer v2）保持一致。转化次数
| 类别 | 信号 | 类型 | 具体说明 |
| 转化信号 | total_conversion_count(Floodlight Activity ID, Attribution Model ID) |
双精度 | ID 对的转化事件总数。使用您自己的模型，或输入 0 作为模型 ID，以使用最终接触归因。 |
|---|---|---|---|
total_conversion_value(Floodlight Activity ID, Attribution Model ID) |
双精度 | 从 Floodlight 销售代码所跟踪的活动获取收入值。使用您自己的模型，或输入 0 作为模型 ID，以使用最终接触归因。 | |
total_conversion_quantity(FloodlightActivity ID, Attribution Model ID) |
双精度 | 归因于给定 ID 对的总转化次数。使用您自己的模型，或输入 0 作为模型 ID，以使用最终接触归因。 | |
conversion_custom_variable(Floodlight Activity ID, Attribution Model ID, Custom Variable Index) |
字符串 | 返回最近归因于相应展示的转化对应的自定义变量的字符串值。否则（如果没促成转化或未设置值），会返回 None。使用您自己的模型，或输入 0 作为模型 ID，以使用最终接触归因。 |
|
conversion_variable_num(FloodlightActivity ID, Attribution Model ID) |
整数 | 获取具有正值的最新转化，如果存在 count_micros 为正，则获取 “num” Floodlight 变量。否则，会返回 None。 |
|
conversion_variable_ord(Floodlight Activity ID, Attribution Model ID) |
字符串 | 获取具有正值的最新转化，如果存在 count_micros 为正，则获取 “ord” Floodlight 变量。否则，会返回 None。 |
视频类型对应关系
| 类型 ID | 类型名称 |
| 2 | /成人 |
| 3 | /艺术与娱乐 |
| 317 | /艺术与娱乐/漫画与动画/动漫 |
| 319 | /艺术与娱乐/漫画与动画/卡通 |
| 1108 | /艺术与娱乐/娱乐业/电影与电视业/影视奖项 |
| 569 | /艺术与娱乐/活动与演出 |
| 1273 | /艺术与娱乐/活动与演出/直播体育赛事 |
| 895 | /艺术与娱乐/幽默/现场喜剧 |
| 1097 | /艺术与娱乐/电影/动作冒险片 |
| 1099 | /艺术与娱乐/电影/动作冒险片/西部片 |
| 1095 | /艺术与娱乐/电影/喜剧片 |
| 615 | /艺术与娱乐/电影/恐怖片 |
| 1105 | /艺术与娱乐/电影/音乐片 |
| 1310 | /艺术与娱乐/电影/爱情片 |
| 616 | /艺术与娱乐/电影/科幻片 |
| 1096 | /艺术与娱乐/电影/惊悚、犯罪与悬疑片 |
| 35 | /艺术与娱乐/音乐与音频 |
| 449 | /艺术与娱乐/网络奇闻/神秘与超自然 |
| 23 | /艺术与娱乐/表演艺术 |
| 894 | /艺术与娱乐/表演艺术/表演与戏剧 |
| 581 | /艺术与娱乐/表演艺术/舞蹈 |
| 1185 | /艺术与娱乐/表演艺术/歌剧 |
| 358 | /艺术与娱乐/电视与视频/电视节目 |
| 1047 | /艺术与娱乐/电视与视频/电视节目/电视喜剧 |
| 1411 | /艺术与娱乐/电视与视频/电视节目/电视纪录片与纪实片 |
| 1193 | /艺术与娱乐/电视与视频/电视节目/电视剧 |
| 1111 | /艺术与娱乐/电视与视频/电视节目/电视剧/罪案剧与律政剧 |
| 357 | /艺术与娱乐/电视与视频/电视节目/电视剧/电视肥皂剧 |
| 1110 | /艺术与娱乐/电视与视频/电视节目/面向家庭的电视节目 |
| 1050 | /艺术与娱乐/电视与视频/电视节目/娱乐竞赛类电视节目 |
| 1049 | /艺术与娱乐/电视与视频/电视节目/电视真人秀 |
| 1112 | /艺术与娱乐/电视与视频/电视节目/科幻类电视节目 |
| 1410 | /艺术与娱乐/电视与视频/电视节目/电视选秀与综艺节目 |
| 1048 | /艺术与娱乐/电视与视频/电视节目/电视谈话节目 |
| 24 | /艺术与娱乐/视觉艺术与设计 |
| 47 | /汽车与交通工具 |
| 1191 | /汽车与交通工具/自行车与配件 |
| 1405 | /汽车与交通工具/自行车与配件/山地自行车 |
| 273 | /汽车与交通工具/机动车（按类型）/摩托车 |
| 148 | /汽车与交通工具/机动车（按类型）/越野车 |
| 185 | /美容与健身/流行与时尚 |
| 94 | /美容与健身/健身 |
| 241 | /美容与健身/健身/健美 |
| 1418 | /美容与健身/健身/健身指导与私人训练 |
| 46 | /商业与工业/农业与林业 |
| 5 | /计算机与电子产品 |
| 122 | /食品与饮料/烹饪与食谱 |
| 39 | /游戏/纸牌游戏 |
| 924 | /游戏/纸牌游戏/扑克与赌场游戏 |
| 924 | /游戏/纸牌游戏/扑克与赌场游戏 |
| 41 | /游戏/计算机与视频游戏 |
| 698 | /游戏/赌博/体育博彩/赛马与赛狗 |
| 939 | /游戏/桌面游戏/台球 |
| 940 | /游戏/桌面游戏/乒乓球 |
| 45 | /健康 |
| 284 | /爱好与休闲/手工艺 |
| 688 | /爱好与休闲/户外活动 |
| 462 | /兴趣与休闲/户外活动/钓鱼 |
| 461 | /爱好与休闲/户外活动/狩猎与射击 |
| 461 | /爱好与休闲/户外活动/狩猎与射击 |
| 461 | /爱好与休闲/户外活动/狩猎与射击 |
| 999 | /爱好与休闲/休闲飞行 |
| 678 | /爱好与休闲/特殊场合/假日与节庆 |
| 459 | /爱好与休闲/水上活动/划船 |
| 11 | /家居与园艺 |
| 158 | /家居与园艺/家装 |
| 966 | /法律与政府/政府/州或省/自治区/直辖市政府与地方政府 |
| 75 | /法律与政府/法律 |
| 366 | /法律与政府/军事 |
| 16 | /新闻 |
| 784 | /新闻/商业资讯 |
| 396 | /新闻/政治 |
| 1201 | /新闻/政治/观点与评论 |
| 1077 | /新闻/体育资讯 |
| 785 | /新闻/科技资讯 |
| 63 | /新闻/天气 |
| 113 | /人与社会/种族与认同群体/女同性恋、男同性恋、双性恋与跨性别者 |
| 58 | /人与社会/家庭与人际关系/家庭/育儿 |
| 59 | /人与社会/宗教与信仰 |
| 870 | /人与社会/励志自助 |
| 57 | /人与社会/社会问题与宣传/慈善机构与慈善事业 |
| 82 | /人与社会/社会问题与宣传/绿色生活与环境问题 |
| 886 | /宠物与动物/宠物/狗 |
| 888 | /宠物与动物/宠物/马 |
| 119 | /宠物与动物/野生动物 |
| 119 | /宠物与动物/野生动物 |
| 690 | /参考资料/一般参考资料/传记与语录 |
| 694 | /参考资料/一般参考资料/知识问答、DIY 与专家指导 |
| 433 | /Reference/Humanities/History |
| 1288 | /参考资料/人类学/历史/军事历史 |
| 174 | /科学 |
| 18 | /购物 |
| 64 | /购物/古董与收藏品 |
| 292 | / 购物 / 拍卖 |
| 69 | /购物/消费者资源 |
| 1666 | /体育/动物运动 |
| 568 | /体育/动物运动/马术 |
| 515 | /体育/搏击运动/拳击 |
| 516 | /体育/搏击运动/武术 |
| 1674 | /体育/搏击运动/武术/综合格斗 |
| 512 | /体育/搏击运动/摔跤 |
| 1681 | /体育/搏击运动/摔跤/职业摔跤 |
| 554 | /体育/极限运动 |
| 1206 | /体育/极限运动/直线竞速赛与街头飙车 |
| 1000 | /体育/个人运动 |
| 1016 | /体育/个人运动/保龄球 |
| 458 | /体育/个人运动/骑行 |
| 261 | /体育/个人运动/高尔夫 |
| 519 | /体育/个人运动/体操 |
| 262 | /体育/个人运动/小球类运动 |
| 1376 | /体育/个人运动/小球类运动/网球 |
| 541 | 体育/个人运动/跑步与步行 |
| 1126 | /体育/个人运动/滑冰运动 |
| 518 | /体育/个人运动/田径 |
| 513 | /体育/国际体育比赛/奥运会 |
| 180 | /体育/机动车运动 |
| 1595 | /体育/机动车运动/汽车赛车 |
| 1596 | /体育/机动车运动/摩托车赛车 |
| 1001 | /体育/团体运动 |
| 258 | /体育/团体运动/美式橄榄球 |
| 259 | /体育/团体运动/棒球 |
| 264 | /体育/团体运动/篮球 |
| 534 | /体育/团体运动/啦啦队 |
| 296 | /体育/团体运动/板球 |
| 1017 | /体育/团体运动/手球 |
| 260 | /体育/团体运动/冰球 |
| 517 | /体育/团体运动/英式橄榄球 |
| 294 | /体育/团体运动/足球 |
| 699 | /体育/团体运动/排球 |
| 118 | /体育/水上运动 |
| 1593 | /体育/水上运动/冲浪 |
| 1594 | /体育/水上运动/游泳 |
| 265 | /体育/冬季运动 |
| 1149 | /体育/冬季运动/滑冰 |
| 1148 | /体育/冬季运动/滑雪与单板滑雪 |
| 67 | /旅行与交通 |
Google Analytics
| 类别 | 信号 | 类型 | 详细信息 |
|---|---|---|---|
| Google Analytics | has_ga4_conversions(property_id, conversion_event_name) |
布尔值 |
如果有至少 1 个带有媒体资源 ID 和转化事件的转化归因于指定展示，那么返回 true。否则，返回 false。 |
ga4_conversions_count(property_id, conversion_event_name) |
整数 | 返回归因于指定展示且带有媒体资源 ID 和转化事件的转化的次数。 | |
ga4_conversions_max_value(property_id,conversion_event_name))* |
双精度 | 如有归因于指定展示且带有媒体资源 ID 和转化事件的转化，返回其最高值。
如果最高转化价值为 |
|
ga4_conversions_max_value_usd(property_id, conversion_event_name) |
双精度 | 注意：针对采用美元作为币种的 Google Analytics 账号。
如有归因于指定展示且带有媒体资源 ID 和转化 ID 的转化，返回其最高值 如果最高转化价值为 |
|
ga4_conversions_total_value(GA4 property ID, conversion_event_name) |
双精度 | 如有归因于指定展示且带有媒体资源 ID 和转化事件的转化，返回权重值总和。
如果最高转化价值为 |
|
ga4_conversions_total_value_usd(property_id, conversion_event_name) |
双精度 | 注意：针对采用美元作为币种的 Google Analytics 账号。
如有归因于指定展示且带有媒体资源 ID 和转化事件的转化，返回权重值总和。 如果最高转化价值为 |
限制
自定义出价脚本不支持以下各项：
- 传递具名实参：例如
func(arg1 = “abc”, arg2 = “def”) - 下标和细分：例如
userlists[1:3] - 引用属性：例如
domain.length - 变量和函数名称可以来自预定义的集合
- 递归
- 高级自定义变量赋值：
- 多赋值
- 增量赋值
- 带注解的赋值
以下是自定义变量赋值不支持的语法的示例
_a, _b = 1, 2
_a, _b = _b, _a
_a = _b = 2
_idx += 1
- 不支持的关键字：
global、nonlocal和exec关键字class和类定义def和函数定义Import和从关键字导入lambda和 lambda 支持breakcontinueyieldraiseasserttryfinallyexceptasyncawaitdelPassellipsis
- 不支持的循环：
for和while循环。
- 不支持的运算符：
*和**，如果是在非算术语句中使用。<<和>>移位运算符。- 位运算符
@修饰符。is、not is身份运算符