服务器到服务器 - 基础知识

关注
Avatar
Jared Ornstead
Updated

Server-to-Server - 基础知识

实施 Singular 的 REST API 以实现完整的服务器端追踪，作为 SDK 集成的替代方案，从而完全掌控数据收集、传输和归因工作流。

选择你的集成方式：SDK 还是 S2S？ 如果你能够嵌入客户端 SDK，请先查看 SDK 集成文档 。当你需要服务器端事件投递、所在平台没有 SDK，或者希望完全掌控数据收集时，请使用 Server-to-Server。本套文档涵盖 S2S 路径，并作为 Mobile、Web 和 PC/主机 S2S 指南的共享参考。

概述

Server-to-Server 使用场景

Server-to-server（S2S）集成提供 REST API 端点，可在你的后端基础设施上构建完整的归因和分析方案，无需在客户端应用中嵌入 Singular SDK。

集成方式：

  • 纯 S2S： 100% 服务器端实施，同时处理会话和事件追踪
  • 混合模式： Singular SDK 管理会话，同时由服务器端处理事件追踪

纯 S2S 集成

纯 S2S 是完全的服务器端实施：由你的后端收集所需数据、维护设备图谱，并将会话和事件同时投递给 Singular。分步流程请参见下方的实施阶段。

混合集成模式

混合集成将用于会话管理的 Singular SDK 与用于后端事件追踪的服务器端 EVENT API 相结合，在易于实施与服务器端灵活性之间取得平衡。

混合模式的优势：

  • SDK 自动处理复杂的会话逻辑、深度链接和设备数据收集
  • 服务器端发送在后端系统中处理的交易事件
  • 降低客户端实施的复杂度
  • 无需 SESSION 端点——由 SDK 管理会话生命周期

混合 S2S 数据流

设备数据获取方式：

  1. 客户端管理流程： 在客户端捕获所需的数据点，并通过内部 API 转发到服务器，以配合 Singular EVENT 端点使用
  2. Internal BI 回传： 配置 Singular Internal BI 回传，以在安装、再互动或事件发生后接收包含设备标识符的实时 JSON 负载（ 设置指南 ）

设备图谱维护： 两种方式都需要服务器端逻辑来维护设备图谱。当 SDK 检测到设备标识符发生变化时，请相应更新服务器，以确保追踪准确。

相关资源：

关键集成原则

无论你使用哪个平台或采用哪种方式，这些原则都适用于每一次 S2S 集成：

原则 说明
灵活性 完全掌控数据收集和传输时机
功能对等 在提供恰当数据的前提下，支持所有 SDK 功能
集成路径 客户端 → 你的服务器 → Singular API
实时处理 一次处理一个请求——不支持批量处理
顺序流程 事件必须按时间顺序处理
不去重 Singular 不做去重——请在服务器端实现去重
数据永久性 设备级数据一经摄入即无法删除——发送前请先验证

实施阶段

完整的 S2S 集成会经历四个阶段，按顺序进行，每个阶段都建立在前一阶段的基础之上。

阶段 1：数据收集

必需的数据点

建立数据收集机制，捕获每一个必需参数，使 Singular 拥有准确归因和报告所需的一切。

所有必需参数均为强制项： 遗漏必需参数会导致数据差异和归因错误。没有任何参数是可选的。

异步函数处理： 在收集客户端数据以传输至服务器时，请等待异步函数完成并处理边缘情况。这是导致数据缺失和归因不完整的常见问题。

实施资源：

阶段 2：实时流式传输

关键时序要求

实时数据流式传输可维持归因准确性，并支持诸如 SKAdNetwork 转化值更新等对时间敏感的功能。

对归因的影响：

  • 延迟的会话： 严重影响归因准确性——系统需要精确的时间数据来关联广告系列
  • SKAdNetwork 计时器： 转化值的设备端计时窗口非常严格，使实时流式传输至关重要。延迟会导致错过转化值更新和广告系列数据不完整

最佳实践：

  • 为应用会话启动实现服务器端事件监听器
  • 立即转发 会话数据 ，并包含所有必需参数
  • 为应用内事件实现服务器端事件监听器
  • 立即转发 事件数据 ，并包含所有必需参数
  • 采用 webhook 架构以实现可靠的数据传输
  • 为失败的请求实现重试机制
  • 监控数据流以进行质量保障

阶段 3：响应处理

双向通信

响应处理将你的服务器端 API 调用连回客户端应用，这正是实现延迟深度链接和转化值更新的关键所在。

关键响应类型：

  • 延迟深度链接： API 响应包含待处理的深度链接数据，需立即中继给应用，以进行用户路由和个性化
  • 转化值： iOS SKAdNetwork 转化值必须及时转发给应用，以实现准确的广告系列衡量

最佳实践：

  • 在服务器基础设施上实现响应处理
  • 解析并验证 Singular API 响应
  • 将相关响应数据转发给客户端应用（对 iOS SKAdNetwork 至关重要）
  • 实现客户端响应处理
  • 以恰当的 HTTP 状态码优雅地处理错误
  • 记录失败的响应以用于重试机制

阶段 4：测试与验证

数据流验证

在部署到生产环境之前，请端到端验证完整的数据管道，并确认归因准确无误。

会话归因流程：

  • 首次会话（新安装）： Singular 识别新安装并触发安装归因流程
  • 符合再互动条件： Singular 触发再互动归因流程（ 再互动常见问题 ）
  • 标准会话： Singular 记录会话，用于用户活跃度和留存指标

关键时序要求：

  1. 会话先于事件： 必须先接收到单个 SESSION，然后才能接收任何事件。SDK 在应用打开时触发会话，随后发送应用内事件。应用进入后台 1 分钟以上后，会话会超时。应用重回前台时会发送新会话。请使用应用生命周期事件和计时器进行会话管理
  2. 实时事件： 应用内发生的事件必须在其对应会话之后实时发送

验证清单：

  • 测试会话数据流——验证首次及后续会话具有正确的数据点和值
  • 确认仅在会话上报给 Singular 之后才接收事件（会话之前的事件会造成自然量归因）
  • 确认会话响应已被处理并传递给客户端应用（对延迟深度链接至关重要）

集成完成：

  • ✓ 数据收集与存储已验证
  • ✓ 向 Singular 的实时流式传输已验证
  • ✓ 响应处理与日志记录已验证
  • ✓ 所有测试数据流已验证

测试指南： S2S 集成测试指南

附加功能

实施跨设备追踪、收入追踪、卸载监控以及数据隐私合规，以获得全面的分析能力。

跨设备追踪

自定义用户 ID 的实施

利用 custom_user_id 参数将用户与设备级会话关联起来，以进行跨设备报告和用户级分析。

隐私合规： 遵守数据隐私政策，避免在 custom_user_id 中使用个人身份信息（PII）。请使用经过哈希处理的用户名、电子邮件，或随机生成的字符串作为唯一用户标识符。

在保护用户隐私的同时，支持全面的跨设备报告、用户级数据导出以及 Internal BI 回传。

更多信息： 自定义用户 ID 参数

收入追踪

应用内购买报告

追踪应用内购买产生的收入，用于 ROI 分析、广告系列效果衡量以及导出/回传数据的丰富。

使用 EVENT 端点 以及 收入参数 ：

  • is_revenue_event：收入事件设为 true；否则设为 false。
  • 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 ，并将信息传递给需要合规的合作伙伴。

可选但推荐： 该参数为可选，但某些归因信息只有在用户明确选择加入时才会由合作伙伴共享。

更多信息： 用户隐私与限制数据共享

端点参考

每个端点参考都在其内文档中完整记录了必需和可选参数。完整的参数表请参见以下内容：

指南

本文是 S2S 套件的共享参考。请使用与你的平台匹配的指南，并参考端点参考获取完整的参数详情。

平台指南

功能指南