Saltar al contenido principal

Sincroniza preferencias de usuarios identificados

Sincroniza preferencias de usuarios identificados

Inicia una sesión identificada cuando tu aplicación conoce al usuario. Soyio restaura su preferencia vigente en otro dispositivo o vincula la decisión anónima tomada antes del registro.

Una decisión anónima crea un CookieConsentAction. Este recibo inmutable incluye la decisión, el sitio, la configuración mostrada, su hash y la cadena de recibos. No crea Entity, Agreement ni Evidence.

La Entity de tu user_reference nace al emitir el token de sesión, no al atribuir la decisión. Soyio la crea o la asocia en esa llamada, para ambos intents, aunque el visitante nunca decida.

Cuando atribuyes la decisión, Soyio materializa recursos reales:

  • Agreement con los permisos del CookieSite
  • Evidence con el snapshot inmutable
  • Perfil interno para sincronizar la preferencia vigente

Los IDs de Agreement y Evidence aparecen en CookieConsentAction solo después de crear esos recursos.

En claim_visitor, Soyio también crea una Entity de navegador cookie:<csite_token>:<visitor_uuid> cuando hay historial anónimo que reclamar y la fusiona al sujeto canónico. Es un artefacto interno de la cadena de merge. Revisa Cookies y tu integración de consentimiento para ver cómo se relaciona con tu consentimiento existente.

Elige el flujo​

MomentoIntentResultado
Registro o conversión explícitaclaim_visitorReclama el historial anónimo firmado y usa la decisión más reciente
Inicio de sesiónsync_preferencesRestaura solo el perfil del usuario, sin reclamar historial anónimo

Usa claim_visitor una sola vez al convertir al visitante. En un navegador compartido, usa siempre sync_preferences para cambiar de cuenta.

1. Crea el token desde tu backend​

Envía un user_reference interno y estable. Soyio encuentra o crea la Entity y devuelve un JWT con 15 minutos de vigencia. El JWT no contiene el user_reference. Reutiliza el mismo user_reference de tu consentimiento existente para no separar los sujetos: revisa Cookies y tu integración de consentimiento.

Backend
curl --request POST \
  --url https://app.soyio.id/api/v1/cookie_sites/csite_TU_TOKEN/subject_session_token \
  --header "Authorization: Bearer $SOYIO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_reference": "customer-user-123",
    "intent": "sync_preferences"
  }'
Respuesta
{
  "token": "eyJ...",
  "expires_at": "2026-07-27T18:15:00Z"
}

Mantén la API key en tu backend. Envía al navegador solo el token temporal.

Consulta el request, los permisos y los errores en crear un token de sesión de cookies.

2. Inicia la sesión en el navegador​

Entrega el token temporal desde tu backend y pásalo al loader:

frontend.ts
const response = await fetch('/api/cookie-subject-session', {
  method: 'POST',
});
const { token } = await response.json();

const result = await window.soyioCookies.startSubjectSession(token);

if (result.status === 'consent_required') {
  console.log('Soyio mostrará el banner');
}

startSubjectSession() devuelve uno de estos estados:

  • profile_applied: aplicó una preferencia vigente
  • history_claimed: reclamó el historial anónimo y aplicó su preferencia
  • consent_required: falta una preferencia vigente para la configuración publicada

La sincronización se limita al mismo CookieSite. Una preferencia expirada o asociada a otra versión de la configuración no se aplica.

3. Renueva sesiones largas​

El token vence después de 15 minutos para limitar la exposición de la credencial. Antes de expires_at, solicita otro token con sync_preferences y reemplázalo en el loader:

frontend.ts
const response = await fetch('/api/cookie-subject-session', {
  method: 'POST',
});
const { token } = await response.json();

await window.soyioCookies.refreshSubjectSession(token);

El loader usa el token nuevo para registrar los próximos cambios de preferencias. Repite la renovación mientras la sesión de tu aplicación siga activa.

4. Termina la sesión​

Termina la sesión antes de cerrar sesión en tu aplicación:

frontend.ts
await window.soyioCookies.endSubjectSession();

Soyio elimina el contexto identificado y rota el identificador del navegador. Conserva la preferencia local efectiva, pero las acciones anónimas posteriores no se atribuyen a la cuenta anterior.

Si el token activo ya venció, solicita otro token con sync_preferences y pásalo al cierre:

frontend.ts
await window.soyioCookies.endSubjectSession(token);

Reglas de seguridad​

  • No envíes user_reference ni la API key al navegador
  • No uses claim_visitor durante un inicio de sesión normal
  • Crea el token para el mismo CookieSite instalado en la página
  • Inicia la sesión antes de que el usuario cambie sus preferencias
  • Termina la sesión al cerrar o cambiar de cuenta

Sigue con bloqueo y verificación para aplicar cada categoría a tus scripts.

Si ya integraste el módulo de consentimiento, revisa Cookies y tu integración de consentimiento para reutilizar la misma Entity.