服务器到服务器 - 基础知识
实施 Singular 的 REST API 以进行完整的服务器端追踪，作为 SDK 集成的替代方案，从而完全控制数据收集、传输和归因工作流程。
选择您的集成方式：SDK 还是 S2S？ 如果您可以嵌入客户端 SDK，请从 SDK 集成文档 开始。当您需要服务器端事件传送、所在平台没有 SDK，或希望完全控制数据收集时，请使用服务器到服务器方式。本套文档涵盖 S2S 路径，并且是移动端、Web 和 PC/主机 S2S 指南的共享参考。
概览
服务器到服务器用例
服务器到服务器（S2S）集成提供 REST API 端点，用于构建完整的归因和分析解决方案，这些方案在您的后端基础设施上运行，无需在客户端应用中嵌入 Singular SDK。
集成方式：
- 纯 S2S： 100% 服务器端实施，同时处理会话追踪和事件追踪
- 混合式： Singular SDK 管理会话，同时服务器端处理事件追踪
混合式集成模式
混合式集成将用于会话管理的 Singular SDK 与用于后端事件追踪的服务器端 EVENT API 相结合，在实施的便捷性与服务器端的灵活性之间取得平衡。
混合式的优势：
- SDK 自动处理复杂的会话逻辑、深度链接和设备数据收集
- 服务器为在后端系统中处理的交易发送事件
- 降低客户端实施的复杂性
- 无需 SESSION 端点——SDK 管理会话生命周期
设备数据检索方法：
- 客户端管理流程： 在客户端捕获所需的数据点，并通过内部 API 转发到服务器，以配合 Singular EVENT 端点使用
- Internal BI 回传： 配置 Singular Internal BI 回传，以在安装、再互动或事件发生后接收包含设备标识符的实时 JSON 载荷（ 设置指南 ）
设备图谱维护： 两种方法都需要服务器端逻辑来维护设备图谱。当 SDK 检测到设备标识符发生变化时，请相应地更新服务器，以确保追踪的准确性。
实施资源：
- EVENT 端点必需参数
- 检索设备数据指南 （iOS/Android 代码示例）
关键集成原则
| 原则 | 说明 |
|---|---|
| 灵活性 | 完全控制数据收集和传输时机 |
| 功能对等 | 在提供适当数据的情况下支持所有 SDK 功能 |
| 集成路径 | 客户端 → 您的服务器 → Singular API |
| 实时处理 | 一次一个请求——不支持批量处理 |
| 顺序流程 | 事件必须按时间顺序处理 |
| 无去重 | Singular 不进行去重——请在服务器端实施去重 |
| 数据永久性 | 设备级数据在摄取后无法删除——请在发送前进行验证 |
集成要求
纯 S2S 集成需要为会话追踪和事件追踪实施全面的数据管道。
- 数据收集： 从客户端应用收集所需的数据点
- 设备图谱： 将数据转发到服务器并维护设备标识符存储
- 会话请求： 通过 SESSION API 发送会话通知
- 响应处理： 处理 Singular 响应并将其转发回客户端应用
- 事件请求： 通过 EVENT API 转发事件
相关 S2S 指南
本文是 S2S 套件的共享参考。请使用与您的平台相匹配的指南，并参阅端点参考以获取完整的参数详情。
平台指南
端点参考
功能指南
REST API 端点
Singular 提供两个主要的 REST API 端点，用于服务器到服务器的会话追踪和事件追踪。
Session 端点
会话追踪 API
SESSION 端点向 Singular 通知应用打开事件，以初始化用户会话，用于归因和留存追踪。
GET https://s2s.singular.net/api/v1/launch完整参考： SESSION 端点 API 参考
Event 端点
事件追踪 API
EVENT 端点追踪应用内事件和收入，用于归因分析和广告系列优化。
GET https://s2s.singular.net/api/v1/evt完整参考： EVENT 端点 API 参考
通用参数
这些参数在 Singular S2S REST API 的 SESSION 和 EVENT 端点之间共享。本节保存了它们的规范定义；其他 S2S 文章会链接到此处，而不是重新定义它们。
身份验证
| 参数 | 详情 |
|---|---|
a
|
用于 API 身份验证的 Singular SDK 密钥。 获取途径： Singular UI → 主菜单 → Developer Tools 。 重要提示： 请勿使用 Reporting API 密钥。请求将被拒绝。
示例：
|
设备标识符
设备标识符因平台和可用性而异。请包含适用于您平台的所有标识符。省略任何不可用的标识符——切勿传递 NULL 或空字符串。
| 参数 | 详情 |
|---|---|
idfa
|
平台： iOS 广告主标识符（IDFA） 支持广告追踪和广告系列归因。 ATT 要求： iOS 14.5+ 要求用户通过 App Tracking Transparency 框架选择加入。
示例：
|
idfv
|
平台： iOS 供应商标识符（IDFV） 在同一供应商的所有应用中保持一致。 始终必需： 无论 ATT 状态或 IDFA 可用性如何，都必须包含此参数。
示例：
|
aifa
|
平台：
Android
Google 广告 ID（GAID） 支持在 Android 上进行用户可重置的广告追踪。
示例：
|
asid
|
平台：
Android
Android App Set ID 为同一开发者提供注重隐私的跨应用追踪。 始终必需： 无论 GAID 是否可用，都必须在 Google Play 设备上包含此参数。
示例：
|
amid
|
平台：
Android
Amazon 广告 ID 适用于没有 Google Play 服务的 Amazon 设备。
示例：
|
oaid
|
平台：
Android
开放广告标识符（OAID），适用于没有 Google Play 服务的中国制造设备（华为、小米、OPPO 等）。
示例：
|
andi
|
平台：
Android
Android ID 是设备生成的 64 位标识符。 受限使用： 在 Google Play 设备上禁止使用——请改用 AIFA 和 ASID。仅当没有其他可用标识符且应用未通过 Google Play 分发时才发送。
示例：
|
sdid
|
平台： iOS、Android、PC、Xbox、PlayStation、Nintendo、MetaQuest、CTV Singular 设备 ID 是客户端生成的匿名化 UUIDv4，代表唯一的应用安装。 主标识符： 对于 PC 和主机应用而言，这是唯一相关的设备标识符。
示例：
|
设备参数
| 参数 | 详情 |
|---|---|
p
|
应用的平台。 允许的值（区分大小写）：
示例：
|
ip
|
示例：
|
ve
|
示例：
|
ma
iOS、Android |
设备制造商（厂商名称）。必须与
示例：
|
mo
iOS、Android |
设备型号。必须与
示例：
|
lc
iOS、Android |
IETF 区域设置标签——由下划线分隔的两字母语言代码和国家/地区代码。
示例：
|
bd
iOS、Android |
设备版本标识符，经过 URL 编码。
示例：
|
应用参数
| 参数 | 详情 |
|---|---|
i
|
应用标识符（区分大小写）。
示例：
|
app_v
|
示例：
|
att_authorization_status
iOS |
App Tracking Transparency（ATT）状态代码（iOS 14.5+）。 状态值：
始终必需：
即使未实施 ATT，也请传递
示例：
|
网络和位置参数
| 参数 | 详情 |
|---|---|
use_ip
|
指示 Singular 从 HTTP 请求中提取 IP 地址，而不是从
限制：
示例：
|
country
|
ISO 3166-1 alpha-2 两字母国家/地区代码。
必需情况：
当 IP 地址不可用或
示例：
|
ua
|
经过 URL 编码的 User Agent 字符串。
原始：
示例：
|
c
iOS、Android |
网络连接类型。
允许的值：
示例：
|
cn
iOS、Android |
示例：
|
数据隐私参数
| 参数 | 详情 |
|---|---|
data_sharing_options
|
经过 JSON URL 编码的最终用户数据共享同意。必须持久保存，并在所有后续的 SESSION 和 EVENT 请求中传递。 用户已同意（选择加入）： 用户已拒绝（选择退出）：
示例：
|
dnt
iOS、Android |
Do Not Track 状态。
示例：
|
dntoff
iOS、Android |
指示 Do Not Track 是否处于关闭状态。
示例：
|
跨设备支持
| 参数 | 详情 |
|---|---|
custom_user_id
|
用于跨设备追踪的您的内部用户 ID。 禁止 PII： 请勿传递个人身份信息。请使用经过哈希处理或以其他方式匿名化的内部标识符，而不是原始的电子邮件地址、电话号码或姓名。
示例：
|
实施阶段
成功的 S2S 集成需要按顺序执行四个关键实施阶段，以实现最佳的数据质量和归因准确性。
阶段 1：数据收集
必需的数据点
建立稳健的数据收集策略，捕获 Singular 平台功能所需的所有参数。
所有必需参数均为强制性： 省略必需参数会导致数据差异和归因错误。没有任何参数是可选的。
异步函数处理： 在收集客户端数据以进行服务器传输时，请等待异步函数完成并处理边缘情况。这是导致数据缺失和部分归因的常见问题。
实施资源：
- SESSION 端点必需参数
- EVENT 端点必需参数
- 检索设备数据指南 （iOS/Android 代码示例）
- SKAdNetwork 4 实施指南 （iOS 特定数据点）
阶段 2：实时流式传输
关键时机要求
实时数据流式传输可保持归因准确性，并支持对时间敏感的功能，例如 SKAdNetwork 转化值更新。
归因影响：
- 延迟的会话： 严重影响归因准确性——系统需要精确的时间数据才能进行广告系列关联
- SKAdNetwork 计时器： 转化值的严格设备端计时器窗口使得实时流式传输至关重要。延迟会导致错过转化值更新和广告系列数据不完整
最佳实践：
- 为应用会话启动实施服务器端事件侦听器
- 立即转发 会话数据 并附上所有必需参数
- 为应用内事件实施服务器端事件侦听器
- 立即转发 事件数据 并附上所有必需参数
- 使用 webhook 架构进行可靠的数据传输
- 为失败的请求实施重试机制
- 监控数据流以进行质量保证
阶段 3：响应处理
双向通信
响应处理将服务器端 API 交互与客户端功能连接起来，支持延迟深度链接和转化值更新。
关键响应类型：
- 延迟深度链接： API 响应包含待处理的深度链接数据，需要立即转发到应用以进行用户路由和个性化
- 转化值： iOS SKAdNetwork 转化值必须及时转发到应用，以进行准确的广告系列衡量
最佳实践：
- 在服务器基础设施上实施响应处理
- 解析并验证 Singular API 响应
- 将相关响应数据转发到客户端应用（对 iOS SKAdNetwork 至关重要）
- 实施客户端响应处理
- 使用适当的 HTTP 状态代码妥善处理错误
- 记录失败的响应以用于重试机制
阶段 4：测试与验证
数据流验证
测试阶段在生产部署之前验证完整的数据管道功能和归因准确性。
会话归因流程：
- 首次会话（新安装）： Singular 识别新安装并触发安装归因流程
- 符合再互动条件： Singular 触发再互动归因流程（ 再互动常见问题 ）
- 标准会话： Singular 记录会话，用于用户活动和留存指标
关键时机要求：
- 会话先于事件： 必须先接收单个 SESSION，然后才能接收任何事件。SDK 在应用打开时触发会话，然后发送应用内事件。在后台停留 1 分钟以上后，会话超时。当应用返回前台时会发送新会话。请使用应用生命周期事件和计时器来进行会话管理
- 实时事件： 应用中发生的事件必须在其各自的会话之后实时发送
验证清单：
- 测试会话数据流——验证首次和后续会话是否具有正确的数据点和值
- 确认仅在会话上报给 Singular 之后才接收事件（在会话之前发生的事件会产生自然量归因）
- 确认会话响应已处理并传递给客户端应用（对延迟深度链接至关重要）
集成完成：
- ✓ 数据收集和存储已验证
- ✓ 向 Singular 的实时流式传输已验证
- ✓ 响应处理和日志记录已验证
- ✓ 所有测试数据流已验证
测试指南： S2S 集成测试指南
附加功能
实施跨设备追踪、收入追踪、卸载监控和数据隐私合规，以实现全面的分析。
跨设备追踪
Custom User ID 实施
利用
custom_user_id
参数将用户与设备级会话关联起来，以进行跨设备报告和用户级分析。
隐私合规：
遵守数据隐私政策，避免在
custom_user_id
中使用个人身份信息（PII）。请使用经过哈希处理的用户名、电子邮件或随机生成的字符串作为唯一用户标识符。
在维护用户隐私的同时，支持全面的跨设备报告、用户级数据导出和 Internal BI 回传。
更多信息： Custom User ID 参数
收入追踪
应用内购买报告
追踪来自应用内购买的收入，用于投资回报率分析、广告系列效果衡量以及导出/回传的数据充实。
-
is_revenue_event：将事件标记为收入事件（如果事件名称为__iap__或金额 > 0，则跳过） -
purchase_receipt：Android/iOS 应用内购买对象——强烈建议提供，以获取交易详情和报告数据充实 -
receipt_signature（Android）：强烈建议提供，用于交易验证和欺诈防范 -
amt：以 Double 表示的收入金额（例如 "amt=1.99"） -
cur：ISO 4217 货币代码（例如 "cur=USD"）
实施指南： 订阅状态管理
数据隐私合规
用户同意处理
向 Singular 通知最终用户对数据共享的同意，以遵守 GDPR、CCPA 及其他隐私法规。
使用
data_sharing_options
参数来传达用户的选择：
-
{"limit_data_sharing":false}：用户已同意（选择加入）共享信息 -
{"limit_data_sharing":true}：用户拒绝共享信息
Singular 在
用户隐私回传
中使用
limit_data_sharing
，并将信息传递给需要合规的合作伙伴。
可选但推荐： 该参数为可选，但某些归因信息只有在用户明确选择加入时才会由合作伙伴共享。
更多信息： 用户隐私与限制数据共享