如何测试 Singular SDK 集成

将 Singular SDK/S2S 集成到应用程序后,在上线新版本应用程序之前,必须确保其正常运行。

开发人员指南 开发人员
前提条件
  • 已为应用程序集成了Singular SDK 或 S2S。
  • 要使用测试控制台,您需要使用移动设备进行测试。

Singular 提供三种主要工具用于测试集成:

  • 测试控制台(Testing Console),允许你实时地对已实现的功能进行手动测试,
  • 导出日志,允许您在一定的延迟后(发送事件至少一小时之后)下载用户级设备日志数据,
  • 审计报告,可自动识别集成中的任何问题。

 

使用测试控制台

测试控制台可以从已添加的测试设备侦听并记录实时事件数据。它并不记录并报告历史过往数据。为了使用测试控制台进行测试,需要做好以下准备:

  • 一台从未安装过待测应用程序的设备
  • 需要测试的事件以及相应的属性列表
  • 对于 iOS 设备 - 请确认ATT提示信息是否会显示。因为用户选择的ATT结果将决定你需要在测试控制台中使用IDFA还是IDFV 
1

添加测试设备

向控制台添加设备:

  1. 在 Singular 平台中,从左侧导航栏转到开发工具 > 测试控制台
  2. 单击 "添加设备"。

  3. 提供设备类型。 对于 Android 设备,如果可以获取到以下某设备标识时,我们建议按照如下优先级使用Google Advertising ID(GAID/aifa)、AppSetID(asid) 或AndroidID(andi)。对于 iOS 设备,如果可以获取到,我们建议使用IDFA
  4. 提供设备ID

    捕捉设备 ID

    对于安卓系统,我们建议使用谷歌广告 ID(GAID/aifa)。Singular Device Assist 辅助应用程序(Android版)可以帮您找到它。

    启用 Singular SDK 日志记录后,还可以在 Android LogCat 中找到 aifa。

    SingularConfig config = new SingularConfig(SdkKey, SdkSecret)
    .withLoggingEnabled()
    .withLogLevel(1);

    LogCat 输出示例:

    2023-06-01 15:48:32.224 27442-27560/com.singular.test D/Singular: DeviceInfo [worker] - andi : 8868adc2f7ffffff
    2023-06-01 15:48:32.224 27442-27560/com.singular.test D/Singular: DeviceInfo [worker] - asid : 12dc3652-5e46-f2bb-a93a-b3c092ffffff
    2023-06-01 15:48:32.224 27442-27560/com.singular.test D/Singular: DeviceInfo [worker] - aifa : 3bbc76b0-cebb-4a9f-b6ec-10ca1affffff

    对于 iOS,当显示了 ATT 提示且用户允许跟踪时,可以使用IDFA。确保代码中也实现了 "等待跟踪授权结果的超时间隔"。对于所有其他情况,请使用IDFV

    可以使用下列方法之一获取设备的IDFA

    • 使用 App Store 中的 Singular Device Assist 辅助应用程序(iOS版)。并确保授予其跟踪权限。
    • 在 Xcode 调试控制台中记录 IDFA
      // Swift 中的示例
      print("IDFA", ASIdentifierManager.shared().advertisingIdentifier.uuidString)
                      
      // Objective-C 中的示例
      NSString *IDFA = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
      NSLog(@"IDFA: %@", IDFA);

    可以在 Xcode 的调试控制台中捕获IDFV

      // Swift 中的示例
      print("IDFV", UIDevice.current.identifierForVendor!.uuidString)
                      
      // Objective-C 中的示例
      NSString *IDFV = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
      NSLog(@"IDFV: %@", IDFV);
  5. 为您添加的设备起一个独特的设备名称 ,然后单击 "保存设备"。

    tc_01.png

2

测试SDK的初始化

首先要测试的是集成的Singular SDK 是否初始化成功,是否能够向 Singular 发送信息(即应用内的埋点事件能正常上报)。这将使得 Singular 开始跟踪此应用程序的归因!

测试SDK的初始化

  1. 如下图,在 "事件日志"页面中,从 "设备"下拉菜单中选择您的测试设备名称。确认状态指示器显示为 🟢Live

  2. 在测试设备上初始化应用程序/打开应用程序。
  3. 当您看到会话SESSION事件时,说明您已经成功初始化了 Singular SDK。

    tc_02.png

如何读取事件日志?

添加测试设备并发送一些事件后,事件就会开始出现在测试控制台页面的事件日志中。

tc_04.png

点击任何一行即可显示应用程序发送的事件的全部细节。

events_details.png

为什么事件日志界面中没有显示任何事件?

如果您已经添加了测试设备,并按照指南测试 SDK 集成,但事件日志界面中没有显示任何事件信息,请仔细检查以下内容:

  • 测试控制台只显示实时事件,即在页面上有选定你所使用的测试设备并确保实时指示器状态为正常🟢 。 它不会查找并显示设备上报的历史事件。如果你在设备上触发事件之后才在控制台中选择测试设备,则之前发送的事件不会被捕获与显示。
  • 确保在测试设备上打开了应用程序(查看用户会话)。
  • 确保触发了一些应用程序内事件(如果要测试事件)。
  • 确认你在添加测试设备时输入了正确的设备标识。
  • 请确你在添加测试设备时选择了正确的设备标识类型(对于iOS设备,如果APP没有弹出ATT提示信息,则IDFA类型不可用)。
使用 Singular SDK 12.0.0 及以上版本测试应用程序时,为什么没收到_InstallReferrer事件?

从Singular SDK 12.0.0开始,您不需要测试_InstallReferrer事件。 一旦您的应用程序被推送到商店,Singular SDK会将_InstallReferrer数据放在第一个会话事件中。 您只需要查看SESSION事件是否出现在测试控制台中。

如果您使用的是旧版本的 Android SDK,您仍然需要在测试控制台中检查是否收到 _InstallReferrer 事件。

如何从控制台中删除/移除设备

删除设备

要从跟踪列表中删除测试设备,单击 "编辑 "图标,然后在出现的设备信息对话框上单击 "删除设备"。这将清除页面上的所有事件日志,Singular 也会删除有关该设备的内部归因数据。

另请参阅:如何重置设备并清除其归属信息,以便再次使用它来测试安装归因

如何重置设备并清除其归因信息,以便再次使用它来测试安装归因?

如果您想用同一台设备重新测试 SDK 集成,除了在 Singular 平台中清除设备的归因信息外,还必须删除设备上所有本地缓存数据。

安卓设备的操作步骤

  1. 关闭应用程序并确认其未在运行(如果有强制停止选项,请使用 "设置"菜单中的 "强制停止")。
  2. 点击通知窗口或 "应用程序 "菜单中的滚轮图标,进入 "设置"菜单。
  3. 进入 "应用程序",选择要测试的应用程序,长按该应用程序并选择 "应用程序信息"。
  4. 选择 "存储",然后选择 "清除缓存"和 "清除数据"。
  5. 在 Singular 测试控制台中,从下拉菜单中选择设备,然后单击编辑(铅笔)图标。在打开的设备信息对话框上,单击 "删除设备",让Singular的系统删除此设备的归因信息。

     

    device_dropdown.png

    device_delete.png

iOS 设备的操作步骤

  1. 关闭应用程序,然后卸载。
  2. 打开 "测试控制台",在下拉菜单中找到您的设备,然后单击 "编辑 "图标。 在打开的设备信息对话框上,单击 "删除设备",让Singular的系统删除此设备的归因信息。

     

提示:有关重新激活的不活跃窗口期进行的测试

不活跃窗口是一项应用程序设置,它决定了用户必须保持不活跃至少多长时间后,才可以触发重新激活的归因。如果您要在启动营销活动前测试重新激活归因,不活跃窗口会增加您的测试难度。因此已添加到测试控制台的测试设备将不受不活跃窗口的限制

3

测试特定功能

测试自定义用户 ID

如果你的 SDK 集成向 Singular 发送了自定义用户 ID,下面是测试方法

  1. 在测试控制台注册测试设备。
  2. 打开应用程序。
  3. 如果需要,在应用程序中触发一个发送用户 ID 的动作(如登录)。具体如何操作取决于您的实现。
  4. 在发送到 Singular 的下一个事件中,展开测试控制台中的事件详细信息,检查详细信息中是否包含 "custom_user_id "值。

     test8.png

如果用户 ID 未显示:

  • 检查应用程序中设置用户 ID 的方法是否按照你的要求被调用。
  • 您可能需要添加一个 Singular SDK 事件并将其命名为 "setting custom user ID",检查该事件就是否会显示在测试控制台的事件日志中。
测试事件

如果您已经在 SDK 集成中实现了事件跟踪或收入跟踪,请按照以下说明进行测试

有关事件的更多信息,请参阅

对于您在 SDK 集成中实现追踪的每个事件:

  1. 从应用程序中触发事件,并检查事件日志中是否出现了您为该事件命名的名称。

     test9.png

  2. 如果您要随事件发送任何附加数据,请单击测试控制台中的事件记录以展开事件详细信息,并确保数据包含在 "event_data "中。

     events_details_field.png

如果事件未显示,则可能是在设备完全注册到测试控制台之前打开了应用程序。可进一步通过导出设备日志功能检查。

测试收入

对于您在 SDK 集成中实现追踪的每种类型的收入事件:

  1. 在应用程序中触发收入事件并检查事件日志。日志中应该会出现对应收入事件名称的记录。

    注意: 如果您没有给事件自定义名称,你会看到收入事件的默认名称为"__iap__"。

  2. 单击收入日志进行展开,确保正确地收到货币("pcc")、金额("r")和收入事件的其他详细信息。

     events_details_field.png

测试深度链接

如果您已在 SDK 集成中实现了对深度链接的支持,请按照以下说明测试您的深度链接功能

注意: 本文假定您的组织正在使用 Singular 跟踪链接(Singular Links)

1.设置测试跳转目标地址

在 Singular 后台中,进入 "设置">"应用程序"界面,找到应用程序并添加深度链接目标地址。

目标地址是在你在应用中集成 SDK 时实现的处理程序代码可以识别和处理的深度链接目标地址之一,如图。

 test12.png

2.创建测试链接

有了要链接的目的地,就可以创建深度链接了。

  1. 转到 "归因">"管理链接",然后从侧边栏中选择应用程序。
  2. 单击 "创建链接"
  3. 链接类型下选择 "自定义渠道/Custom Source",在渠道名称下选择 "电子邮件/Email"。
  4. 为链接命名。
  5. 单击展开 "链接设置和重定向" 设置部分。
  6. "深度链接"下拉列表中选择刚刚创建的目标地址。
  7. "其他平台的后备目标"文本框中输入一个网站的 URL 地址。
  8. 单击"生成"并从"点击跟踪链接"文本框中复制链接

     test13.gif

3.测试链接

要测试链接,请完成:

  1. 确保应用程序已安装在测试设备上。
  2. 将复制的链接通过电子邮件发送到测试设备。
  3. 在设备上打开电子邮件并点击链接。应用程序应被打开并跳转至深度链接所指定的页面或内容。

测试链接的另一种方法(仅限安卓)

在电脑上打开命令行终端,触发深度链接:

 test14.png

故障排除

"当我的应用程序已在运行时,点击深度链接会打开应用程序的新实例,而不是切换到现有应用的实例。要避免这种情况,请编辑清单文件并在活动中添加以下内容:

android:launchMode="singleTask"

有关 launchMode 选项的更多信息,请参阅Google 的 <activity> 文档

测试延迟深度链接

确认是否启用了延迟深度链接

  1. 检查测试控制台中的会话事件。

     test15. png

  2. 按照上述测试深度链接中的说明设置测试目标地址和链接。
  3. 从测试设备上卸载应用程序。
  4. 通过电子邮件将深度链接发送到设备,然后在设备上打开链接。链接应该会带您进入应用商店。安装并打开应用后,您应该会看到延迟深度链接指定的页面或内容。

     테스트16.gif

测试卸载跟踪

如果您已经在 SDK 集成时实现了卸载跟踪,请按照以下说明进行测试

测试卸载跟踪比测试其他 SDK 功能更复杂,因为 Singular 依赖于 Google/iOS 服务来报告卸载情况,而这一过程需要一些时间。你无法在 Singular 平台上实时地看到卸载事件,因此也无法使用测试控制台进行该测试。

测试前,请确保已向 Singular 发送 FCM/APNS 令牌(请参阅Android SDK:跟踪卸载iOS SDK跟踪卸载)。

此外,请仔细检查是否在应用程序配置页面输入了FCM Server Key 服务器密钥(安卓平台)或iOS Push Certificate 推送证书

测试卸载跟踪:

  1. 使用真实设备(而不是模拟器),在设备上安装应用程序。
  2. 打开应用程序,以便注册安装。
  3. 卸载应用程序。
  4. 要检查 Singular 是否收到卸载事件,您有以下几种选择:

    • 导出归因日志(事件日志)并找到卸载事件,可能需要几天时间才能在日志中显示出来。
    • 如果设置了向您的内部 BI 系统发送事件回传,则您内部 BI 系统可收到有关卸载的回传事件。
    • 您可以联系 Singular 支持团队或客户成功经理CSM,帮助您验证卸载跟踪。

注意: 在等待验证卸载事件期间,不要重置设备 ID,也不要重新安装应用程序。

注意:测试控制台不支持 iOS TestFlight 应用程序。TestFlight 构建的版本会在每次启动应用程序时重置 IDFV,导致无法捕获实时事件。

使用导出日志

您还可以使用 "归因">"导出日志 "来验证测试结果,这需要在事件发出一段时间后才能进行。导出日志功能允许您手动下载用户级数据,如转化(安装)、事件等。

最佳实践

  • 获取数据前,请仔细检查所选日期、应用程序和版本是否正确。
  • 导出日志中的数据滞后约 3 个小时。
  • 如需更多帮助,请参阅常见问题

运行 SDK 审计

Singular 提供 SDK 审计报告,用于测试 SDK 和 S2S 集成是否正确实施。审核报告会列出发现的所有问题,并提供解决问题的提示。按照如下步骤使用 SDK 审核报告:

1

运行 SDK 审核报告

转到 "开发人员工具">"测试控制台",然后单击右上角的 "运行审核"

tc_03.png

2

下载报告并修复相关问题

报告运行完成后,您可以下载 CSV 格式的报告。

该报告列出了在 SDK 和 S2S 集成中发现的问题。并非所有问题都是关键或相关的,这取决于您实现了哪些功能。

查看报告中的问题,并根据错误描述字段中的提示进行修复。

对于警告/信息类型的问题:检查 "验证名称",看看这是否是您选择不实现的可选 SDK 功能,如延迟深度链接 (DDL)。如果是,则可以忽略相关错误信息。

SDK 审计是如何工作的,在什么数据上运行?

SDK 审计会查看最近 3 天内从应用程序接收到的数据。它会检查数据是否符合预期,例如

  • 应用程序是否报告用户会话(这是 SDK/S2S 集成的最基本功能,也是 Singular 跟踪归因的基础)
  • 应用程序是否报告应用内事件和收入
  • 是否使用最佳实践报告收入
  • 是否启用了延迟深度链接
如何阅读 SDK 审计报告?

 Screen_Shot_2021-11-11_at_18.28.27.png

该报告列出了在 SDK 和 S2S 集成中发现的潜在问题

说明
App Name 在 Singular 中配置的应用程序名称。
App Bundle 在 Singular 中配置的应用程序包名,例如 com.example.appname。
Platform 操作系统平台,如:iOS、Android 或 Amazon。
App Version 应用程序版本号(如果有)。
Validation Name 发现的集成问题来自何处,如 "自定义用户 ID "或 "收入事件"。
Type

问题的严重程度:

  • 错误: 此问题会导致集成无法工作,您必须在应用程序上线前解决。例如,Singular 无法从应用程序中接收用户会话。没有用户会话,我们就无法执行归因。
  • 警告:此问题不影响集成的工作,但是如果您想遵循最佳实践并从 Singular 归因跟踪器中获得最大收益,您应该修复它。例如,您的应用程序没有发送自定义用户 ID。自定义用户 ID 是可选功能,但强烈建议使用。
  • 信息: 与可选功能相关的实现问题的提示,也许你本来就决定不实现这些功能。例如,您的应用程序未启用延迟深度链接 (DDL)。DDL 可能与您的营销策略无关。
Error Description 有关该问题的更多信息以及修复方法。