SDK do Android - Configurando um ID de usuário e User Details hasheados

Seguir
Avatar
Jared Ornstead
Updated

Configurando um ID de usuário e User Details hasheados

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

Observação: Se você usa a solução entre dispositivos da Singular , deve coletar o ID de usuário em todas as plataformas.

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 conformidade com a privacidade e uma medição entre dispositivos adequada.

  • Sem PII: O ID de usuário não deve expor informações de identificação pessoal (PII) como endereços de email, nomes de usuário ou números de telefone. Use um valor hash exclusivo dos seus dados de primeira parte. 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 de primeira parte: A Singular inclui o ID de usuário em exportações no nível do usuário, ETL e postbacks de BI internos (se configurados). O ID de usuário é dado de primeira parte e não é compartilhado com terceiros.
  • Persistência: O ID de usuário persiste até ser explicitamente removido 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 definir o identificador do usuário e unsetCustomUserId() para limpá-lo no logout.

Melhor prática: Se vários usuários compartilham um mesmo dispositivo, implemente um fluxo de logout que chame setCustomUserId() no login e unsetCustomUserId() no logout.

Se você já souber o ID de usuário quando o aplicativo abrir, chame setCustomUserId() antes de inicializar o Singular SDK. Isso garante que a 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 o fluxo de registro ou autenticação ser concluído.

Métodos do SDK

Definir ID de usuário personalizado

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

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

Assinatura do método: 

public static void setCustomUserId(String customUserId);

Remover ID de usuário personalizado

Limpe o ID de usuário quando o usuário fizer logout para garantir um rastreamento de sessão preciso em dispositivos compartilhados por vários usuários.

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

Assinatura do método: 

public static 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.

Disponibilidade: Versão 12.16.0 e superiores do SDK do Android. Esta API não está disponível na versão Kids do SDK.

Escolher um modo de hash

Há duas formas de fornecer PII. 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 PII em texto simples no momento da chamada.

Importante: Se você definir tanto um valor em texto simples quanto a sua variante pré-hasheada correspondente, o valor pré-hasheado prevalece.

Setters de SingularUserDetails

Setter Detalhes
setEmail

Modo: Hash pelo SDK

Endereço de e-mail em texto simples. O SDK remove espaços e converte o valor para minúsculas antes de aplicar o hash. Para endereços gmail.com e googlemail.com, ele também gera uma segunda variante com o sufixo +tag e todos os pontos removidos da parte local.

Exemplo: user@example.com

setPhoneNumber

Modo: Hash pelo SDK

Número de telefone em texto simples. O SDK gera duas variantes: uma no formato E.164 que mantém o + inicial e remove todos os outros caracteres não numéricos, e outra apenas com dígitos, que remove também o +. Inclua o código do país para que a variante E.164 seja utilizável.

Exemplo: +15551234567

setEmailSTD

Modo: Pré-hasheado

Hash SHA-256 do endereço de e-mail após remover os espaços e convertê-lo para minúsculas.

setEmailNoDots

Modo: Pré-hasheado

Hash SHA-256 do endereço de e-mail após remover os espaços, convertê-lo para minúsculas e retirar o sufixo +tag e todos os pontos da parte local. Aplica-se a endereços do tipo Gmail.

setPhoneE164

Modo: Pré-hasheado

Hash SHA-256 do número de telefone no formato E.164, mantendo o + inicial.

setPhoneDigits

Modo: Pré-hasheado

Hash SHA-256 do número de telefone com todos os caracteres não numéricos removidos, incluindo o + inicial.

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

Definir os User Details na inicialização

Encadeie withUserDetails no seu SingularConfig antes de chamar Singular.init para que os User Details sejam anexados à primeira sessão enviada pelo 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)

Definir a PII 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.

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)

Assinatura do método: 

public static void setUserDetails(SingularUserDetails userDetails);

Limpar a PII

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

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

Assinatura do método: 

public static void clearUserDetails();

Observação: O payload é armazenado criptografado no dispositivo, sob uma chave mantida no Android Keystore. Como é persistido, chamar withUserDetails em uma inicialização posterior não apaga o que foi armazenado antes. clearUserDetails é a única forma de removê-los.

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 PII é 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.