Configurando um ID de usuário e User Details hasheados

Envie seu ID de usuário interno para o Singular para habilitar o rastreamento entre dispositivos e relatórios de dados em nível de usuário.

Requisitos do ID de usuário

Privacidade e melhores práticas

Siga estas diretrizes ao implementar o rastreamento do ID de usuário para garantir a conformidade com a privacidade e a medição correta entre dispositivos.

• Sem PII: O ID de usuário não deve expor Informações de Identificação Pessoal (PII), como endereços de e-mail, nomes de usuário ou números de telefone. Use um valor hasheado e único dos seus dados próprios (first-party). Para enviar um endereço de e-mail ou número de telefone, use a API dedicada de User Details hasheados.
• Consistência entre plataformas: O valor do ID de usuário deve ser o mesmo identificador interno que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline) para uma medição precisa entre dispositivos.
• Dados próprios (first-party): O Singular inclui o ID de usuário em exportações em nível de usuário, ETL e postbacks de BI internos (se configurados). O ID de usuário é um dado próprio e não é compartilhado com terceiros.
• Persistência: O ID de usuário persiste até ser explicitamente desativado usando unsetCustomUserId() ou até que o aplicativo seja desinstalado. Fechar ou reiniciar o aplicativo não limpa o ID de usuário.

Visão geral da implementação

Quando configurar o ID de usuário

Use setCustomUserId() para configurar o identificador do usuário e unsetCustomUserId() para limpá-lo durante o logout.

Se você já conhece o ID de usuário quando o aplicativo é aberto, chame setCustomUserId() antes de inicializar o SDK do Singular. Isso garante que o Singular receba o ID de usuário desde a primeira sessão. No entanto, o ID de usuário normalmente não está disponível até que o usuário se registre ou faça login. Nesse caso, chame setCustomUserId() após a conclusão do fluxo de registro ou autenticação.

Métodos do SDK

Configurar o Custom User ID

Envie seu ID de usuário interno para o Singular para rastreamento entre dispositivos e relatórios em nível de usuário.

// 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"];

Assinatura do método:

+ (void)setCustomUserId:(NSString *)customUserId;

Desativar o Custom User ID

Limpe o ID de usuário quando um usuário fizer logout para garantir o rastreamento preciso das sessões em dispositivos multiusuário.

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

// Unset the user ID on logout
[Singular unsetCustomUserId];

Assinatura do método:

+ (void)unsetCustomUserId;

User Details hasheados (e-mail e telefone)

O ID de usuário descrito acima é o seu próprio identificador opaco. Se você também quiser enviar o endereço de e-mail ou o número de telefone do usuário ao Singular, use a API separada SingularUserDetails. O SDK normaliza e aplica hash SHA-256 a esses valores no dispositivo, portanto o endereço de e-mail e o número de telefone brutos nunca são transmitidos.

Escolher um modo de hash

Há duas formas de fornecer os User Details. Escolha uma por usuário e mantenha a consistência.

• Hash pelo SDK (recomendado): Passe o e-mail ou o número de telefone em texto simples. O SDK normaliza o valor, aplica hash e gera todas as variantes que o Singular pode usar para correspondência.
• Pré-hasheado: Passe valores que você já normalizou e submeteu a hash SHA-256. O SDK os armazena exatamente como fornecidos e não realiza nenhum processamento adicional. Use esta opção quando seu app não puder manter User Details em texto simples no momento da chamada.

Setters de SingularUserDetails

Cada setter tem um getter correspondente (getEmail, getPhoneNumber, getEmailSTD, getEmailNoDots, getPhoneE164, getPhoneDigits) que retorna o valor definido.

Definir os User Details na inicialização

Atribua o objeto a SingularConfig.userDetails antes de chamar start para que os User Details sejam anexados à primeira sessão enviada pelo 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];

Definir os User Details após a inicialização

Se o endereço de e-mail ou o número de telefone só forem conhecidos após o login ou o registro, chame setUserDetails nesse momento. A partir daí, os valores são anexados a todas as sessões e eventos enviados pelo 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];

Assinatura do método:

+ (void)setUserDetails:(SingularUserDetails *)userDetails;

Limpar os User Details

Os User Details armazenados persistem no Keychain do iOS entre inicializações do app. Chame clearUserDetails no logout, ou quando o usuário retirar o consentimento, para removê-la.

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

// Remove stored user details on logout
[Singular clearUserDetails];

Assinatura do método:

+ (void)clearUserDetails;

Validação e comportamento de privacidade

• Validação de e-mail: Um e-mail em texto simples deve conter exatamente um @ e um ponto depois dele. Valores inválidos são rejeitados e registrados em log, não enviados.
• Validação de telefone: Um número de telefone em texto simples deve conter pelo menos 6 dígitos. Valores mais curtos são rejeitados e registrados em log.
• Proteção contra modo incorreto: Um valor que já parece hasheado é rejeitado por setEmail e setPhoneNumber. Da mesma forma, os setters pré-hasheados rejeitam qualquer valor que não seja uma string hexadecimal SHA-256 de 64 caracteres.
• Limit Data Sharing: Enquanto o Limit Data Sharing estiver habilitado, o payload de User Details é excluído de todas as solicitações. Consulte: Privacidade de dados.
• Consentimento: Colete e envie endereços de e-mail e números de telefone apenas quando houver base legal para isso. O uso de hash não elimina suas obrigações sob o GDPR, a CCPA ou regulamentações equivalentes.