商店检测和验证

Adjust 可检测并验证安装的具体来源商店,商店覆盖面极广,包括 Google Play 商店、Apple App Store、华为 AppGallery 等。阅读这篇文章,了解默认情况下的检测功能运作方式,何时需要补充信号以改善结果精准度,并掌握功能的后备行为以及多信号并存时的冲突处理办法。

检测和验证

对于每一次安装,Adjust 都会回答两个问题:安装来自哪一家应用商店,以及安装来源能否得以独立确认。

  • 检测​ 功能会利用安装时可用的任何信号立即进行尽可能准确的匹配。
  • 验证​ 功能则会对比独立证据,核验匹配结果进行,这些证据包括 Install Referrer API 调用、商店许可检查等。

验证结果会作为补充信号,与商店类型一同记录。例如,如果系统检测到安装 A 来自 Google Play 商店,但验证失败,那么安装 A 的来源商店仍会显示 “Google Play”,但验证结果显示为“failed” (失败)。

默认状态下的检测功能运作原理

检测从设备报告的操作系统信息开始。大多数操作系统仅关联一个应用商店,因此无需您进行任何额外集成,即可确定检测结果。例如,iOS 安装会匹配至 Apple App Store,tvOS 安装会匹配至 Apple App Store (TV),CTV 和游戏主机平台同理。

而少数平台并不会关联唯一的商店。此类平台最典型的是 Android,此外还有 PC端。Google Play、华为 AppGallery、小米 GetApps、Samsung Galaxy Store 等均支持 Android,因此仅凭操作系统信息,并不足以区分 Android 端安装究竟来自哪个商店。在这种情况下,下文所述的补充信号就能提升检测精准度。跳过这些信号并不会影响检测功能本身,只意味着 Adjust 无法自行区分具体的来源商店。此时,您实际看到的检测结果取决于您的设置。如果您已经为平台配置了默认商店,那么该默认商店就将是检测结果,否则会显示为“Unknown” (未知)。要了解更多详情,请前往本文的“后备行为”一节。

针对多商店平台的补充信号

检测功能开箱即用,并非一定需要下列补充信号。但在缺乏补充信号的情况下,Adjust 只能报告安全的默认结果,即精准度较低的检测结果,或报告验证状态已跳过,无法提供您实际配置的真实结果。Adjust 无法预知您实际使用的商店或验证方法,因此进行更精细的设置,可告知系统需要针对您的集成检查哪些内容。

信号用途确认信息
预安装信号->
预安装合作伙伴点击
检测仅限 Android 平台。受支持的预安装合作伙伴会将交互数据写入设备。当应用首次打开时,这些数据会以点击形式发送;该机制会在下文“ 预安装监测”中详细介绍。将安装标记为“preinstall” (预安装),让它的优先级高于所有其他信号。无需手动配置。具体请参阅“ 结果参考”一节。
预安装信号->
系统应用标记
检测仅限 Android 平台。 is_system_app和 is_updated_system_app这一对标记在安装或会话发生时直接发送,让系统将应用识别为预加载系统应用。将安装标记为“preinstall” (预安装),让它的优先级高于所有其他信号。无需手动配置。具体请参阅“结果参考”一节。。
商店信息->
系统报告的商店
检测仅限 Android 平台。直接从 Android 系统 API (store_name_from_system) 读取,用于识别将应用安装到设备的来源商店安装程序。如果可用,这是最强的检测信号,优先级高于您的商店配置。如果安装程序包名并未映射到已知商店,那么安装将被报告为“custom” (自定义)。具体请参阅“ 结果参考”一节。。
商店信息->
您配置的商店名称和应用 ID
检测系统报告的信号不可用时,Adjust 会通过该机制为多商店部署提供支持,例如非 Android 平台、PC 以及服务器到服务器设置。以 store_name_from_client和 store_app_id_from_client 形式发送。针对 Android 端,如果系统报告的商店信息缺失或商店无法被识别,将使用此信号。如果系统报告的商店信息和该信号均可用,则以系统报告的商店为准。目前检测仅使用商店名称,应用 ID 保留供未来使用。可在 SDK 配置中设置,或作为 S2S 参数发送。要了解设置步骤,请参阅 SDK 集成指南。
Windows Store SDK 版本检测仅限 Windows。SDK 会使用专门的请求标头,报告它是否是针对 Windows Store 构建的版本。仅凭此信号无法区分 PC 端与移动端的 Microsoft Store。要解决该问题,您需要配置 store_name_from_client (参见上文)。如果您配置的商店名称与 Microsoft Store 不匹配,系统就会将两个信号记录为冲突。
PC 端 Google Play 游戏检测仅限 Windows。Google Play Games PC 版会在 Windows 系统中运行 Android 应用,因此会使用 Android SDK 的系统功能检查进行自动检测,无需单独的插件,也无需您手动配置。
Steam ID 或 Steam UUID检测仅限 PC (Windows、macOS、Linux)。将安装来源识别为 Steam。检查的优先级高于任何客户端声明的商店值。无需手动配置。
Epic Games ID检测仅限 PC (Windows、macOS、Linux)。将安装来源识别为 Epic 游戏商城。检查的优先级高于任何客户端声明的商店值。无需手动配置。
Google Play referrer验证使用 Google Play 自有的 Install Referrer API 独立确认安装。
Huawei AppGallery referrer验证使用华为自有的 Install Referrer API 独立确认安装。
Xiaomi GetApps referrer验证使用小米自有的 Install Referrer API 独立确认安装。
Samsung Galaxy Store referrer验证使用 Samsung 自有的 Install Referrer API 独立确认安装。
Vivo Appstore referrer验证使用 Vivo 自有的 Install Referrer API 独立确认安装。
Google Play License Verification Library (LVL)验证针对 Google Play 旗下所有商店。对比 Google 许可服务进行加密检查,从而确认安装。由通用商店检查下的“ 启用 Google License Verification (LVL) 集成 ”控制。请查看 LVL 设置 ,了解该验证与其他验证方法如何相互影响。
Adjust SDK 信号 (iOS,Apple TV)验证针对 iOS 和 Apple TV。使用专用 Adjust SDK 信号确认 App Store 安装。由商店验证配置中的“ 使用专用 SDK 信号验证 ”设置控制。

上述所有五种 referrer 验证方法均由“商店验证配置”中的同一个“ Referrer 检查​ ”设置控制,可针对每个商店分别设置。

集成要求

每项补充信号都要依赖特定的最低 SDK 版本。在某些情况下,还需要安装插件或进行额外的配置。如果您的 SDK 版本过低,系统不会报错,但也不会发送信号。检测功能将使用其他可用的信号,继续正常运行。

信号要求
预安装信号->
预安装合作伙伴点击
Android SDK v4.27.0 或更高版本,通过受支持的预安装合作伙伴设置。
预安装信号->
系统应用标记
Android SDK v5.7.0 或更高版本
商店信息->
系统报告的商店
Android SDK v5.4.0 或更高版本
商店信息->
您配置的商店名称和应用 ID
Android 和 iOS 端:SDK v5.4.0 或更高版本。
PC 端 (Windows、macOS、Linux) 独立 Steamworks Unity SDK v1.1.0 或更高版本,或 Steamworks Unreal SDK (任意已发布版本) — 不属于主 Android 或 iOS SDK 版本的一部分。请参阅 Steamworks Unity SDK。
Windows Store SDK 版本从最早支持 Windows 的版本起就已经内置在 SDK 中,没有最低版本限制。要区分 PC 与移动端,请通过 Steamworks SDK 配置 store_name_from_client ——具体要求请参阅上文。
PC 端 Google Play 游戏Android SDK v4.36.0 或更高版本。无需安装单独的插件。
Steam ID 或 Steam UUIDSteamworks Unity SDK v1.1.0 或更高版本,或 Steamworks Unreal SDK (任意已发布版本)。这些均是独立的配套包,并非主 Android 或 iOS SDK 的一部分。
Epic Games ID仅限服务器到服务器
Google Play referrer从最早支持 Google Play 的版本起就已经内置在 SDK 中,没有最低版本限制。
Huawei AppGallery referrerAndroid SDK v4.21.2 或更高版本,以及华为 referrer 插件
Xiaomi GetApps referrerAndroid SDK v4.31.0 或更高版本,以及小米 referrer 插件
Samsung Galaxy Store referrerAndroid SDK v4.33.0 或更高版本,以及 Galaxy Store referrer 插件
Vivo Appstore referrerAndroid SDK v4.33.1 或更高版本,以及 Vivo referrer 插件
Google Play License Verification Library (LVL)Android SDK v5.4.4 或更高版本,以及已使用您的公钥配置的 LVL
Adjust SDK 信号 (iOS,Apple TV)iOS SDK v5 或更高版本,以及签名库 v3.32 或更高版本

针对 S2S 集成,可通过 store_name_from_client 和 store_app_id_from_client 请求参数分享预期商店名称和应用 ID。

后备行为

如果 Adjust 无法确定安装的具体来源商店,那么通过 “未检测到时使用平台默认”​ 选项,安装就会回退到您为对应平台配置的应用默认商店,不会将安装标记为“未知”。该后备默认启用。如果您希望将此类安装标记为“未知”,而不是归因到平台默认商店,请关闭此后备。

需要 SDK/S2S 商店类型信号

如果您应用的所有版本均通过 SDK (Android 或 iOS SDK v5.4.0 或更高版本) 或 S2S (store_name_from_client) 发送商店类型,那么请启用 “需要 SDK/S2S 商店类型信号”​ 。这样,在禁用后备的情况下,即便 Adjust 通过其他信号监测到了商店 (例如 Android 系统报告的商店),缺失该信号的安装依然会被标记为“未知”。

该设置仅检查您的集成是否发送了商店类型,不会改变信号的优先级。只要发送了商店类型,检测就会照常运作,在 Android 端,系统报告的商店仍比您配置的值优先级更高。

即便安装被标记为“未知”,如果符合条件,标记仍可能发生变化。如果商店验证确认了来源商店,例如通过 Google Play Install Referrer 或通过了 LVL 检查,那么该安装的“未知”标记就会被移除,被匹配到对应的商店。

因此,只有在 SDK/S2S 未发送商店类型、且商店验证缺失的情况下,安装才会一直保留“未知”标记。这种情况通常表明安装可能来自旧版应用或被篡改的应用版本,并非来自您自己的应用版本,或 S2S 流量并非来自您的集成。

要了解如何更改这项配置,请参阅配置商店检测和验证。

如何处理多信号并存的情况

多数安装只会产生一个商店信号,因此不存在信号冲突的问题。但同一次安装偶尔会收到多个信号。例如,初始检测发送了一个信号,随后又收到了验证结果信号;或者收到了两个独立信号,分别指向不同的来源商店。遇到此类情况时,Adjust 遵循以下优先级:

  1. 预安装优先级高于其他信号​ 。如果安装被识别为预安装,那么该信号就始终拥有最高优先级。无论同一请求中出现其他信号,或稍后单独发来其他信号,它们都会被忽略。唯一的例外是“ 需要 SDK/S2S 商店类型信号​ ”设置。如果启用该设置且禁用后备,而您的应用未发送商店类型,那么仅通过系统应用标记检测到的预安装将被标记为“未知”。更多信息请参阅需要 SDK/S2S 商店类型信号。
  2. 如果尚无任何记录,那么 系统会接受首个可用的信号​ 。
  3. 已验证的结果会受到保护。​ 假设安装已经通过 Install Referrer 检查确认为来自 Google Play 商店,然后又出现了指向不同商店的未验证信号,那么后者将被忽略,记录中的来源商店始终是 Google Play.已被验证的结果只能被其他通过验证的结果覆盖。
  4. 在 Android 端,系统报告的商店信号优先级高于您配置的商店。​ 如果在同一个请求中,store_name_from_system 和 store_name_from_client 不一致,那么 Adjust 就会使用系统报告的值,因为该值来自操作系统本身,而非您的集成。与本文中的其他情况不同的是,这并不是需要解决的冲突,而是针对单个请求的精确选择。只有在系统报告的商店信息缺失或商店无法被识别时,我们才会使用您配置的值。“ 需要 SDK/S2S 商店类型信号​ ”设置并不会改变该优先顺序。更多信息请参阅需要 SDK/S2S 商店类型信号。
  5. 存在信号冲突的安装会被标记为“未知”。​ 无论是否来自同一个请求 (例如同一个请求中出现两个信号,或两个请求中各有一个信号,分别来自 Steam 和 Epic Games),如果存在两个指向不同商店的、彼此不相关的信号,且两个信号都未能验证,那么 Adjust 就无法判断该以哪个信号为准。在这种情况下,安装就会标记为未知,与完全未收到可用信号时的结果相同。与上文提到的其他情况不同,一旦安装由于信号冲突而被标记为未知,那么即便后续收到更多信号,“未知”标记也不会被自动修改。

结果参考

针对每个安装,检测功能都会解析出唯一一个 store_type 值。可能的值包括:Adjust 支持的商店 (即便您尚未在应用设置中添加该商店),标记为“Preinstall” (预安装)、“Custom” (自定义) 或“Unknown” (未知) 的值。下表中列出了每种值的适用场景。验证功能会检查已检测到的商店。每种验证方法都有特定的适用商店。例如,如果启用 Google Play install referrer 检查,那么系统就会使用此方法验证来自 Google Play 商店的安装。验证结果 (通过、失败或跳过) 将与 store_type 分开报告。部分情况下,商店的 Install Referrer 还可能更新 store_type。具体请参阅如何处理多信号并存的情况一节。此外,请查看结果显示位置一节,了解 store_type 和验证结果会出现在 Adjust 的哪些位置。

场景store_type 值
检测到特定商店无论验证是通过、失败还是被跳过,商店名称都会显示,例如“Google Play”。
未检测到特定商店,且已启用后备您为该平台设置的应用默认商店。如果没有设置默认商店,则标记为未知。
未检测到特定商店,且已禁用后备Unknown
应用由 OEM 或预安装合作伙伴预安装。标记为预安装。在确认任何商店之前检查,优先级高于其他所有信号。
在 Android 端,应用通过不受 Adjust 支持的商店安装,且您的应用未通过 SDK 或 S2S 发送受支持的商店信息自定义
需要 SDK/S2S 商店类型信号 启用,后备禁用,且您的应用未通过 SDK 或 S2S 发送受支持的商店信息Unknown
相互冲突的信号,例如一个信号指示 Steam,另一个指示 Epic GamesUnknown
重要提示:

如果 Adjust 检测到了商店,而您尚未在“应用设置”版块为自己的应用设置该商店,那么报告中就会显示系统生成的、而非真实的应用商店 ID,格式为 {store_type}_{app_token}。示例:xiaomi_abc123abcde。系统始终会为预安装、自定义和直接 Android 安装生成应用商店 ID,例如 preinstall_abc123abcde,因为它们无法在应用设置中作为商店添加。在应用设置中添加商店后,报告就会显示您配置的应用 ID。

系统生成 ID 仅用于报告。在原始数据中,未设置的商店的 {app_id} 始终为空。

配置商店检测和验证

检测与验证功会自动正常运行,您无需更改任何设置。Adjust 会利用可用信号和默认设置自动检测商店,结果会直接显示在您的报告中。

如果您希望强化针对特定商店的检测精确度,或控制验证的严格程度,可以前往 AppView > 数据保护 > 商店检测与验证设置,进行所需调整:

  • 应用层级配置​ ,涵盖多个检测设置,例如“ 未检测到时使用平台默认​ ” 和 “ 需要 SDK/S2S 商店类型信号​ ”。
  • 商店验证配置​ ,分别应用于每种商店类型。商店验证配置独立于检测。无论商店是否已在应用设置版块中保存,检测功能都会自动识别任何受支持的商店 (参见结果参考)。但要开/关特定商店的验证检查,您需要先前往应用设置界面进行商店配置。以下商店支持验证配置:Google Play、Google Play (TV)、Google Play (PC)、华为 Huawei AppGallery、小米 GetApps、Samsung Galaxy Store、Vivo Appstore、Apple App Store 以及 Apple App Store (TV)。如果您想配置的商店未在此处列出,请前往“平台”选项卡进行添加。更多详情请参阅关联您的平台。

下方表格中列出了未经任何修改的默认设置:

方法适用对象默认
Referrer 检查Google Play,Google Play (TV 和 PC),华为,小米,Galaxy Store,Vivo开
LVL 检查Google Play 旗下所有商店关。必须配置公钥才能启用。在“通用商店检查”下的“ 启用 Google License Verification (LVL) 集成 ”设置。请参见 LVL 设置。
使用专用 SDK 信号验证Apple App Store,Apple App Store (TV)关。如果您希望检查更严格,请启用该方法。该方法会使用 SDK 签名结果,但无需您为 SDK 签名本身启用拦截功能。

即便不启用上述任何方法,商店检测和验证功能依旧能正常运作。但我们还是建议您检查自己的 SDK 或 S2S 集成。这些验证设置能够提高检测和验证流程的质量。

LVL 设置

Google Play License Verification (LVL) 是一种更为严格的验证方法,会直接对照 Google 的许可服务检查安装,而不是仅依赖 referrer。这是一项通用检查,适用于 Google Play 旗下所有商店,可通过“通用商店检查”版块的” 启用 Google License Verification (LVL) 集成​ “来启用。该设置默认关闭,只有您配置应用公钥后才能开启。如果不配置应用公钥,设置开关会始终处于不可用的状态。

启用后,Adjust 会分别评估每个已启用的验证方法。如果您为同一个商店启用了 referrer 检查,那么只要有一项检查失败,整体验证结果就为失败。只有在两项检查均未失败、且至少一项检查通过的情况下,结果才会是“通过”。

结果显示位置

无论您是否使用下方任何界面,每次安装都会接受检测和验证。“转化规则”中的商店规则并非使用检测和验证功能的条件,而是一种利用结果采取行动的方式。即便不设置商店规则,您也可以通过原始数据、回传或报告维度直接读取商店类型和验证结果。

在客户和合作伙伴回传中​ ,针对使用商店相关占位符的应用:

  • {store_info} 返回一个基于 Adjust 所收到的原始信号构建的 JSON 对象。其中的 JSON 字段名称与本文前述中使用的请求参数名称不同: from_system 对应 store_name_from_system,from_client 对应 store_name_from_client,app_id 对应 store_app_id_from_client。在 Android 端,from_system 是原始安装程序包名(例如 Google Play 为 com.android.vending),而非解析后的商店名称。例如:
{
  "from_client": "google_play",
  "from_system": "com.android.vending",
  "app_id": "com.example.app"
}

仅包括含有值的字段。因此,如果客户端没有声明安装的来源商店,那么返回的 JSON 对象就不会包含 from_client 和 app_id。

当平台报告 Android 安装来源信息时,JSON 对象中还可能包含 initiating_package_name和 originating_package_name 两个额外字段。这两个字段与 from_system 一样,都来自同一组 Android 安装来源 API,记录请求安装的包和发起安装的包。这些字段会按原样发送,不会影响检测结果。

  • {store_type} 会以单个值的形式返回解析后的商店类型,例如 google_play、custom 或 unknown。
  • {store_verification_result} 返回整体验证结果。可能的值:passed, failed, skipped
{
  "store_verification_result": "passed"
}
  • {store_verification_result_lvl} — LVL 验证结果。可能的值:passed, failed, skipped
  • {store_verification_result_referrer_api} — install referrer API 验证结果。可能的值:passed, failed, skipped
  • {store_verification_result_app_store} — 基于 Adjust SDK 信号的应用商店检查验证结果。可能的值:passed, failed, skipped
{
  "store_verification_result_lvl": "failed",
  "store_verification_result_referrer_api": "passed",
  "store_verification_result_app_store": "skipped"
}

作为聚合数据,维度:​

  • App store type (store_type),允许您按照检测到的安装商店类型分组
  • Platform (platform),允许您按照商店类型所属的平台分组,例如 Android、iOS、CTV、PC、主机、其他
    • OS name (os_name),允许您按照安装发生的操作系统进行分组

在 转化规则商店类型条件​ 中,您可以根据解析后的商店类型以及验证结果直接采取行动。

重要提示:

如果一项验证方法已经配置,但没有作为检查启用,那么该方法就会返回“skipped” (跳过) 结果。而商店规则会将“跳过”结果视为与“通过”相同。如果您为某个商店设置了商店规则,那么请仔细检查,确认已集成必要信号或 SDK 版本,且确实已针对该商店启用了验证功能。举例来说,假设规则 A 仅允许来自 Apple App Store 的安装,而您没有启用“ 使用专用 SDK 信号验证​ ”设置,那么规则 A 就只能检查商店类型。而在 iOS 端,商店类型默认是 Apple App Store,因此,只有在检测到 Apple App Store 以外的其他商店、或未检测到任何商店时,规则 A 才会拒绝对应的安装。启用 使用专用 SDK 信号验证​ 功能,即可通过 SDK 签名确认 App Store 安装。更多详情请参阅商店规则设置步骤说明。