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.

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

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

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

Elige el flujo

Momento	Intent	Resultado
Registro o conversión explícita	claim_visitor	Reclama el historial anónimo firmado y usa la decisión más reciente
Inicio de sesión	sync_preferences	Restaura 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.

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.