设置用户 ID 和哈希 User Details
向 Singular 发送内部用户 ID，以实现跨设备跟踪和用户级数据报告。
注：如果使用Singular 的跨设备解决方案，则必须在所有平台上收集用户 ID。
用户ID要求
隐私和最佳实践
在实施用户 ID 跟踪时，请遵循以下准则，以确保隐私合规和正确的跨设备测量。
- 无 PII：用户 ID 不应暴露个人身份信息 (PII)，如电子邮件地址、用户名或电话号码。使用与第一方数据独一无二的哈希值。
- 跨平台一致性：用户 ID 值必须是您在所有平台（网络/移动/PC/控制台/离线）上获取的相同内部标识符，以便进行准确的跨设备测量。
- 第一方数据：Singular会在用户级导出、ETL和内部商业智能回传（如有配置）中包含用户ID。用户 ID 是第一方数据，不会与第三方共享。
-
持久性：用户 ID 会一直存在，直到使用
UnsetCustomUserId()明确取消设置或卸载应用程序。关闭或重启应用程序不会清除用户 ID。
实施概述
何时设置用户 ID
使用SetCustomUserId() 设置用户标识符，使用UnsetCustomUserId() 注销时清除用户标识符。
最佳实践：如果多个用户共用一台设备，请执行注销流程，登录时调用SetCustomUserId() ，注销时调用UnsetCustomUserId() 。
如果在应用程序打开时已经知道用户 ID，请在初始化 Singular SDK 之前调用SetCustomUserId() 。不过，在用户注册或登录之前，用户 ID 通常是不可用的，在这种情况下，应在注册或验证流程完成后调用SetCustomUserId() 。
SDK 方法
设置自定义用户 ID
向 Singular 发送内部用户 ID，用于跨设备跟踪和用户级报告。
// Set the user ID after login or registration
SingularSDK.SetCustomUserId("custom_user_id");方法签名：
public static void SetCustomUserId(string customUserId)取消设置自定义用户 ID
在用户注销时清除用户 ID，以确保多用户设备的准确会话跟踪。
// Unset the user ID on logout
SingularSDK.UnsetCustomUserId();方法签名：
public static void UnsetCustomUserId()哈希 User Details（邮箱和电话号码）
上述用户 ID 是您自己的不透明标识符。如果您还想将用户的邮箱地址或电话号码发送到 Singular，请使用独立的 SingularUserDetails API。SDK 会在设备上对这些值进行规范化并使用 SHA-256 哈希，因此原始的邮箱地址和电话号码不会被传输。
适用版本： Unity SDK 5.10.0 及以上版本。这两个方法在 Unity 编辑器中不执行任何操作，请在设备或模拟器上验证。
选择哈希模式
提供 User Details 有两种方式。请为每位用户选择一种并保持一致。
- SDK 哈希（推荐）： 传入明文邮箱地址或电话号码。SDK 会对值进行规范化并哈希，生成 Singular 可用于匹配的所有变体。
- 预哈希： 传入您已自行规范化并使用 SHA-256 哈希的值。SDK 会原样存储，不做任何额外处理。当您的应用不能持有明文值时使用此方式。
重要： 如果您同时设置了明文值及其对应的预哈希变体，预哈希值优先。
SingularUserDetails Setter
每个 setter 都会返回同一个 SingularUserDetails 实例，因此可以链式调用。传入 null、空字符串或空白字符会移除该值，而不是存储它。
| 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 —— 以及用于判断是否设置了任何值的 IsEmpty。
在初始化前设置 User Details
Unity 没有单独的配置期 User Details API。在 SDK 初始化之前调用 SetUserDetails，这些值会被保留并随第一个会话一起发送，因此从第一个请求开始就会附带这些值。
// Called before the Singular SDK initializes
SingularUserDetails userDetails = new SingularUserDetails()
.SetEmail("user@example.com")
.SetPhoneNumber("+15551234567");
SingularSDK.SetUserDetails(userDetails);在初始化后设置 User Details
如果只有在登录或注册后才能获取邮箱地址或电话号码，请在那时调用 SetUserDetails。此后，这些值会附加到 SDK 发送的每个会话和事件中。
// Cleartext values, hashed by the SDK
SingularUserDetails userDetails = new SingularUserDetails()
.SetEmail("user@example.com")
.SetPhoneNumber("+15551234567");
SingularSDK.SetUserDetails(userDetails);
// Or supply your own SHA-256 hashes
SingularUserDetails hashed = new SingularUserDetails()
.SetEmailSTD("b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514")
.SetPhoneE164("8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4");
SingularSDK.SetUserDetails(hashed);方法签名：
public static void SetUserDetails(SingularUserDetails details)清除 User Details
存储的 User Details 会在应用多次启动之间保留在设备上，并在卸载应用时一并删除。请在登出时，或用户撤回同意时调用 ClearUserDetails 将其移除。
// Remove stored user details on logout
SingularSDK.ClearUserDetails();方法签名：
public static void ClearUserDetails()注意： 在后续启动中调用 SetUserDetails 不会清除之前存储的内容。传入 SetUserDetails(null)，或未设置任何值的 SingularUserDetails，同样会清除已存储的数据，而不是保持原样。
验证与隐私行为
- 验证发生的位置： Unity 层会原样存储您传入的值并转发给原生 SDK，由原生 SDK 进行验证。被拒绝的值由原生 SDK 记录到日志中，不会发送。
-
邮箱验证： 明文邮箱地址必须恰好包含一个
@，且其后有一个点号。无效值会被拒绝并记录到日志中，不会发送。 - 电话号码验证： 明文电话号码必须至少包含 6 位数字。更短的值会被拒绝并记录到日志中。
-
模式误用防护： 看起来已经过哈希的值会被
SetEmail和SetPhoneNumber拒绝。同样，预哈希 setter 会拒绝任何非 64 位 SHA-256 十六进制字符串的值。 - Limit Data Sharing: 在启用 Limit Data Sharing 期间，User Details 载荷会从所有请求中排除。请参阅数据隐私.
- 同意： 仅在具备合法依据时才收集和发送邮箱地址与电话号码。哈希并不能免除您在 GDPR、CCPA 或同等法规下的义务。