Personalización

El área de Personalización de Relevance Studio convierte señales de usuario anónimas y autenticadas en ajustes al ranking. Está construida sobre cuatro capas, cada una opcional y activable de forma independiente por índice:

1. Perfiles de usuario — vectores de características por usuario derivados del historial de compras y clics.
2. Segmentos — cohortes amplias (p. ej. "compradores frecuentes", "cazadores de descuentos") que agrupan perfiles para boosts sintonizables por el editor.
3. Reranking de sesión — reordenación corta en la sesión, basada en las últimas consultas y clics.
4. Recomendaciones — bloques productos relacionados, también compraron, vistos juntos con frecuencia, alimentados por el mismo store de perfiles.

Cuándo activar la personalización

Active la personalización cuando las tres condiciones se cumplen:

• Su buscador tiene un concepto real de usuario recurrente (autenticado o ID anónimo estable).
• Tiene al menos ~10k eventos de clic por índice y semana — por debajo, la señal es demasiado ruidosa.
• Las curations del editor no bastan para diferenciar la misma consulta entre distintos usuarios.

Si tiene dudas, empiece con solo reranking de sesión — no necesita historial y se degrada a no-op para visitantes nuevos.

Cómo personalize=true + sessionId se cablean al search call

Toda petición de búsqueda pública puede optar in enviando dos campos extra:

• personalize: true en el body — activa la capa para esta consulta.
• sessionId: "<id-estable>" — un UUID o cookie hasheada que ata la petición al perfil (o, para anónimos, a su sesión).

El servidor resuelve estos campos en el camino de lectura, antes del multi_search de Typesense, y AND-combina una expresión de boost de perfil al ranking existente. El flujo es los mismos cinco gates de una búsqueda normal — auth, rate limit, tenant filter, scoped filter, multi_search — con un paso extra entre rate-limit y tenant-filter: applyPersonalization.

IDs estables y PII

sessionId DEBE ser opaco para AACsearch. No envíe emails crudos, números de teléfono, ni IDs de usuario de su CRM. El patrón recomendado:

sessionId = sha256(your_internal_user_id + BETTER_AUTH_SECRET_FRAGMENT).slice(0, 32)

El historial server-side que respalda cada perfil se limita a 100 entradas por sesión. Los clics y vistas más antiguos se descartan FIFO. Es intencional: mantiene el perfil pequeño, rápido de cargar en el camino caliente, y fácil de expirar para peticiones de derecho al olvido GDPR (un solo DELETE /personalization/profile/<sessionId> lo limpia).

Ejemplo: curl

curl -X POST https://api.aacsearch.com/api/search/public/multi \
  -H "Authorization: Bearer ss_search_pub_XXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "collection": "products",
        "q": "running shoes",
        "query_by": "title,brand,description",
        "personalize": true,
        "sessionId": "9f3c1b2e8a7d4f6c0b1a2d3e4f5a6b7c"
      }
    ]
  }'

La forma de la respuesta no cambia. Si personalize=true no se puede aplicar — perfil vacío, personalización desactivada en el índice, o falta del entitlement Scale — la petición cae limpiamente al ranking estándar y un flag personalization_applied: false se incluye en los metadatos.

Ejemplo: SDK TypeScript / cliente oRPC

import { client } from "@repo/api/client";

const res = await client.search.public.multi.call({
  searches: [
    {
      collection: "products",
      q: "running shoes",
      query_by: "title,brand,description",
      personalize: true,
      sessionId: visitorSessionId, // sha256(uid + secret).slice(0, 32)
    },
  ],
});

Para uso en navegador prefiera el flujo de scoped search token descrito en Arquitectura → Camino de lectura — los campos personalize y sessionId se reenvían sin cambios por el token.

Cablear el boost de perfil al ranking

En Studio → Relevancia → Personalización, un admin elige cómo las features del perfil influyen en el ranking. Tres modos soportados:

El peso del boost es un número 0–10. Empiece en 1.0, mire CTR en el panel Feedback de clics una semana, y suba en pasos de 0.5. Por encima de 5.0 domina típicamente a las curations — solo vaya allí si lo validó en un A/B.

Segmentos

Un segmento es un filtro guardado sobre el espacio de perfiles. Los segmentos se definen en Studio y se evalúan server-side en cada petición personalizada. Ejemplos out-of-the-box:

• frequent_buyers — perfiles con ≥ 3 compras en los últimos 30 días.
• cart_abandoners — perfiles con ≥ 1 add_to_cart y 0 purchase en 7 días.
• discount_hunters — perfiles cuyos productos clicados tenían discount_pct > 0 en ≥ 50% de los clics recientes.

Cada segmento tiene su propio peso de boost. Un usuario en dos segmentos recibe el máximo de los dos (no la suma) — esto mantiene la matemática predecible cuando se solapan.

Recomendaciones

El mismo store de perfiles alimenta los endpoints de recomendación. Están expuestos como procedures oRPC propios y no requieren personalize=true en el search call:

• recommendations.related — basado en contenido: similar al productId de entrada.
• recommendations.alsoBought — colaborativo: del grafo clic-y-compra.
• recommendations.frequentlyViewedTogether — co-vista dentro de la sesión.

Vea la sección dedicada Recomendaciones para el schema completo de petición y respuesta.

Mejores prácticas sobre PII

1. Nunca envíe email / teléfono / customer ID crudo en sessionId. Hashee primero con un secret del servidor.
2. Trate sessionId como un token, no un identificador. Debe rotar al cerrar sesión.
3. Limite el historial a 100 entradas. Es el default server-side y la única configuración soportada — documentado aquí para que los clientes razonen sobre retención.
4. Cablee un hook de delete GDPR. Cuando un usuario invoque derecho al olvido, llame a la procedure personalization.profile.delete con su sessionId estable. La limpieza es síncrona e idempotente.
5. No personalice sesiones admin con sesión cerrada. Las consultas de modo inspección desde Studio deben pasar personalize=false para que el explicador de ranking vea el ranking sin sesgo.

Relacionado

• Referencia de API de Personalización — schema completo de petición y respuesta para personalize=true y recommendations.*.
• Learning to Rank — bucle de feedback ortogonal que aprende de clics independientemente de la personalización.
• Arquitectura → Camino de lectura — dónde se sitúa el paso applyPersonalization en el flujo.
• Recomendaciones — la superficie que consume el mismo store de perfiles.