Android SDK - 设置用户 ID 和哈希 User Details

关注
Avatar
Jared Ornstead
Updated

设置用户 ID 和哈希 User Details

将您的内部用户 ID 发送到 Singular，以启用跨设备追踪和用户级数据报告。

注意： 如果您使用 Singular 跨设备解决方案 ，则必须在所有平台上收集用户 ID。

用户 ID 要求

隐私和最佳实践

实施用户 ID 追踪时，请遵循以下准则以确保隐私合规和准确的跨设备测量。

  • 不含 PII： 用户 ID 不应暴露个人身份信息（PII），例如电子邮件地址、用户名或电话号码。请使用您的第一方数据中独有的哈希值。 如需发送电子邮件地址或电话号码，请改用专用的 哈希 User Details API。
  • 跨平台一致性： 为了准确测量跨设备数据，用户 ID 的值必须与您在所有平台（Web/Mobile/PC/Console/Offline）中获取的内部标识符相同。
  • 第一方数据： Singular 在用户级导出、ETL 和内部 BI 回传（如果已配置）中包含用户 ID。用户 ID 属于第一方数据，不会与第三方共享。
  • 持久性： 用户 ID 一直保留，直到使用 unsetCustomUserId() 显式取消或应用被卸载。关闭或重启应用不会清除用户 ID。

实施概述

何时设置用户 ID

使用 setCustomUserId() 设置用户标识符，使用 unsetCustomUserId() 在登出时清除它。

最佳实践： 如果多个用户共用一台设备，请实施登出流程，在登录时调用 setCustomUserId() ，在登出时调用 unsetCustomUserId() 。

如果在应用打开时您已经知道用户 ID，请在初始化 Singular SDK 之前调用 setCustomUserId() 。这样可以确保 Singular 从第一个会话开始就接收到用户 ID。但是，用户 ID 通常在用户注册或登录之前不可用，在这种情况下，请在注册或身份验证流程完成后调用 setCustomUserId() 。

SDK 方法

设置自定义用户 ID

将您的内部用户 ID 发送到 Singular，以进行跨设备追踪和用户级报告。

Kotlin Java 
// Set the user ID after login or registration
Singular.setCustomUserId("custom_user_id")

方法签名： 

public static void setCustomUserId(String customUserId);

取消自定义用户 ID

当用户登出时清除用户 ID，以确保在多用户共用设备上进行准确的会话追踪。

Kotlin Java 
// Unset the user ID on logout
Singular.unsetCustomUserId()

方法签名： 

public static void unsetCustomUserId();

哈希 User Details(电子邮件和电话号码)

上述用户 ID 是您自己的不透明标识符。如果您还想将用户的电子邮件地址或电话号码发送到 Singular,请使用独立的 SingularUserDetails API。SDK 会在设备上对这些值进行规范化并使用 SHA-256 哈希,因此原始的电子邮件地址和电话号码不会被传输。

适用版本： Android SDK 12.16.0 及以上版本。此 API 在 Kids SDK 版本中不可用。

选择哈希模式

提供 PII 有两种方式。请为每位用户选择一种并保持一致。

  • SDK 哈希（推荐）： 传入明文电子邮件地址或电话号码。SDK 会规范化该值、进行哈希,并生成 Singular 可用于匹配的所有变体。
  • 预哈希： 传入您已自行规范化并使用 SHA-256 哈希的值。SDK 会完全按照提供的内容存储,不做任何进一步处理。当您的应用在调用时不能持有明文 PII 时,请使用此方式。

重要： 如果您同时设置了明文值及其对应的预哈希变体,预哈希值优先。

SingularUserDetails Setter

Setter 详情
setEmail

模式： SDK 哈希

明文电子邮件地址。SDK 会在哈希前去除空格并转换为小写。对于 gmail.com 和 googlemail.com 地址,它还会生成第二个变体,即从本地部分移除 +tag 后缀和所有点号。

示例： user@example.com

setPhoneNumber

模式： SDK 哈希

明文电话号码。SDK 会生成两个变体:一个是保留开头 + 并去除其他所有非数字字符的 E.164 格式,另一个是同时去除 + 的纯数字格式。请包含国家代码,以便 E.164 变体可用。

示例： +15551234567

setEmailSTD

模式： 预哈希

去除空格并转换为小写后的电子邮件地址的 SHA-256 哈希值。

setEmailNoDots

模式： 预哈希

去除空格、转换为小写,并从本地部分移除 +tag 后缀和所有点号后的电子邮件地址的 SHA-256 哈希值。适用于 Gmail 类型的地址。

setPhoneE164

模式： 预哈希

保留开头 + 的 E.164 格式电话号码的 SHA-256 哈希值。

setPhoneDigits

模式： 预哈希

去除所有非数字字符(包括开头的 +)后的电话号码的 SHA-256 哈希值。

每个 setter 都有对应的 getter(getEmail、getPhoneNumber、getEmailSTD、getEmailNoDots、getPhoneE164、getPhoneDigits),返回您所设置的值。

在初始化时设置 User Details

在调用 Singular.init 之前将 withUserDetails 链接到您的 SingularConfig，这样 User Details 就会附加到 SDK 发送的第一个会话中。

Kotlin Java 
val userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")

val config = SingularConfig("SDK KEY", "SDK SECRET")
    .withUserDetails(userDetails)

Singular.init(context, config)

在初始化后设置 PII

如果只有在登录或注册后才能获取电子邮件地址或电话号码,请在那时调用 setUserDetails。此后,这些值会附加到 SDK 发送的每个会话和事件中。

Kotlin Java 
// Cleartext values, hashed by the SDK
val userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")
Singular.setUserDetails(userDetails)

// Or supply your own SHA-256 hashes
val hashed = SingularUserDetails()
hashed.setEmailSTD("b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514")
hashed.setPhoneE164("8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4")
Singular.setUserDetails(hashed)

方法签名： 

public static void setUserDetails(SingularUserDetails userDetails);

清除 PII

存储的 User Details 会在应用多次启动之间保留在设备上。请在登出时，或用户撤回同意时调用 clearUserDetails 将其移除。

Kotlin Java 
// Remove stored user details on logout
Singular.clearUserDetails()

方法签名： 

public static void clearUserDetails();

注意： 载荷会使用 Android Keystore 中保存的密钥加密存储在设备上。由于会被持久化，在后续启动中调用 withUserDetails 不会清除之前存储的内容。clearUserDetails 是唯一的移除方式。

验证与隐私行为

  • 电子邮件验证： 明文电子邮件必须包含且仅包含一个 @,且其后需有一个点号。无效值会被拒绝并记录到日志,不会被发送。
  • 电话号码验证： 明文电话号码必须包含至少 6 位数字。更短的值会被拒绝并记录到日志。
  • 模式误用防护： 看起来已经过哈希的值会被 setEmail 和 setPhoneNumber 拒绝。同样,预哈希 setter 会拒绝任何非 64 位 SHA-256 十六进制字符串的值。
  • Limit Data Sharing： 在启用 Limit Data Sharing 期间,PII 载荷将从所有请求中排除。 参阅: 数据隐私.
  • 同意： 仅在您具有合法依据的情况下收集和发送电子邮件地址和电话号码。哈希处理并不免除您在 GDPR、CCPA 或同等法规下的义务。