> For the complete documentation index, see [llms.txt](https://docs.exoclick.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.exoclick.com/rtb/zh/guang-gao-zhu/kai-fang-rtb/adv-open-rtb-2.4-request.md).

# Open RTB 2.4 出价请求

本页描述您将接收到的 RTB 请求的各个组成部分，以便出价。

## 竞价请求头

* **OpenRTB 版本 HTTP 头**: `x-openrtb-version: 2.4`
* **Keep-Alive HTTP 头**: `Connection: Keep-Alive`
* **内容 JSON**: `Content-Type: application/json`
* **数据编码头**: `Accept-Encoding`

## 竞价请求对象

当针对特定场景请求出价时，平台将发起一个 HTTP 请求，超时时间为 **300ms** 并在请求正文中发送以下以 JSON 编码的对象。 **HTTP** 由于使用 HTTPS 会增加额外延迟，建议使用。

| 属性     | 描述                                  |
| ------ | ----------------------------------- |
| 在      | 竞价类型，第一价格 = 1（整数）                   |
| id     | 唯一竞价请求 ID（字符串）                      |
| imp    | 表示所提供展示的对象（对象）。                     |
| site   | 通过 Site 对象提供关于发布商网站的详情（对象）。         |
| device | 通过 Device 对象提供关于将投放该展示的用户设备的详情（对象）。 |
| user   | 通过 User 对象提供关于设备的人类用户的详情；即广告受众（对象）。 |
| ext    | 用于交易平台特定扩展的占位符。                     |

## imp

| 属性          | 描述                                                                                   |
| ----------- | ------------------------------------------------------------------------------------ |
| id          | 此竞价请求中的唯一展示 ID（字符串）                                                                  |
| bidfloor    | 此展示的最低出价（CPM）/ 点击（CPC），以及账户货币，可选（浮点数）。                                               |
| bidfloorcur | 使用 ISO-4217 字母代码指定的最低出价值所对应的货币，可选（字符串）                                               |
| native      | Native 对象；如果该展示作为原生广告机会提供，则为必填（对象）。                                                  |
| banner      | banner 对象；如果该展示作为横幅广告机会提供，则为必填（对象）。                                                  |
| instl       | 插屏对象；如果该展示作为插屏或弹出式广告机会提供，则为必填（对象）。(对象)                                               |
| secure      | 用于指示该展示是否需要安全的 HTTPS URL 创意素材和标记，其中 0 = 非安全，1 = 安全。若省略，则安全状态未知，但可假定支持非安全 HTTP，可选（整数） |
| el          | Base64 编码的电子邮件（字符串）                                                                  |

### imp.banner

| 属性    | 描述                                                        |
| ----- | --------------------------------------------------------- |
| w     | 横幅的宽度，单位像素（整数）。                                           |
| h     | 横幅的高度，单位像素（整数）。                                           |
| mimes | 支持的 MIME 类型。示例值：image/jpg、image/png、video/mp4、image/webp。 |

### imp.instl

| 属性    | 描述                                    |
| ----- | ------------------------------------- |
| instl | 指示广告是否为弹出式/插屏广告的标志（整数）：1=true，0=false |

### imp.native（原生广告和推送通知）

| 属性      | 描述                                                                    |
| ------- | --------------------------------------------------------------------- |
| request | 符合原生广告规范的请求载荷——一个 **JSON 编码字符串** 的原生广告请求，包括其 **native** 顶层对象（JSON 对象） |
| ver     | 动态原生广告 API 的版本， **request** 符合（字符串）                                   |

### imp.native.request

| 属性        | 描述                                                                                                                                   |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| ver       | 所使用的 Native Markup 版本（字符串）                                                                                                           |
| context   | 广告出现的场景。在此情况下，它是 **1** (*以内容为中心的场景，例如新闻流、文章、图片画廊、视频画廊或类似场景*），可选（整数）                                                                  |
| plcmttype | 所提供广告单元的设计/格式/布局。目前我们支持 **4** (*推荐组件*）和 **500** (*推送通知*）（整数）                                                                         |
| plcmtcnt  | 此布局中相同展示位的数量（整数）                                                                                                                     |
| assets    | 一个 **资产对象**。任何竞价响应都必须符合竞价请求中表达的元素数组（JSON 对象数组）                                                                                       |
| seq       | 第一个广告为 0，第二个广告为 1，依此类推。注意，这通常不应与 plcmtcnt 结合使用——要么你正在对多个相同展示位进行竞价（此时 plcmtcnt>1，seq=0），要么你正在针对信息流中的不同项目分别进行竞价（此时 plcmtcnt=1，seq=>=1） |

### imp.native.request.assets

| 属性       | 描述                                                                                     |
| -------- | -------------------------------------------------------------------------------------- |
| id       | 唯一资产 ID，由交易平台分配。通常是数组中的计数器（整数）                                                         |
| 必需       | 设置为 **1** 如果资产是必需的，或 **0** 如果资产是可选的\*\*（整数）                                            |
| plcmtcnt | 此布局中相同展示位的数量（整数）                                                                       |
| img      | 用于图片素材的图像对象\*（JSON 对象）                                                                 |
| title    | 用于标题素材的标题对象\*（JSON 对象）                                                                 |
| data     | 用于品牌名称、描述、评分、价格等的数据对象\*（JSON 对象）                                                       |
| video    | 用于视频素材的视频对象。请参见 Video 请求对象定义。请注意，in-stream（即前贴片等）视频广告不属于 Native。原生广告可以将视频作为广告创意本身（对象）。 |

\* 每个资产对象中只应包含 {img, title, data} 中的一个对象

\*\* 资产会根据您的广告可能展示的发布商版位配置被标记为必需

### imp.native.request.assets.img

| 属性   | 描述                                                              |
| ---- | --------------------------------------------------------------- |
| type | 发布商支持的图像元素类型 ID。我们支持： **1** (*图标图片*）（整数）， **3** (*广告的大图预览*）（整数） |
| w    | 图片宽度，单位像素，可选（整数）                                                |
| h    | 图片高度，单位像素，可选（整数）                                                |
| wmin | 图片请求的最小宽度，单位像素（整数）                                              |
| hmin | 图片请求的最小高度，单位像素（整数）                                              |

### imp.native.request.assets.title

| 属性  | 描述                |
| --- | ----------------- |
| len | 标题元素中文本的最大长度。（整数） |

### imp.native.request.assets.video

| 属性            | 描述                                 |
| ------------- | ---------------------------------- |
| mimes         | 支持的 MIME 类型列表（字符串数组）。              |
| minduration   | 视频广告最小时长，单位秒（整数）。                  |
| maxduration   | 视频广告最长时长，单位秒（整数）。                  |
| protocols     | 支持的视频竞价响应协议列表（整数数组）。               |
| linearity     | 指示该展示是否必须为线性、非线性等（整数）。             |
| boxingallowed | 指示是否允许将 4:3 内容以黑边方式嵌入 16:9 窗口（整数）。 |

### imp.native.request.assets.data

| 属性   | 描述                                                                                                    |
| ---- | ----------------------------------------------------------------------------------------------------- |
| type | 发布商支持的元素类型 ID（整数）。我们支持： **1** (*sponsored - 赞助方信息，响应中应包含赞助商的品牌名称*), **2** (*desc - 与所广告产品或服务相关的描述文本*) |
| len  | 元素响应中文本的最大长度（整数）                                                                                      |

### imp.video

| 属性        | 描述                            |
| --------- | ----------------------------- |
| mimes     | 支持的 mime 类型列表（字符串数组）          |
| protocols | 支持的视频竞价响应协议列表（整数数组）           |
| skip      | 指示播放器是否允许跳过视频，其中 0 = 否，1 = 是  |
| skipafter | 在启用跳过前，视频必须播放的秒数；仅在广告可跳过时适用   |
| skipmin   | 总时长大于该秒数的视频可设置为可跳过；仅在广告可跳过时适用 |

{% hint style="info" %}
如果发布商在请求中提供了“skip”但未提供“skipafter”，则视频将在 5 秒后可跳过。响应将把“skipoffset”设为 5。\
如果发布商提供了“skip”但未提供“skipmin”，则无论视频时长如何，都可跳过。
{% endhint %}

## site

| 属性       | 描述                                    |
| -------- | ------------------------------------- |
| id\*     | 唯一站点 ID（字符串）                          |
| domain\* | 站点的域名（字符串）                            |
| cat      | IAB 类别 ID（字符串数组）                      |
| page     | 将展示广告的页面完整 URL（字符串）                   |
| keywords | 关键词可用于确保广告位获得正确类型的广告。关键词应为以逗号分隔的单词字符串 |
| ext      | 用于 OpenRTB 交易平台特定扩展的占位符。              |

\*这些属性对于 Direct Link 和 Email Clicks 格式是必需的。

### site.ext

| 属性          | 描述                      |
| ----------- | ----------------------- |
| exchangecat | 自定义 ExoClick 类别 ID（整数）  |
| idzone      | 自定义 ExoClick 广告位 ID（整数） |
| keyword     | 匹配关键词（如有）（字符串）          |

idzone 属性用于在 ExoClick 中标识流量来源。

## device

| 属性       | 描述                                                 |
| -------- | -------------------------------------------------- |
| ua       | 浏览器用户代理（字符串）                                       |
| sua      | 结构化的用户代理信息，可在客户端支持 User-Agent Client Hints 时使用（对象） |
| geo      | 通过 Geo 对象定义的设备位置，假定为用户当前位置。                        |
| ip       | 用户的 IP 地址（字符串）\*                                   |
| ipv6     | 用户的 IPv6 地址（字符串）\*                                 |
| language | 浏览器语言，使用 ISO-639-1 两位字母代码（字符串）                     |
| os       | 操作系统（字符串）                                          |
| js       | 是否支持 JavaScript，其中 0 = 否，1 = 是（整数）                 |
| ext      | 用于 OpenRTB 交易平台特定扩展的占位符                            |

\*竞价请求中只会出现 ip 或 ipv6 中的一个。

### device.geo

| 属性      | 描述      |
| ------- | ------- |
| country | 国家 ISO3 |

### device.ext

| 属性                | 描述                                     |
| ----------------- | -------------------------------------- |
| remote\_addr      | 用户的主 IP 地址（字符串）                        |
| x\_forwarded\_for | 用户的 X-FORWARDED-FOR IP 地址；若未设置则为空（字符串） |

### device.sua

结构化用户代理信息。 `device.sua` 被认为是设备属性更准确的表示。

| 属性           | 描述                                                                                                                                                                          |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| browsers     | 发送从 Sec-CH-UA-Full-Version-List 头部派生的品牌和版本。（ `BrandVersion` BrandVersion 对象数组）                                                                                              |
| platform     | 发送从 Sec-CH-UA-Platform 头部派生的品牌，以及从 Sec-CH-UA-Platform-Version 头部派生的版本。（`BrandVersion` 对象）                                                                                   |
| mobile       | 从 Sec-CH-UA-Mobile 头部派生此值。（整数）                                                                                                                                              |
| architecture | 从 Sec-CH-UA-Arch 头部获取此值。（字符串）                                                                                                                                               |
| bitness      | 从 Sec-CH-UA-Bitness 头部获取此值。（字符串）                                                                                                                                            |
| model        | 从 Sec-CH-UA-Model 头部获取此值。（字符串）                                                                                                                                              |
| source       | 用于创建此对象的数据来源， [列表：User-Agent 来源](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list--user-agent-source-) 在 AdCOM 1.0 中（整数；默认 0） |

### device.sua.browsers | device.sua.platform

| 属性      | 描述                                                                                                            |
| ------- | ------------------------------------------------------------------------------------------------------------- |
| brand   | 该值可能来自 User-Agent Client Hints 头部，表示用户代理品牌（来自 Sec-CH-UA-Full-Version 头部）或平台品牌（来自 Sec-CH-UA-Platform 头部）。（字符串） |
| version | 版本组件序列，按降序层级顺序 \[主版本、次版本、微版本、…]（字符串数组）                                                                        |

## user

| 属性 | 描述           |
| -- | ------------ |
| id | 唯一用户 ID（字符串） |

## ext

| 属性  | 必填？ | 描述                         |
| --- | --- | -------------------------- |
| sub | 否   | sub 将是一个整数，表示请求发起所在版位的 ID。 |

## regs.ext

| 属性       | 描述                             |
| -------- | ------------------------------ |
| dsaapply | 用于指示该请求是否适用 DSA 的标志。1 = 必需（整数） |
| dsa      | DSA 透明度信息的扩展（对象）               |

### regs.ext.dsa

| 属性        | 描述                                                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 必需        | 用于指示是否应提供 DSA 信息的标志。0 = 不需要，1 = 支持，包含或不包含 DSA 对象的竞价响应都可接受，2 = 必需，不包含 DSA 对象的竞价响应将不被接受，3 = 必需，不包含 DSA 对象的竞价响应将不被接受，发布商是在线平台（整数） |
| datatopub | 发布商可能需要透明度数据用于审计。0 = 不发送透明度数据，1 = 可选发送透明度数据，2 = 发送透明度数据（整数）                                                                    |

{% hint style="warning" %}
如果您收到 **dsaapply: 1** 和 **required: 2 或 3**，则必须在响应中添加带值的 dsa 属性，否则响应将被拒绝。
{% endhint %}

## 示例

您可以在我们的 [广告主请求示例页面](/rtb/zh/guang-gao-zhu/kai-fang-rtb/open-rtb-advertiser-code-examples.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.exoclick.com/rtb/zh/guang-gao-zhu/kai-fang-rtb/adv-open-rtb-2.4-request.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.