Singular SDK 集成：规划与前提条件

关注
Avatar
Jared Ornstead
Updated

SDK 集成前提条件

Singular SDK 集成前所需的基本准备步骤，涵盖规划、应用注册、域名配置和测试准备。

必要准备步骤： 以下步骤是任何 Singular SDK 集成所必需的。

了解如何规划 SDK 集成、注册开发用应用、创建追踪链接域名，以及在实施过程中和实施后准备测试工作流程。

目标受众 业务团队、营销团队、开发团队
前提条件 Singular 账户访问权限、应用 Bundle ID、营销 KPI 定义

集成概述

跨部门协作

Singular SDK 的成功集成需要营销、业务和开发团队之间的协作，以定义需求、配置追踪并验证实施情况。

团队职责：

团队 职责
营销/业务
  • 定义事件追踪需求和营销 KPI
  • 选择用于推广活动追踪的链接域名
  • 在 Singular 平台中配置生产应用设置
  • 审核并批准测试流程
开发
  • 按照技术规范实施 SDK 集成
  • 在 Singular 平台中注册开发/测试应用
  • 配置深度链接和追踪链接处理程序
  • 执行测试流程和验证

第 1 步：规划 SDK 集成

在开始 SDK 集成之前，营销和业务团队必须回答关键问题，使开发团队能够实施适当的 SDK 功能。

儿童隐私合规

面向儿童的应用

问题： 此应用是否明确面向儿童？

面向儿童的应用必须遵守保护儿童隐私的 Play Store 和 App Store 政策。Singular 提供专业的 SDK 以满足合规要求。

推荐解决方案： 使用 Singular 儿童应用 SDK，通过不捕获设备标识符来帮助遵守隐私政策。

深度链接配置

深度链接处理

问题： 应用是否需要处理深度链接？

深度链接可将用户从营销推广活动、推送通知或网页等外部来源引导至应用内的特定内容。

实施要求：

  • 前提条件： 遵循 Singular Links 前提条件进行域名和平台配置。
  • 深度链接处理程序： 按照相关 SDK 指南（iOS、Android、React Native 等）中的说明在代码中实施处理程序。
  • 测试： 使用 Testing Console 和手动测试流程验证深度链接功能。

事件追踪策略

应用内事件规划

问题： 应用是否需要追踪用户事件？

Singular 收集应用内事件数据以分析推广活动效果并衡量 KPI。事件策略应与营销目标和用户价值衡量保持一致。

标准事件

标准事件的优势

Singular 支持各类标准事件，这些事件在各垂直行业中广泛使用，且通常受到广告网络的支持，可用于报告和优化。

优势：

  • 自动识别： Singular 自动识别标准事件并将其添加到事件列表，无需手动定义。
  • 合作伙伴支持： 广告网络支持标准事件用于推广活动优化和报告。
  • 行业对齐： 跨平台和合作伙伴的一致命名规范
  • 最佳实践： 事件与标准定义匹配时的推荐方法

标准事件归因

对于每个标准事件，传递推荐的标准归因以实现完整的数据捕获和合作伙伴兼容性。

示例： sng_content_view 事件（用户查看产品）应包含：

  • sng_attr_content_type - 查看的内容类型
  • sng_attr_content_id - 唯一内容标识符
  • sng_attr_content - 内容描述或名称

事件策略资源

UA/营销/业务团队应使用以下资源，基于营销 KPI 编制事件列表：

特定平台的事件名称

开发者注意： SDK 集成可能需要根据开发平台使用略有不同的事件/归因名称格式（全部大写、无下划线等）。

各平台列表：

自定义事件

自定义事件定义

如果事件与 Singular 的标准事件不匹配，请为特定追踪需求定义具有自定义名称的自定义事件。

自定义事件指南：

  • 字符限制： 最多 32 个字符
  • 语言： 建议使用英文名称，以便与从 Singular 接收事件的广告网络合作伙伴保持兼容。
  • 命名规范： 使用描述性、一致的命名以便于清晰理解和维护。
  • 文档记录： 维护记录自定义事件名称和用途的事件目录。

事件追踪范围

最佳实践： 仅在营销相关目的需要时才向 Singular 发送事件。如果某事件对推广活动绩效 KPI 或用户价值指标没有重要意义，则不应由 Singular 追踪。

事件选择标准：

  • 营销相关性： 事件为推广活动优化提供洞察。
  • KPI 衡量： 事件有助于关键绩效指标的衡量。
  • 用户价值： 事件表明用户参与度或变现情况。
  • 合作伙伴优化： 事件被广告网络用于推广活动定向。

iOS 专属配置

SKAdNetwork 实施

问题（iOS）： 应用是否需要实施 SKAdNetwork？

SKAdNetwork 无需用户级追踪权限即可在 iOS 上实现隐私保护归因。Singular 支持两种实施模式。

SKAdNetwork 模式：

  • 托管模式： Singular 根据预定义规则自动更新转化值。
  • 手动模式： 应用使用 SDK 方法直接更新转化值。

应用追踪透明度 (ATT)

问题（iOS）： 应用是否需要请求用户许可以共享追踪信息 (ATT)？

Singular 建议显示 ATT 提示，因为用户选择加入后可以共享设备 ID (IDFA)，从而提高安装归因的准确性。

配置要求： 如果显示 ATT 提示，请将 SDK 配置为延迟 Singular 初始化，直到用户响应提示。这可确保归因捕获正确的追踪授权状态。

ATT 实施：

  • 提示时机： 在初始化 Singular SDK 之前显示 ATT 提示。
  • SDK 配置： 使用 SDK 配置选项等待 ATT 响应。
  • IDFA 捕获： 如果用户授予权限，则收集 IDFA 用于确定性归因。
  • 备用归因： 如果用户拒绝权限，归因使用设备指纹和 IDFV。

第 2 步：注册开发应用

使用与生产应用不同的 Bundle ID 在 Singular 平台中注册开发/测试应用，以便在测试期间保持数据隔离。

Bundle ID 策略

开发与生产环境

生产应用和测试应用使用相同的 SDK Key 和 Secret Key。数据一旦保存到 Singular，便无法删除。

推荐方法： 为测试应用使用不同的 Bundle Identifier，以保持数据与生产应用的隔离。在将应用发布到应用商店之前，将 Bundle ID 更改为生产版本。

Bundle ID 示例：

环境 Bundle ID
生产 com.myapp
开发/测试 com.myapp.dev

应用注册步骤

平台配置

如何注册开发应用

注册流程

  1. 导航至应用： 在 Singular 平台中，前往 Settings → Apps，然后点击 Add New App。
  2. 输入应用名称： 输入开发应用的名称（建议使用 Bundle ID 以便于识别）。
  3. 选择平台： 选择与应用平台对应的操作系统（iOS 或 Android）。
  4. 配置 Bundle ID： 选择 Bundle ID 选项，输入 Bundle Identifier 的开发版本，然后保存应用。
  5. 仅 iOS - 高级设置： 保存应用后，点击应用名称旁边的箭头查看详情。
    • 切换 Show Advanced Settings 选项。
    • 添加 Team ID（Universal Links 所需）。
    • 添加 Scheme（深度链接所需）。

开发后更新

完成开发和测试后：

  1. 更新 Bundle ID： 在应用配置中将 Bundle ID 更改为生产版本。
  2. 生产应用设置： 营销团队按照 应用配置 FAQ 的说明添加生产应用。

重要： 在将应用发布到 App Store 或 Play Store 之前，请确保 Bundle ID 已更新为生产值。Bundle ID 不匹配将导致无法正常进行归因和追踪。

第 3 步：创建链接域名

为 Singular 追踪链接建立自定义域名，实现品牌推广活动 URL 和深度链接功能。

链接域名结构

Singular 链接格式

Singular Links（Singular 追踪链接）采用带有自定义子域名的标准化结构：

https://[SUBDOMAIN].sng.link/[PARAMETERS]

示例： 对于名为"Jewel Rush"的应用，创建域名 jewelrush.sng.link，即可使用以下结构的追踪链接：

https://jewelrush.sng.link/[PARAMETERS]

域名策略

单一域名与多个域名

企业可以对所有链接使用单一域名，也可以为不同目的（应用、品牌、推广活动等）创建多个域名。

要求： 使用 Singular Tracking Links 前至少需要一个域名。营销团队应参与域名选择，因为它将出现在营销推广活动和面向用户的材料中。

域名使用场景：

  • 单一域名： 所有应用和推广活动的所有追踪链接使用一个域名
  • 应用专属： 每个应用使用单独的域名以提升品牌辨识度
  • 推广活动专属： 不同类型的推广活动使用不同域名
  • 地域性： 本地化推广活动使用地区域名

iOS 域名配置

关联域名设置

在 iOS 应用中集成 Singular SDK 时，在 Xcode 关联域名设置中添加链接域名以支持 Universal Links。

关联域名格式：

applinks:[DOMAIN].sng.link

示例：

applinks:jewelrush.sng.link

更多资源： 有关完整的域名设置和配置说明，请参阅 Singular Links 前提条件。

第 4 步：规划集成测试

使用 Singular 的测试工具和验证流程，在发布应用之前验证 SDK/S2S 集成功能。

测试策略

测试阶段

全面测试分两个阶段进行：实施过程中的实时验证和实施完成后的全面集成验证。

实施过程中的测试

实时验证工具

使用提供即时反馈的实时验证工具，在实施功能的同时进行测试。

Testing Console

使用 Testing Console 在实施过程中实时手动测试各种 SDK 功能。

Testing Console 的优势：

  • 实时反馈： 即时验证 SDK 调用和数据传输
  • 逐一功能测试： 在开发过程中逐步测试各项功能
  • 调试支持： 立即识别配置问题和数据问题
  • 会话追踪： 验证会话初始化和事件追踪

第三方调试工具

使用代理工具进行流量检查和验证的替代测试方法。

Charles Proxy 设置：

  • 安装 Charles Proxy 或类似的网络检查工具。
  • 启用 SSL 代理以检查 HTTPS 流量。
  • 验证 Singular 数据是否在正确的时间以正确的参数触发。
  • 验证 API 端点调用和响应代码。
实施完成后的测试

全面验证工具

完成实施后，使用自动化和手动工具进行全面集成验证。

SDK 审计报告

运行 SDK 审计报告，自动识别集成问题并获取推荐解决方案。

审计报告功能：

  • 自动检测： 识别缺失或配置错误的 SDK 功能。
  • 最佳实践验证： 根据 Singular 建议验证实施情况。
  • 可行性建议： 针对已识别问题提供具体解决方案。
  • 全面覆盖： 检查所有 SDK 功能和配置。

导出日志验证

使用导出日志页面下载用户级别数据，查看从应用成功传输到 Singular 的所有数据。

导出日志详情：

  • 数据格式： 包含完整用户级别数据的 CSV 文件
  • 时间： 数据可用前约需 30 分钟
  • 验证： 验证事件、会话和归因数据。
  • 调试： 识别缺失的事件或不正确的数据。

深度链接测试

按照"如何测试 Singular SDK 集成"中的说明测试深度链接。

深度链接测试案例：

  • Universal Links： 测试 iOS Universal Links 和 Android App Links
  • 自定义方案： 验证自定义 URL 方案的处理
  • 延迟深度链接： 测试在应用安装前点击的链接
  • 推广活动参数： 验证参数传递和归因

归因验证

测试后使用归因详情 API 查询设备归因详情。归因数据在事件发生后约 4-6 分钟可用。

了解如何使用归因详情端点验证归因。

归因验证步骤：

  1. 执行测试： 安装应用并完成测试用户旅程。
  2. 等待处理： 等待 4-6 分钟以处理归因。
  3. 查询 API： 使用设备标识符调用归因详情 API。
  4. 验证结果： 确认归因到正确的推广活动和来源。

更多测试资源

完整测试指南

有关全面的测试流程、最佳实践和故障排除，请参阅如何测试 Singular SDK 集成。

测试清单：

  • Testing Console 验证实时 SDK 调用。
  • SDK 审计报告确认完整集成。
  • 导出日志验证数据传输。
  • 深度链接在所有场景下正常运行。
  • 归因与预期的推广活动来源匹配。
  • 事件以正确的名称和归因进行追踪。
  • 收入事件捕获金额和货币。

后续步骤

完成前提条件后，继续进行特定平台的 SDK 集成或 S2S 实施。

SDK 集成指南

更多资源