SDK do Unity - Definindo um ID de usuário e User Details hasheados

Seguir
Avatar
Jared Ornstead
Updated

Definindo um ID de usuário e User Details hasheados

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

Nota: Se você usar a solução Cross-Device da Singular, você deve coletar o ID do usuário em todas as plataformas.

Requisitos de ID de usuário

Privacidade e práticas recomendadas

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

  • Sem PII: A ID de utilizador não deve expor informações de identificação pessoal (PII), tais como endereços de correio eletrónico, nomes de utilizador ou números de telefone. Use um valor com hash exclusivo para seus dados primários.
  • Consistência entre plataformas: O valor da ID de utilizador deve ser o mesmo identificador interno que capta 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 utilizador nas exportações ao nível do utilizador, ETL e postbacks do BI interno (se configurado). O ID de utilizador é um dado de primeira parte e não é partilhado com terceiros.
  • Persistência: O ID de utilizador persiste até ser explicitamente desativado utilizando UnsetCustomUserId() ou até a aplicação ser desinstalada. Fechar ou reiniciar a aplicação não apaga o ID de utilizador.

Descrição geral da implementação

Quando definir o ID de utilizador

Utilize SetCustomUserId() para definir o identificador de utilizador e UnsetCustomUserId() para o limpar durante o fim de sessão.

Melhores práticas: Se vários utilizadores partilharem um único dispositivo, implemente um fluxo de fim de sessão que chame SetCustomUserId() no início de sessão e UnsetCustomUserId() no fim de sessão.

Se você já souber a ID de usuário quando o aplicativo for aberto, chame SetCustomUserId() antes de inicializar o SDK do Singular. No entanto, a 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

Definir ID de usuário personalizada

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

C# 
// Set the user ID after login or registration
SingularSDK.SetCustomUserId("custom_user_id");

Assinatura do método: 

public static void SetCustomUserId(string customUserId)

Cancelar definição da ID de usuário personalizada

Limpe a ID de usuário quando um usuário fizer logout para garantir o rastreamento preciso da sessão para dispositivos multiusuário.

C# 
// Unset the user ID on logout
SingularSDK.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 SHA-256 a esses valores no dispositivo, portanto o e-mail e o telefone originais nunca são transmitidos.

Disponibilidade: SDK do Unity versão 5.10.0 e superiores. Ambos os métodos não fazem nada no Editor do Unity; execute-os em um dispositivo ou emulador.

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 o hash e gera todas as variantes que a Singular pode usar para correspondência.
  • Pré-hasheado: Passe valores que você já normalizou e aplicou SHA-256. O SDK os armazena exatamente como fornecidos e não faz nenhum processamento adicional. Use quando o seu app não puder manter valores em texto simples.

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

Cada setter retorna a mesma instância de SingularUserDetails, portanto as chamadas podem ser encadeadas. Passar null, uma string vazia ou espaços em branco remove aquele valor em vez de armazená-lo.

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, também gera uma segunda variante sem o sufixo +tag e sem os pontos 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 os demais 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 o getter correspondente — GetEmail, GetPhoneNumber, GetEmailSTD, GetEmailNoDots, GetPhoneE164 e GetPhoneDigits — além de IsEmpty, que informa se algum valor foi definido.

Definir os User Details antes da inicialização

O Unity não tem uma API de configuração separada para os User Details. Chame SetUserDetails antes de o SDK inicializar e os valores são mantidos e enviados com a primeira sessão, de modo que ficam anexados desde a primeira requisição.

C#
// Called before the Singular SDK initializes
SingularUserDetails userDetails = new SingularUserDetails()
    .SetEmail("user@example.com")
    .SetPhoneNumber("+15551234567");

SingularSDK.SetUserDetails(userDetails);

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.

C#
// 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);

Assinatura do método:

public static void SetUserDetails(SingularUserDetails details)

Limpar os User Details

Os User Details armazenados persistem no dispositivo entre inicializações do app e são removidos quando o app é desinstalado. Chame ClearUserDetails no logout, ou quando o usuário retirar o consentimento, para removê-los.

C#
// Remove stored user details on logout
SingularSDK.ClearUserDetails();

Assinatura do método:

public static void ClearUserDetails()

Observação: Chamar SetUserDetails em uma inicialização posterior não apaga o que foi armazenado antes. Passar SetUserDetails(null), ou um SingularUserDetails sem nenhum valor definido, também apaga os dados armazenados em vez de mantê-los intactos.

Validação e comportamento de privacidade

  • Onde a validação acontece: A camada do Unity armazena o que você passa e encaminha para o SDK nativo, que valida os valores. Os valores rejeitados são registrados pelo SDK nativo e não são enviados.
  • Validação do 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, e não são enviados.
  • Validação do telefone: Um número de telefone em texto simples deve conter pelo menos 6 dígitos. Valores mais curtos são rejeitados e registrados.
  • Proteção contra o modo incorreto: Um valor que já parece hasheado é rejeitado por SetEmail e SetPhoneNumber. Da mesma forma, os setters pré-hasheados rejeitam qualquer coisa que não seja uma string hexadecimal SHA-256 de 64 caracteres.
  • Limit Data Sharing: Enquanto o Limit Data Sharing estiver ativado, o payload de User Details é excluído de todas as requisiçõ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 hash não elimina as suas obrigações sob GDPR, CCPA ou regulamentações equivalentes.