设置用户 ID 和哈希 User Details
将您内部的用户 ID 发送到 Singular,以启用跨设备追踪 和用户级别的数据报告。
注意: 如果您使用 Singular 的跨设备解决方案 ,则必须在所有平台上 收集用户 ID。
用户 ID 要求
隐私和最佳实践
在实施用户 ID 追踪时,请遵循以下准则,以确保符合隐私规定 并实现准确的跨设备测量。
- 禁止 PII: 用户 ID 不应暴露个人身份识别信息(PII), 例如电子邮件地址、用户名或电话号码。请使用基于您第一方数据的 唯一哈希值。 如需发送电子邮件地址或电话号码,请改用专用的 哈希 User Details API。
- 跨平台一致性: 用户 ID 的值必须是您在所有平台 (Web/移动端/PC/主机/线下)上获取的相同内部标识符, 以实现准确的跨设备测量。
- 第一方数据: Singular 会将用户 ID 包含在用户级别的导出、 ETL 和内部 BI 回调中(如已配置)。 用户 ID 是第一方数据,不会与第三方共享。
-
持久性:
用户 ID 会一直保留,直到使用
unsetCustomUserId()显式取消设置或应用被卸载为止。 关闭或重启应用不会清除用户 ID。
实施概述
何时设置用户 ID
使用
setCustomUserId()
设置用户标识符,使用
unsetCustomUserId()
在登出时清除它。
最佳实践:
如果多个用户共用一台设备,
请实施一个登出流程,在登录时调用
setCustomUserId()
,并在登出时调用
unsetCustomUserId()
。
如果在应用启动时已知用户 ID,请在初始化 Singular SDK 之前调用
setCustomUserId()
。
这可确保 Singular 从第一个会话开始就收到用户 ID。但是,
用户 ID 通常要等到用户注册或登录后才能获取,在这种情况下,
请在注册或身份验证流程完成后调用
setCustomUserId()
。
SDK 方法
设置 Custom User ID
将您内部的用户 ID 发送到 Singular,用于跨设备追踪和 用户级别的报告。
// Set the user ID after login or registration
Singular.setCustomUserId("custom_user_id")// Set the user ID after login or registration
[Singular setCustomUserId:@"custom_user_id"];方法签名:
+ (void)setCustomUserId:(NSString *)customUserId;
+setCustomUserId:
返回
void
— 在调用处没有成功/失败信号。用户 ID 会
附加到 SDK 发送的下一个会话和事件上。
名称相似的
+setDeviceCustomUserId:
被标注为
__attribute__((deprecated))
,仅出于遗留兼容性而存在。新代码中请始终调用
+setCustomUserId:
。
取消设置 Custom User ID
在用户登出时清除用户 ID,以确保在多用户设备上进行准确的 会话追踪。
// Unset the user ID on logout
Singular.unsetCustomUserId()// Unset the user ID on logout
[Singular unsetCustomUserId];方法签名:
+ (void)unsetCustomUserId;哈希 User Details(电子邮件和电话号码)
上述用户 ID 是您自己的不透明标识符。如果您还想将用户的电子邮件地址或电话号码发送到 Singular,请使用独立的 SingularUserDetails API。SDK 会在设备上对这些值进行规范化并使用 SHA-256 哈希,因此原始的电子邮件地址和电话号码不会被传输。
适用版本: iOS SDK 12.14.0 及以上版本。此 API 在 Kids SDK 版本中不可用。
选择哈希模式
提供 User Details 有两种方式。请为每位用户选择一种并保持一致。
- SDK 哈希(推荐): 传入明文电子邮件地址或电话号码。SDK 会规范化该值、进行哈希,并生成 Singular 可用于匹配的所有变体。
- 预哈希: 传入您已自行规范化并使用 SHA-256 哈希的值。SDK 会完全按照提供的内容存储,不做任何进一步处理。当您的应用在调用时不能持有明文 User Details 时,请使用此方式。
重要: 如果您同时设置了明文值及其对应的预哈希变体,预哈希值优先。
SingularUserDetails Setter
| Setter | 详情 |
|---|---|
setEmail
|
模式: SDK 哈希
明文电子邮件地址。SDK 会在哈希前去除空格并转换为小写。对于
示例:
|
setPhoneNumber
|
模式: SDK 哈希
明文电话号码。SDK 会生成两个变体:一个是保留开头
示例:
|
setEmailSTD
|
模式: 预哈希 去除空格并转换为小写后的电子邮件地址的 SHA-256 哈希值。 |
setEmailNoDots
|
模式: 预哈希
去除空格、转换为小写,并从本地部分移除 |
setPhoneE164
|
模式: 预哈希
保留开头 |
setPhoneDigits
|
模式: 预哈希
去除所有非数字字符(包括开头的 |
每个 setter 都有对应的 getter(getEmail、getPhoneNumber、getEmailSTD、getEmailNoDots、getPhoneE164、getPhoneDigits),返回您所设置的值。
在初始化时设置 User Details
在调用 start 之前将该对象赋值给 SingularConfig.userDetails,这样 User Details 就会附加到 SDK 发送的第一个会话中。
let config = SingularConfig(apiKey: "SDK KEY", andSecret: "SDK SECRET")
let userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")
config.userDetails = userDetails
Singular.start(config)SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK KEY"
andSecret:@"SDK SECRET"];
SingularUserDetails *userDetails = [SingularUserDetails new];
[userDetails setEmail:@"user@example.com"];
[userDetails setPhoneNumber:@"+15551234567"];
config.userDetails = userDetails;
[Singular start:config];在初始化后设置 User Details
如果只有在登录或注册后才能获取电子邮件地址或电话号码,请在那时调用 setUserDetails。此后,这些值会附加到 SDK 发送的每个会话和事件中。
// Cleartext values, hashed by the SDK
let userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")
Singular.setUserDetails(userDetails)
// Or supply your own SHA-256 hashes
let hashed = SingularUserDetails()
hashed.setEmailSTD("b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514")
hashed.setPhoneE164("8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4")
Singular.setUserDetails(hashed)// Cleartext values, hashed by the SDK
SingularUserDetails *userDetails = [SingularUserDetails new];
[userDetails setEmail:@"user@example.com"];
[userDetails setPhoneNumber:@"+15551234567"];
[Singular setUserDetails:userDetails];
// Or supply your own SHA-256 hashes
SingularUserDetails *hashed = [SingularUserDetails new];
[hashed setEmailSTD:@"b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"];
[hashed setPhoneE164:@"8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4"];
[Singular setUserDetails:hashed];方法签名:
+ (void)setUserDetails:(SingularUserDetails *)userDetails;清除 User Details
存储的 User Details 保存在 iOS Keychain 中,并在应用多次启动之间保持。请在登出时,或用户撤回同意时调用 clearUserDetails 将其移除。
// Remove stored user details on logout
Singular.clearUserDetails()// Remove stored user details on logout
[Singular clearUserDetails];方法签名:
+ (void)clearUserDetails;
注意:
由于这些值会被持久化,在后续启动中赋值 SingularConfig.userDetails 不会清除之前存储的内容。clearUserDetails 是唯一的移除方式。
验证与隐私行为
-
电子邮件验证:
明文电子邮件必须包含且仅包含一个
@,且其后需有一个点号。无效值会被拒绝并记录到日志,不会被发送。 - 电话号码验证: 明文电话号码必须包含至少 6 位数字。更短的值会被拒绝并记录到日志。
-
模式误用防护:
看起来已经过哈希的值会被
setEmail和setPhoneNumber拒绝。同样,预哈希 setter 会拒绝任何非 64 位 SHA-256 十六进制字符串的值。 - Limit Data Sharing: 在启用 Limit Data Sharing 期间,User Details 载荷将从所有请求中排除。 参阅: 数据隐私.
- 同意: 仅在您具有合法依据的情况下收集和发送电子邮件地址和电话号码。哈希处理并不免除您在 GDPR、CCPA 或同等法规下的义务。