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.

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. 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 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 em exportações ao nível do utilizador, ETL e postbacks de BI interno (se configurado). O ID de utilizador é um dado primário 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 Singular.setCustomUserId() para definir o identificador de utilizador e Singular.unsetCustomUserId() para o limpar durante o fim de sessão.

Se você já sabe a ID de usuário quando o aplicativo é aberto, configure-a usando withCustomUserId() antes de inicializar o SDK do Singular. Isso garante que o Singular receba a ID de usuário da primeira sessão. No entanto, a ID de utilizador normalmente não está disponível até que o utilizador se registe ou inicie sessão, caso em que deve chamar setCustomUserId() após a conclusão do fluxo de registo 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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';

// Set the user ID after login or registration
NativeSingular.setCustomUserId('user_123456');

import { Singular } from 'singular-react-native';

// Set the user ID after login or registration
Singular.setCustomUserId('user_123456');

Assinatura do método:

static setCustomUserId(customUserId: string): void

Exemplo: Definir ID de usuário após o login

Chame setCustomUserId() imediatamente após o utilizador concluir a autenticação com sucesso para garantir que todos os eventos subsequentes são associados ao seu ID de utilizador.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';

async function handleUserLogin(email, password) {
  try {
    // Your authentication logic
    const response = await authenticateUser(email, password);

    if (response.success) {
      // Set the user ID in Singular after successful login
      NativeSingular.setCustomUserId(response.userId);

      console.log('User ID set:', response.userId);

      // Navigate to home screen
      navigateToHome();
    }
  } catch (error) {
    console.error('Login failed:', error);
  }
}

import { Singular } from 'singular-react-native';

async function handleUserLogin(email, password) {
  try {
    // Your authentication logic
    const response = await authenticateUser(email, password);

    if (response.success) {
      // Set the user ID in Singular after successful login
      Singular.setCustomUserId(response.userId);

      console.log('User ID set:', response.userId);

      // Navigate to home screen
      navigateToHome();
    }
  } catch (error) {
    console.error('Login failed:', error);
  }
}

Anular a definição do ID de utilizador personalizado

Limpe o ID de utilizador quando um utilizador termina a sessão para garantir um acompanhamento preciso da sessão para dispositivos com vários utilizadores.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';

// Unset the user ID on logout
NativeSingular.unsetCustomUserId();

import { Singular } from 'singular-react-native';

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

Assinatura do método:

static unsetCustomUserId(): void

Exemplo: Anular a definição do ID de utilizador no fim da sessão

Chame unsetCustomUserId() durante o fluxo de logout para limpar o ID do usuário e evitar a atribuição incorreta de eventos subsequentes.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';

async function handleUserLogout() {
  try {
    // Clear app data and user session
    await clearUserSession();

    // Unset the user ID in Singular
    NativeSingular.unsetCustomUserId();

    console.log('User ID cleared');

    // Navigate to login screen
    navigateToLogin();
  } catch (error) {
    console.error('Logout failed:', error);
  }
}

import { Singular } from 'singular-react-native';

async function handleUserLogout() {
  try {
    // Clear app data and user session
    await clearUserSession();

    // Unset the user ID in Singular
    Singular.unsetCustomUserId();

    console.log('User ID cleared');

    // Navigate to login screen
    navigateToLogin();
  } catch (error) {
    console.error('Logout failed:', error);
  }
}

Definir ID de utilizador durante a inicialização

Se a ID de utilizador estiver disponível quando a aplicação for iniciada (por exemplo, o utilizador já tiver iniciado sessão), configure-a durante a inicialização do SDK utilizando withCustomUserId(). Isto garante que a primeira sessão inclui a ID de utilizador.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import AsyncStorage from '@react-native-async-storage/async-storage';

export default function App() {
  useEffect(() => {
    initializeSingular();
  }, []);

  async function initializeSingular() {
    // Check if user is already logged in
    const userId = await AsyncStorage.getItem('user_id');

    // Create configuration object
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      ...(userId ? { customUserId: userId } : {}),
    };

    // Initialize SDK
    NativeSingular.init(config);
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';
import AsyncStorage from '@react-native-async-storage/async-storage';

export default function App() {
  useEffect(() => {
    initializeSingular();
  }, []);

  async function initializeSingular() {
    // Check if user is already logged in
    const userId = await AsyncStorage.getItem('user_id');

    // Create configuration
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // If user ID exists, set it during initialization
    if (userId) {
      config.withCustomUserId(userId);
    }

    // Initialize SDK
    Singular.init(config);
  }

  return (
    // Your app components
  );
}

Assinatura do método de configuração:

withCustomUserId(customUserId: string): SingularConfig

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 devolve o mesmo objeto, pelo que as chamadas podem ser encadeadas. Na New Architecture também pode passar um objeto simples com as mesmas seis chaves: email, phoneNumber, emailSTD, emailNoDots, phoneE164 e phoneDigits.

Definir os User Details na inicialização

Defina SingularConfig.userDetails antes de chamar init(), ou use o builder withUserDetails(), para que os User Details sejam anexados à primeira sessão enviada pelo SDK.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
const config: SingularConfig = {
  apikey: 'YOUR_SDK_KEY',
  secret: 'YOUR_SDK_SECRET',
  userDetails: {
    email: 'user@example.com',
    phoneNumber: '+15551234567'
  }
};
NativeSingular.init(config);

import { Singular, SingularConfig, SingularUserDetails } from 'singular-react-native';
const userDetails = new SingularUserDetails()
  .setEmail('user@example.com')
  .setPhoneNumber('+15551234567');
const config = new SingularConfig('YOUR_SDK_KEY', 'YOUR_SDK_SECRET')
  .withUserDetails(userDetails);
Singular.init(config);

Assinatura do método de configuração:

withUserDetails(userDetails: SingularUserDetails): SingularConfig

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.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
// Cleartext values, hashed on the device by the SDK
NativeSingular.setUserDetails({
  email: 'user@example.com',
  phoneNumber: '+15551234567'
});
// Or supply your own SHA-256 hashes
NativeSingular.setUserDetails({
  emailSTD: 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514',
  phoneE164: '8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4'
});

import { Singular, SingularUserDetails } from 'singular-react-native';
// Cleartext values, hashed on the device by the SDK
const userDetails = new SingularUserDetails()
  .setEmail('user@example.com')
  .setPhoneNumber('+15551234567');
Singular.setUserDetails(userDetails);
// Or supply your own SHA-256 hashes
const hashed = new SingularUserDetails()
  .setEmailSTD('b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514')
  .setPhoneE164('8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4');
Singular.setUserDetails(hashed);

Assinatura do método:

static setUserDetails(userDetails: SingularUserDetails): void

Limpar os User Details

Os User Details armazenados persistem no dispositivo: no Keychain no iOS e em armazenamento cifrado no Android, sobrevivendo aos arranques da app. Chame clearUserDetails() no logout, ou quando o utilizador retirar o consentimento, para os remover.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
// Remove stored user details on logout
NativeSingular.clearUserDetails();

import { Singular } from 'singular-react-native';
// Remove stored user details on logout
Singular.clearUserDetails();

Assinatura do método:

static clearUserDetails(): void

Validação e comportamento de privacidade

• Camada de JavaScript: SingularUserDetails descarta qualquer valor que não seja uma string não vazia, incluindo as strings literais "null" e "undefined". Não verifica o formato do valor.
• 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.