了解实时内容精选规范

Google 会根据与您的目标广告资源匹配的广告请求,向您的实时内容精选集成发送 SegmentRequest。SegmentRequest 对象提供情境信号或受众群体信号,您可以使用这些信号来确定哪些细分受众群适用于 SegmentResponse 中的指定广告资源。 实时内容精选支持以 JSON 格式发送的 SegmentRequest 和 SegmentResponse 对象。

本指南是实时精选协议的参考文档,可帮助您构建集成。

SegmentRequest

属性 类型 说明
imp 展示次数数组 仅适用于情境化精选合作伙伴。表示所提供的展示机会。
site 场地 仅适用于情境化精选合作伙伴。网站的描述符。如果含广告的内容是网站而非非浏览器应用,则会填充 site 字段。
app 应用广告系列 仅适用于情境化精选合作伙伴。应用的描述符。如果广告支持的内容是非浏览器应用(而非网站),则会填充 app 字段。
pub 发布商 仅适用于情境化精选合作伙伴。发布商的描述符。
user 用户 发起细分受众群请求的浏览发布商内容的用户描述符。
device 设备 仅适用于情境化精选合作伙伴。用户设备的描述符。
segment_request_id 字符串 用于独立于所有其他细分请求来标识细分请求的唯一标识符。

展示次数

属性 类型 说明
id 字符串 仅支持情境化精选合作伙伴。相应展示在细分请求上下文中的唯一标识符。该值从 1 开始,并随着展示次数的增加而递增,最多可递增到 n(对于 n 次展示)。
banner 横幅广告 仅支持情境化精选合作伙伴。如果展示机会作为横幅广告机会提供,则此字段会填充相应值。
video 视频 仅支持情境化精选合作伙伴。如果展示机会作为视频广告机会提供,则此字段会填充相应值。
ext ImpExt 此字段填充了 Imp 对象的扩展信息。

横幅

属性 类型 说明
w int 仅适用于情境化精选合作伙伴。宽度(以与设备无关的像素 [DIP] 为单位)。
h int 仅支持情境化精选合作伙伴。高度(以与设备无关的像素 [DIP] 为单位)。
pos int 仅支持情境化精选合作伙伴。广告在屏幕上的位置。如需详细了解可能的展示位置,请参阅 AdCOM 1.0 中的列表:展示位置。

视频

属性 类型 说明
w int 仅适用于情境化精选合作伙伴。视频播放器的宽度(以设备无关像素 [DIP] 为单位)。
h int 仅适用于情境化精选合作伙伴。视频播放器的高度(以设备无关像素 [DIP] 为单位)。
pos int 仅适用于情境化精选合作伙伴。广告在屏幕上的位置。如需详细了解可能的展示位置,请参阅 AdCOM 1.0 中的列表:展示位置。

ImpExt

属性 类型 说明
gpid 字符串 仅适用于情境化精选合作伙伴。描述全局展示位置 ID。由发布商指定的独特且持久的 ID,在网页上每个广告单元的各个供应路径中保持一致。请参阅这篇文章。

网站

属性 类型 说明
page 字符串 仅支持情境化精选合作伙伴。展示所在网页的网址。
mobile int 仅支持情境化精选合作伙伴。表示网站是否已编程为在移动设备上查看时优化布局,其中 0 表示否,1 表示是。

应用

属性 类型 说明
bundle 字符串 仅适用于情境化精选合作伙伴。特定于平台的应用标识符,旨在确保应用的唯一性。在 Android 上,bundle 字段是软件包名称。在 iOS 上,它是数字 ID。

发布商

属性 类型 说明
id 字符串 仅适用于情境化精选合作伙伴。由网站媒体资源代码的发布商代码后缀定义的发布商 ID。例如,如果发布商的网络媒体资源代码为 ca-pub-123,则其 ID 会设置为 pub-123。

用户

属性 类型 说明
id 字符串 Google 用户 ID。
buyeruid 字符串 通过 Cookie Matching Service 上传的托管匹配数据。默认情况下,此值以网络安全 base64 编码指定,不含填充。您可以选择与客户经理联系,将此字段配置为在不进行编码的情况下填充。
consent 字符串 从发布商的 IAB 意见征求管理平台 (CMP) 中提取的基于 base64 编码的 IAB 透明度和用户意见征求框架 (TCF) v2 用户意见征求字符串(采用 Web 安全格式)。如果发布商已与 CMP 集成以使用 TCF v2,并且该 CMP 表明 GDPR 适用于相应广告请求并提供有效的用户同意字符串,则会填充 consent 字段。如需详细了解用户意见征求字符串中列出的供应商,请访问 vendor-list.consensu.org/v2/vendor-list.json 查看 IAB 全球供应商列表。
eids EID 数组 仅支持受众群体精选合作伙伴。扩展 ID 实例。在精选广告资源中,eids 字段是发布商提供的数据,例如安全信号。

EID

属性 类型 说明
source 字符串 仅支持受众群体精选合作伙伴。负责提供所含数据的数据源或技术提供方。以顶级网域的形式表示。
uids UID 数组 仅支持受众群体精选合作伙伴。指定来源中的 UID 对象数组。

UID

属性 类型 说明
id 字符串 仅支持受众群体策划合作伙伴。标识符。在甄选过程中,id 字段是一种安全信号。如需详细了解安全信号,请参阅 Ad Manager 的与出价方和甄选合作伙伴共享安全信号。

设备

属性 类型 说明
geo 地理位置 仅适用于情境化精选合作伙伴。用户设备的位置。
devicetype int 仅支持情境化精选合作伙伴。设备的常规类型。如需详细了解可能的设备类型,请参阅 AdCOM 1.0 中的列表:设备类型。
os 字符串 仅适用于情境化精选合作伙伴。设备操作系统(例如“iOS”)。
make 字符串 仅适用于情境化精选合作伙伴。设备品牌(例如“Apple”)。
ifa 字符串 未加密的设备广告 ID(未经过哈希处理)。在 Google 的实时甄选协议中,这通常是一个 36 字符的 UUID,其中 Android ID 为小写,IDFA 为大写。对于 Samsung 设备,这些是 32 个字符的字母数字值。

Geo

属性 类型 说明
country 字符串 仅适用于情境化精选合作伙伴。国家/地区,采用 ISO-3166-1 Alpha-3 标准。
region 字符串 仅适用于情境化精选合作伙伴。使用 ISO-3166-2 标准的地区代码;如果是美国,则为 2 个字母的州代码。
metro 字符串 仅适用于情境化精选合作伙伴。在 geo-table.csv 文件中找到了 Google 都市圈代码。
city 字符串 仅适用于情境化精选合作伙伴。使用联合国贸易和运输地点代码的城市。

SegmentResponse

属性 类型 说明
segment 细分数组 细分的描述符。

Segment

属性 类型 说明
segment_id 字符串 细分的 ID。该 ID 应与 Marketplace API 的 curators.dataSegments 资源中细分的名称中找到的 curatorDataSegmentId 相匹配。