Establecer un ID de usuario y User Details hasheados

Envíe su ID de usuario interno a Singular para permitir el seguimiento entre dispositivos y la generación de informes de datos a nivel de usuario.

Nota: Si utiliza la solución Cross-Device de Singular, debe recopilar el ID de usuario en todas las plataformas.

Requisitos de ID de usuario

Privacidad y buenas prácticas

Siga estas directrices cuando implemente el seguimiento de ID de usuario para garantizar el cumplimiento de la privacidad y la medición adecuada entre dispositivos.

Sin PII: El ID de usuario no debe exponer información personal identificable (PII) como direcciones de correo electrónico, nombres de usuario o números de teléfono. Utilice un valor hash único para sus datos de origen. Para enviar una dirección de correo electrónico o un número de teléfono, use en su lugar la API dedicada de User Details hasheados.
Coherencia entre plataformas: El valor del ID de usuario debe ser el mismo identificador interno que capture en todas las plataformas (Web/Móvil/PC/Consola/Offline) para una medición precisa entre dispositivos.
Datos de primera parte: Singular incluye el ID de usuario en las exportaciones a nivel de usuario, ETL y postbacks de BI interno (si está configurado). El ID de usuario es un dato de primera parte y no se comparte con terceros.
Persistencia: El ID de usuario persiste hasta que se anula explícitamente mediante unsetCustomUserId() o hasta que se desinstala la aplicación. Cerrar o reiniciar la aplicación no borra el ID de usuario.

Resumen de la implementación

Cuándo establecer el ID de usuario

Utilice Singular.setCustomUserId() para establecer el identificador de usuario y Singular.unsetCustomUserId() para borrarlo durante el cierre de sesión.

Práctica recomendada: Si varios usuarios comparten un mismo dispositivo, implementa un flujo de cierre de sesión que llame a setCustomUserId() al iniciar sesión y a unsetCustomUserId() al finalizarla.

Si ya conoce el identificador de usuario cuando se abre la aplicación, configúrelo mediante withCustomUserId() antes de inicializar Singular SDK. Esto garantiza que Singular reciba el identificador de usuario desde la primera sesión. Sin embargo, el ID de usuario no suele estar disponible hasta que el usuario se registra o inicia sesión, en cuyo caso llame a setCustomUserId() una vez finalizado el flujo de registro o autenticación.

Métodos SDK

Establecer ID de usuario personalizado

Envíe su ID de usuario interno a Singular para el seguimiento entre dispositivos y la generación de informes a nivel de usuario.

// 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');

Firma del método:

static setCustomUserId(customUserId: string): void

Ejemplo: Establecer ID de usuario después del inicio de sesión

Llame a setCustomUserId() inmediatamente después de que el usuario complete con éxito la autenticación para asegurarse de que todos los eventos posteriores se asocian con su ID de usuario.

// 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);
  }
}

Desactivar ID de usuario personalizado

Borre el ID de usuario cuando un usuario cierre la sesión para garantizar un seguimiento preciso de la sesión en dispositivos multiusuario.

// 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();

Firma del método:

static unsetCustomUserId(): void

Ejemplo: Desactivar ID de usuario al cerrar sesión

Llame a unsetCustomUserId() durante el flujo de cierre de sesión para borrar el ID de usuario y evitar la atribución incorrecta de eventos posteriores.

// 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);
  }
}

Establecer ID de usuario durante la inicialización

Si el ID de usuario está disponible cuando se inicia la aplicación (por ejemplo, el usuario ya ha iniciado sesión), configúrelo durante la inicialización del SDK utilizando withCustomUserId(). Esto garantiza que la primera sesión incluya el ID de usuario.

// 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
  );
}

Firma del método de configuración:

withCustomUserId(customUserId: string): SingularConfig

Recomendación: Utilice withCustomUserId()durante la inicialización para aplicaciones con sesiones de inicio de sesión persistentes. Para aplicaciones en las que los usuarios deben iniciar sesión cada vez, llame a setCustomUserId() después de la autenticación.

User Details hasheados (correo electrónico y teléfono)

El ID de usuario descrito arriba es su propio identificador opaco. Si además desea enviar la dirección de correo electrónico o el número de teléfono del usuario a Singular, use la API independiente SingularUserDetails. El SDK normaliza y aplica un hash SHA-256 a estos valores en el dispositivo, por lo que la dirección de correo electrónico y el número de teléfono sin procesar nunca se transmiten.

Disponibilidad: Versión 4.3.0 y superiores del SDK de React Native.

Elegir un modo de hasheo

Hay dos formas de proporcionar los User Details. Elija una por usuario y manténgala de forma consistente.

Hasheo por el SDK (recomendado): Pase el correo electrónico o el número de teléfono en texto claro. El SDK normaliza el valor, le aplica hash y genera todas las variantes con las que Singular puede hacer matching.
Pre-hasheado: Pase valores que usted ya normalizó y hasheó con SHA-256. El SDK los almacena exactamente como se los proporciona y no realiza ningún procesamiento adicional. Use esta opción cuando su app no pueda mantener User Details en texto claro en el momento de la llamada.

Importante: Si establece tanto un valor en texto claro como su variante pre-hasheada correspondiente, prevalece el valor pre-hasheado.

Setters de SingularUserDetails

Setter	Detalles
`setEmail`	Modo: Hasheo por el SDK Dirección de correo electrónico en texto claro. El SDK elimina los espacios y convierte el valor a minúsculas antes de aplicar el hash. Para las direcciones de `gmail.com` y `googlemail.com` también genera una segunda variante en la que se eliminan el sufijo `+tag` y todos los puntos de la parte local. Ejemplo: `user@example.com`
`setPhoneNumber`	Modo: Hasheo por el SDK Número de teléfono en texto claro. El SDK genera dos variantes: una en formato E.164 que conserva el `+` inicial y elimina el resto de los caracteres no numéricos, y otra únicamente con dígitos que también elimina el `+`. Incluya el código de país para que la variante E.164 sea utilizable. Ejemplo: `+15551234567`
`setEmailSTD`	Modo: Pre-hasheado Hash SHA-256 de la dirección de correo electrónico después de eliminar los espacios y convertirla a minúsculas.
`setEmailNoDots`	Modo: Pre-hasheado Hash SHA-256 de la dirección de correo electrónico después de eliminar los espacios, convertirla a minúsculas y quitar el sufijo `+tag` y todos los puntos de la parte local. Se aplica a las direcciones de tipo Gmail.
`setPhoneE164`	Modo: Pre-hasheado Hash SHA-256 del número de teléfono en formato E.164, conservando el `+` inicial.
`setPhoneDigits`	Modo: Pre-hasheado Hash SHA-256 del número de teléfono con todos los caracteres no numéricos eliminados, incluido el `+` inicial.

Cada setter devuelve el mismo objeto, por lo que las llamadas se pueden encadenar. En la New Architecture también puede pasar un objeto simple con las mismas seis claves: email, phoneNumber, emailSTD, emailNoDots, phoneE164 y phoneDigits.

Establecer los User Details en la inicialización

Establezca SingularConfig.userDetails antes de llamar a init(), o use el builder withUserDetails(), para que los User Details se adjunten a la primera sesión que envía el 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);

Firma del método de configuración:

withUserDetails(userDetails: SingularUserDetails): SingularConfig

Establecer los User Details después de la inicialización

Si la dirección de correo electrónico o el número de teléfono solo se conocen después del inicio de sesión o del registro, llame a setUserDetails en ese momento. A partir de entonces, los valores se adjuntan a todas las sesiones y eventos que envía el 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);

Firma del método:

static setUserDetails(userDetails: SingularUserDetails): void

Nota: setUserDetails() no tiene efecto antes de init(): el SDK nativo registra un error y retorna. Use SingularConfig.userDetails para cubrir la primera sesión.

Borrar los User Details

Los User Details almacenados persisten en el dispositivo: en el Keychain en iOS y en almacenamiento cifrado en Android, y se conservan entre inicios de la app. Llame a clearUserDetails() al cerrar sesión, o cuando el usuario retire su consentimiento, para eliminarlos.

// 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();

Firma del método:

static clearUserDetails(): void

Nota: Como los valores se persisten, asignar SingularConfig.userDetails en un inicio posterior no borra lo que se almacenó antes. clearUserDetails es la única forma de eliminarlo.

Validación y comportamiento de privacidad

Capa de JavaScript: SingularUserDetails descarta cualquier valor que no sea una cadena no vacía, incluidas las cadenas literales "null" y "undefined". No comprueba el formato del valor.
Validación del correo electrónico: Un correo electrónico en texto claro debe contener exactamente una @ y un punto después de ella. Los valores no válidos se rechazan y se registran en el log; no se envían.
Validación del teléfono: Un número de teléfono en texto claro debe contener al menos 6 dígitos. Los valores más cortos se rechazan y se registran en el log.
Protección contra el modo incorrecto: Un valor que ya parece hasheado es rechazado por setEmail y setPhoneNumber. De la misma forma, los setters pre-hasheados rechazan cualquier valor que no sea una cadena hexadecimal SHA-256 de 64 caracteres.
Limit Data Sharing: Mientras Limit Data Sharing esté habilitado, la carga de User Details se excluye de todas las solicitudes. Consulte: Privacidad de datos.
Consentimiento: Recopile y envíe direcciones de correo electrónico y números de teléfono únicamente cuando tenga una base legal para hacerlo. El hasheo no elimina sus obligaciones bajo el GDPR, la CCPA o regulaciones equivalentes.

SDK de React Native - Establecer un ID de usuario y User Details hasheados

Establecer un ID de usuario y User Details hasheados

Requisitos de ID de usuario

Privacidad y buenas prácticas

Resumen de la implementación

Cuándo establecer el ID de usuario

Métodos SDK

Establecer ID de usuario personalizado

Ejemplo: Establecer ID de usuario después del inicio de sesión

Desactivar ID de usuario personalizado

Ejemplo: Desactivar ID de usuario al cerrar sesión

Establecer ID de usuario durante la inicialización

User Details hasheados (correo electrónico y teléfono)

Elegir un modo de hasheo

Setters de SingularUserDetails

Establecer los User Details en la inicialización

Establecer los User Details después de la inicialización

Borrar los User Details

Validación y comportamiento de privacidad