概览：网页端效果衡量S2S API支持通过服务器直接向AppsFlyer发送网页访问和事件数据，不受广告拦截器、Cookie限制等浏览器端限制的影响。您可以将S2S API与Web SDK搭配使用，也可以单独使用，以获取更完整、更高质量的归因数据。
关于网页端归因S2S API
AppsFlyer支持使用Web SDK（客户端）或S2S API（服务器对服务器，简称S2S）发送用于归因的网页端数据。您可以根据实际配置和需求单独使用其中一种方式，也可以组合使用。
Web SDK在浏览器中运行。S2S API则支持从自有后端发送相同的数据。S2S API之所以重要，是因为Safari ITP、Firefox ETP和Brave等隐私保护型浏览器及相关功能，以及广告拦截器，都可能阻止或限制客户端衡量。据行业估算，网页端用户中受浏览器端拦截影响的比例约为25%–40%。S2S调用由服务器发起，无需经过浏览器，因此完全不受上述限制影响。
工作原理
- 用户访问您的网站或在浏览器中触发事件。
- 您的服务器接收事件。
- 您的服务器将事件直接发送至AppsFlyer服务器进行归因。
为什么使用S2S
S2S API主要具有以下优势：
- 衡量服务器端事件：部分转化完全不会经过浏览器，例如由后端处理的订阅续订，或CRM系统中生成的事件。只有通过S2S API，才能将此类事件发送至AppsFlyer，并归因至相应的广告系列。
- 扩大衡量范围：S2S调用来自服务器，而非浏览器，因此不受广告拦截器、Safari ITP Cookie限制及其他浏览器端限制的影响。您可以捕获单靠客户端衡量会遗漏的访问和转化数据。
- 通过后端丰富事件数据：通过S2S API发送事件前，您的服务器可以向事件中添加更多数据，包括Customer User ID、经过哈希处理的电子邮件地址或电话号码、CRM属性、订阅状态或任意内部标识符。这样有助于提升身份解析能力和信号质量。
- 安全性：开发者密钥、用户标识符及其他补充数据均保存在您的服务器上，并通过安全连接发送，您可以完全控制哪些数据会传出自有基础架构。
API规范
基础URL：https://events.appsflyer.com
身份验证
所有请求均须在请求标头中包含有效的S2S API令牌，并指定正确的内容类型。
| 标头 | 类型 | 说明 |
|---|---|---|
Authorization |
API令牌 |
请按以下格式在标头中添加您的S2S API令牌： Authorization: Bearer {s2s-token} |
Content-Type |
字符串 | 必须为application/json。所有请求均须包含此项。 |
注意
如需创建S2S API令牌，请参阅管理AppsFlyer令牌中的说明。
衡量事件
POST /v2.0/s2s/inapps/app/web/{appId}
衡量指定应用的网页端事件，例如购买、注册或自定义操作。
路径参数
| 参数 | 是否必填 | 说明 |
|---|---|---|
appId |
是否必填 | AppsFlyer中定义的unified_app_id。例如：website-www.example.com
|
请求正文
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
user_id |
对象 | 是否必填 | 用户标识符。必须至少包含customer_user_id或appsflyer_id中的一项。 |
event_name |
字符串 | 是否必填 | 事件名称。1–64个字符。不得包含@ = + -。示例：af_purchase
|
event_revenue |
数值（double） | 选填 | 购买或变现事件的收入金额。 |
event_revenue_currency |
字符串（ISO-4217） | 选填 | 收入金额对应的货币代码。例如USD或EUR。 |
event_value |
对象 | 选填 | 可自由定义的事件参数。支持custom_parameters子对象。 |
event_url |
字符串 | 选填 | 事件发生页面的URL。必须是有效的HTTP URL，最多4096个字符。 |
timestamp |
整数（int64） | 选填 | Unix时间戳，单位为毫秒（UTC）。未提供时，AppsFlyer将使用事件接收时间。延迟接收窗口：事件必须在应用时区次日00:30前送达。 |
ip |
字符串 | 选填 | 设备IP地址（IPv4或IPv6）。最多46个字符。 |
user_agent |
字符串 | 选填 | 浏览器的完整用户代理字符串。最多1024个字符。 |
http_referrer |
字符串 | 选填 | 当前页面的引荐来源URL。 |
customer_dedup_id |
字符串 | 选填 | 客户提供的去重标识符。 |
email_hashed |
字符串 | 选填 | 规范化电子邮件地址（转为小写并删除首尾空格）的SHA256哈希值。必须是64个字符的十六进制字符串。 |
phone_number_hashed |
字符串 | 选填 | 电话号码的SHA256哈希值。必须是64个字符的十六进制字符串。 |
phone_number_e164_hashed |
字符串 | 选填 | E.164格式电话号码的SHA256哈希值（例如+14155552671）。必须是64个字符的十六进制字符串。 |
first_name_hashed |
字符串 | 选填 | 规范化名字的SHA256哈希值。必须是64个字符的十六进制字符串。 |
last_name_hashed |
字符串 | 选填 | 规范化姓氏的SHA256哈希值。必须是64个字符的十六进制字符串。 |
请求示例
{"user_id":{"customer_user_id":"15667737-366d-4994-ac8b-653fe6b2be4a"},"event_name":"af_purchase","event_revenue":49.99,"event_revenue_currency":"USD","event_value":{"af_content_id":"SKU-001","af_quantity":2,"custom_parameters":{"promo_code":"SUMMER10"}},"event_url":"https://example.com/checkout/success","timestamp":1712000000000,"ip":"35.244.183.10","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...","email_hashed":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"}响应
| 状态 | 说明 |
|---|---|
| 202 Accepted | 请求已接受。返回状态、消息以及可选的messageId。 |
| 400 Bad Request | 字段无效或缺失。 |
| 401 Unauthorized | 应用不存在或身份验证失败。 |
| 403 Forbidden | 应用流量已被屏蔽。 |
| 415 Unsupported Media Type |
Content-Type必须为application/json。 |
衡量访问
POST /v2.0/s2s/visits/app/web/{appId}
衡量指定网页端应用的页面访问。此端点与事件端点使用相同的基础字段，但有两项主要区别：event_url为必填项，事件名称和收入字段不适用。
路径参数
| 参数 | 是否必填 | 说明 |
|---|---|---|
appId |
是否必填 | AppsFlyer中定义的unified_app_id。例如：website-www.example.com
|
请求正文
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
user_id |
对象 | 是否必填 | 用户标识符。必须至少包含customer_user_id或appsflyer_id中的一项。 |
event_url |
字符串 | 是否必填 | 所访问页面的URL。必须是有效的HTTP URL，最多4096个字符。 |
timestamp |
整数（int64） | 选填 | Unix时间戳，单位为毫秒（UTC）。未提供时，AppsFlyer将使用事件接收时间。延迟接收窗口：访问必须在应用时区次日00:30前送达。 |
ip |
字符串 | 选填 | 设备IP地址（IPv4或IPv6）。最多46个字符。 |
user_agent |
字符串 | 选填 | 浏览器的完整用户代理字符串。最多1024个字符。 |
http_referrer |
字符串 | 选填 | 当前页面的引荐来源URL。 |
event_value |
对象 | 选填 | 可自由定义的事件参数，其中包括custom_parameters子对象。 |
customer_dedup_id |
字符串 | 选填 | 客户提供的去重标识符。 |
email_hashed |
字符串 | 选填 | 规范化电子邮件地址的SHA256哈希值。必须是64个字符的十六进制字符串。 |
phone_number_hashed |
字符串 | 选填 | 电话号码的SHA256哈希值。必须是64个字符的十六进制字符串。 |
phone_number_e164_hashed |
字符串 | 选填 | E.164格式电话号码的SHA256哈希值必须是64个字符的十六进制字符串。 |
first_name_hashed |
字符串 | 选填 | 规范化名字的SHA256哈希值。必须是64个字符的十六进制字符串。 |
last_name_hashed |
字符串 | 选填 | 规范化姓氏的SHA256哈希值。必须是64个字符的十六进制字符串。 |
请求示例
{"user_id":{"appsflyer_id":"1234567890abcdef","customer_user_id":"15667737-366d-4994-ac8b-653fe6b2be4a"},"event_url":"https://example.com/products/sneakers","timestamp":1712000000000,"ip":"35.244.183.10","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...","http_referrer":"https://www.google.com/","email_hashed":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"}响应
| 状态 | 说明 |
|---|---|
| 202 Accepted | 请求已接受。返回状态、消息以及可选的messageId。 |
| 400 Bad Request | 字段无效或缺失。 |
| 401 Unauthorized | 应用不存在或身份验证失败。 |
| 403 Forbidden | 应用流量已被屏蔽。 |
| 415 Unsupported Media Type |
Content-Type必须为application/json。 |
配置完全基于服务器端的对接
如果您同时使用Web SDK和S2S，请改为参阅提取Web SDK的afUserID。本节仅适用于完全不使用SDK的对接方式。
如果您的网站完全未使用Web SDK，则需要自行完成Web SDK通常会处理的所有任务，包括设置用户Cookie、发送正确的标识符，以及确保每个事件的有效负载完整无缺。正确完成配置后，您将获得为什么使用S2S中介绍的全部优势，但前提是准确处理上述细节。
除事件外，还需发送访问数据
访问数据包含后续所有事件所依赖的归因参数，系统要求先接收用户的访问数据，再接收该用户的任何事件。如果先发送事件、后发送访问数据，系统会将该事件归类为自然量。
通过HTTP设置第一方Cookie
由于没有Web SDK为您设置afUserId Cookie，您需要自行设置和管理。该Cookie需作为HTTP Cookie通过Set-Cookie响应标头设置，不应通过JavaScript写入客户端。
原因在于，通过document.cookie设置的客户端Cookie有效期很短：在Safari中最快7天后过期，在受ITP限制的域名中最快仅24小时后过期。Cookie过期后，标识符会重置，回访用户也会被视为新用户。由服务器设置的Cookie不受上述期限限制，可持续保留至浏览器允许的最长期限（Chrome最长为400天）。还可将Cookie标记为HttpOnly，使页面脚本和广告拦截器无法读取或移除，并且完全无需依赖页面上运行的任何脚本。
设置和读取方法：
- 收到未携带Cookie的访客首次请求时，在服务器上生成一个稳定的唯一ID（例如UUID）。
-
通过第一方Cookie返回该ID：
Set-Cookie: af_web_id=<generated-id>; Max-Age=34128000; Path=/; Secure; HttpOnly; SameSite=Lax - 后续每次收到请求时，从传入的Cookie标头中读取并重复使用该值。不得重新生成该值。
- 每次向AppsFlyer发起调用时，都需要将该值作为请求
user_id对象中的appsflyer_id发送。
Cookie可以任意命名；AppsFlyer读取的是您发送的值，与Cookie名称无关。只需确保通过自有第一方域名设置Cookie。
每次调用均需发送正确的标识符
每次调用都必须包含user_id对象，并至少提供appsflyer_id（Cookie值）或customer_user_id（您的内部用户ID）中的一项。同时发送两项可提升身份解析能力。
需要注意：访问通常来自匿名用户，因此必须始终发送Cookie值。对于站内事件，识别出用户身份后，需添加customer_user_id，并继续同时发送Cookie值。对于并非来自浏览器的事件，只需发送customer_user_id，前提是AppsFlyer已在之前的会话中识别出该用户。
注意事项
用户识别
每个请求都必须包含user_id对象。必须至少提供以下一个标识符。
| 字段 | 类型 | 说明 |
|---|---|---|
customer_user_id |
字符串（1–64个字符） | 您在自有系统中设置的内部用户标识符。 |
appsflyer_id |
字符串（至少1个字符） | AppsFlyer为网页端用户分配的内部标识符。使用AppsFlyer Web SDK时，可从Web SDK Cookie中获取appsflyer_id值。从afUserId中提取该值。参阅提取Web SDK的afUserId
|
延迟接收窗口
事件和访问数据必须在应用时区次日00:30前送达。对于延迟送达的事件，系统将改用服务器接收时间。
经过哈希处理的PII字段
所有个人数据字段都必须在发送前进行SHA256哈希处理。进行哈希处理前，需先将文本规范化（转换为小写并删除首尾空格）。每个哈希值必须为64个十六进制字符，不区分大小写。
- 所有哈希字段均须遵循以下格式：
^[a-fA-F0-9]{64}$ -
phone_number_e164_hashed字段中的电话号码必须先转换为E.164格式（例如+14155552671），再进行哈希处理。
提取Web SDK的afUserID
-
afUserId参数是Web SDK在用户首次访问网站时设置的唯一标识符。 - 如需获取
afUserId，可使用以下任一方法。
从HTTP Cookie标头中获取afUserId
- 访客浏览器向您的网站发起请求时会发送
afUserId。 - 如有需要，可从HTTP Cookie标头中提取该值。
在访客浏览器中查看afUserId
- 可在访客浏览器中查看
afUserId，用于问题排查和调试。 - 访客必须至少访问过一次已部署Web SDK的页面，才能获取该值。
- 包含
afUserId的Cookie属于您域名下的第一方Cookie。 - 以下操作步骤基于Chrome 81编写。不同浏览器和操作系统中的操作可能有所不同。
如需从访客浏览器中获取afUserId：
- 在浏览器中打开您的网站。
- 右键单击，然后选择检查。浏览器开发者工具窗口随即打开。
- 打开（A）Application标签页。
- 在侧边菜单中展开（B）Cookies。
- 选择您的网站。若未显示，刷新浏览器。
- 在（C）filter字段中输入
afUserId。页面随即显示afUserID的值。
This article was translated using AI and may contain errors. For the most accurate information, please refer to the English version using the language selector.