> 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/api/zh/guang-gao-tou-fang-api/ad-plac-request.md).

# 请求

广告投放 API 可从以下任一端调用 **客户端** 端或 **服务端** 端。

在使用 **客户端** 端实现时，浏览器可能执行一次 **预检** 请求。如果您希望避免这种情况，请在请求头中使用 `Content-Type: text/plain`。这将确保浏览器将该请求判定为“简单”请求，因此会跳过预检请求。

另外，在 **客户端** 端调用 API 时， **实际上并不需要 IP** 因为使用前端和 JavaScript 检测 IP 可能很困难。相反，我们的 API 会在发出请求时从连接中检测 IP。

在使用 **服务端** 端实现中，为确保正确定向， **应显式传递用户的正确 IP**。否则，广告将按服务器位置进行定向，这可能会导致后续因 IP 不匹配而使展示失效。

无论使用客户端还是服务端，如果传递了 IP，它都将优先于我们检测到的 IP。

要向广告投放 API 发起请求，您需要传递两个对象： **user** and **zones**。请求使用 HTTP POST，以 JSON 形式发起。

## user

| 参数                  | 必填？ | 描述                                                                                                                     |
| ------------------- | --- | ---------------------------------------------------------------------------------------------------------------------- |
| id                  | 否   | 用户 ID                                                                                                                  |
| ip                  | 推荐  | 用户的 IP 地址。                                                                                                             |
| ua                  | 是   | User Agent：包含用户的浏览器/应用和设备/操作系统信息的字符串。                                                                                  |
| language            | 否   | 使用以下方式设置请求语言： [标准的两位 ISO 代码](https://www.andiamo.co.uk/resources/iso-language-codes/) 再加上可选的两位区域代码。例如： `en-us` 表示美国英语。 |
| referer             | 否   | 广告将展示所在网站的地址。                                                                                                          |
| el                  | 否   | 用户的 Base64 编码电子邮件。                                                                                                     |
| screen\_resolution  | 否   | 用户所使用设备的屏幕分辨率                                                                                                          |
| window\_orientation | 否   | 如果网站为移动版布局，则应为“portrait”；如果为桌面版，则应为“landscape”。                                                                        |
| gdpr                | 否   | 隐私建议扩展（对象）。                                                                                                            |

### user.gdpr

| 参数      | 描述                                                        |
| ------- | --------------------------------------------------------- |
| gdpr    | 这应为 **0** 如果调用方认为该用户不受 GDPR 约束，则为 **1** 如果用户受 GDPR 约束，则为。 |
| consent | 这是 IAB 标准要求的同意字符串。                                        |

## zones

| 参数                | 必填？ | 描述                                                                                                                                       |
| ----------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| id                | 是   | 广告区位 ID                                                                                                                                  |
| sub               | 否   | 广告区位的子 ID                                                                                                                                |
| keywords          | 否   | 任何 [keywords](/advertisers/campaigns/creating-a-campaign/create-campaign-step3.md#keywords) 与流量相关、可能匹配特定广告类型的关键词。如果没有关键词，将使用网站的 URL 进行匹配 |
| custom\_targeting | 否   | 自定义区位值（对象）                                                                                                                               |

### zones.custom\_targeting

| 参数     | 描述                                             |
| ------ | ---------------------------------------------- |
| ex\_av | 这应为 **0** 如果未定义， **1** 如果已验证年龄，且 **2** 如果未验证年龄 |

## 示例

可以在一次请求中请求多个广告区位。每个区位都会有不同的 ID，正如您在下面的示例中所示。

```json
{
  "user": {
    "id": "abdef8u9",
    "ip": "10.42.0.1",
    "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
    "language": "en-US",
    "referer": "https://blabla.com",
    "gdpr": {
      "gdpr": 1,
      "consent": "CPAoZRHPArq3hBcADBENBJCgAAAAAAAAAAqIHKQAAOUgAAAA"
    }
  },
  "zones": [
    {
      "id": 4031007,
      "sub": 111,
      "keywords": "humour, general"
    },
    {
      "id": 4031015,
      "sub": 222
    },
    {
      "id": 4031019,
      "sub": 222
    }
  ]
}
```


---

# 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/api/zh/guang-gao-tou-fang-api/ad-plac-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.