Saltar a contenido

Guia de Instalacion del Script de Audiencias

Este documento explica como instalar y usar el script de audiencias en un sitio web cliente.

El script consulta audiencias e intereses asociados a un identificador anonimo del visitante y deja esa informacion disponible para que el sitio pueda usarla en personalizacion, pauta, analitica u otras integraciones propias.

Que Hace el Script

El script realiza el siguiente flujo en el navegador:

  1. Busca la cookie __eventn_id en el sitio.
  2. Usa ese valor como identificador anonimo del visitante.
  3. Hace una peticion GET /resolve con anon y client_id (tenant).
  4. Recibe las audiencias e intereses asociados a ese visitante.
  5. Si la respuesta viene con ingest_pending: true o audiences vacio por lag de ingestión, puede reintentar tras unos segundos.
  6. Deja la respuesta disponible en variables globales de window.
  7. Dispara un evento personalizado para que otros scripts puedan capturar la respuesta.

El servicio de resolucion:

  1. Consulta primero el cache (Valkey) por anonymous_id.
  2. Si no hay membresia y se envio client_id, evalua en vivo contra las audiencias activas del CDP (ClickHouse) y escribe el resultado en cache.
  3. Devuelve audiences, interests y, si aplica, ingest_pending.

El script esta disenado para no bloquear la carga del sitio. Si no encuentra el identificador anonimo, si la peticion falla o si el servicio no responde a tiempo, el sitio continua funcionando normalmente.

Manejo de la API Key

El script incluye un valor configurable para autenticar la peticion:

const API_KEY = "TU_API_KEY";

Importante: no se debe incluir una API key privada o sensible directamente en codigo frontend. Todo valor incluido en un script del navegador puede ser visto por usuarios, herramientas de desarrollo, proxies, logs de red o terceros con acceso al sitio.

Para entornos productivos, se recomienda usar una de estas alternativas:

  • Usar un token publico restringido, emitido exclusivamente para uso desde navegador.
  • Usar un token con permisos limitados solo para consulta de audiencias.
  • Usar tokens de corta duracion generados por un backend del cliente.
  • Hacer que el sitio llame a un endpoint propio del cliente y que ese backend agregue las credenciales necesarias.

Si se entrega un token para usar directamente en el script, ese token debe tratarse como publico y no como secreto.

Donde Instalar el Script

El script debe instalarse dentro del <head> del sitio web, preferiblemente lo mas arriba posible despues de los scripts que crean la cookie __eventn_id, si existen.

Ejemplo:

<head>
  <!-- Otros scripts requeridos por el sitio -->

  <script src="https://cdn.example.com/scriptHead.js" async></script>
</head>

Tambien puede instalarse inline si el cliente recibe el contenido completo del archivo:

<head>
  <script>
    (function () {
      // Contenido del script entregado
    })();
  </script>
</head>

Configuracion Basica

Antes de instalarlo, se deben revisar estos valores dentro del script:

const RESOLVER_URL = "https://resolver.rcnaudiences.com/resolve";
const API_KEY = "TU_API_KEY";
const CLIENT_ID = "rcn"; // tenant del CDP, por ejemplo rcn

RESOLVER_URL corresponde al servicio que entrega las audiencias.

API_KEY debe reemplazarse solo por el token o mecanismo de autenticacion acordado para el cliente. No debe usarse una credencial privada en frontend.

CLIENT_ID es el identificador del tenant en el CDP (el mismo que se usa en aud:<client_id>:<audience_slug>). Es necesario para el resolve en vivo: sin client_id, el servicio solo consulta el cache Valkey y un visitante nuevo puede recibir audiences: [] hasta el sync batch.

URL resultante:

GET https://resolver.rcnaudiences.com/resolve?anon=<uuid>&client_id=<tenant>

Respuesta Esperada

El script espera recibir una respuesta JSON con esta estructura:

{
  "anonymous_id": "e2f5d9a9-14eb-4b93-a403-d17eb0412872",
  "audiences": ["aud:rcn:test-interests"],
  "interests": ["noticias", "mundo", "colombia"]
}

Cuando el evento page() de Jitsu aun no llego a ClickHouse, la respuesta puede incluir ingest_pending:

{
  "anonymous_id": "e2f5d9a9-14eb-4b93-a403-d17eb0412872",
  "audiences": [],
  "interests": [],
  "ingest_pending": true
}

Campos:

  • anonymous_id: identificador anonimo usado para resolver la informacion.
  • audiences: lista de audiencias asociadas al visitante (puede ser []).
  • interests: lista de intereses asociados al visitante (puede ser []).
  • ingest_pending: opcional. true si aun no hay eventos del visitante en ClickHouse.

Si el visitante no tiene audiencias o intereses disponibles, los arreglos pueden venir vacios. Eso no es necesariamente un error.

Formato de audiencias

Cada elemento de audiences sigue el patron:

aud:<client_id>:<audience_slug>

Ejemplo: aud:rcn:test-interests.

Reintento por lag de ingestión

Un visitante 100% nuevo dispara page() en el sitio; ese evento suele tardar unos segundos en aparecer en ClickHouse. Hasta entonces el resolve puede devolver audiences: [] y/o ingest_pending: true.

Recomendacion:

  1. Llamar a /resolve con anon + client_id cuando exista la cookie.
  2. Si ingest_pending === true (o audiences vacio en la primera respuesta de un visitante nuevo), reintentar tras 5–10 segundos.
  3. Usar la primera respuesta con audiencias no vacias, o aceptar vacio si tras el reintento sigue sin match.
  4. No bloquear la UI mientras se reintenta.

Ejemplo conceptual:

/**
 * Resolve audiences; retry once if ingest is still pending.
 * @param {string} anonymousId
 * @param {string} clientId
 * @returns {Promise<object|null>}
 */
async function resolveWithIngestRetry(anonymousId, clientId) {
  const url =
    RESOLVER_URL +
    "?anon=" +
    encodeURIComponent(anonymousId) +
    "&client_id=" +
    encodeURIComponent(clientId);

  /**
   * @returns {Promise<object|null>}
   */
  async function once() {
    const response = await fetch(url, {
      method: "GET",
      headers: { "x-api-key": API_KEY },
      credentials: "omit",
      cache: "no-store"
    });
    if (!response.ok) return null;
    return response.json();
  }

  let data = await once();
  if (data && data.ingest_pending === true) {
    await new Promise(function (resolve) {
      setTimeout(resolve, 5000);
    });
    data = await once();
  }
  return data;
}

Como Capturar la Respuesta

Cuando el script recibe una respuesta exitosa, guarda los datos en estas variables globales:

window.__MIDAS_AUDIENCES__;
window.__MIDAS_INTERESTS__;
window.__MIDAS_RESOLVER_RESPONSE__;

Ejemplo de uso:

<script>
  console.log(window.__MIDAS_AUDIENCES__);
  console.log(window.__MIDAS_INTERESTS__);
  console.log(window.__MIDAS_RESOLVER_RESPONSE__);
</script>

Como la peticion ocurre de forma asincrona, la forma recomendada de consumir la respuesta es escuchar el evento midas:audiences-ready:

<script>
  window.addEventListener("midas:audiences-ready", function (event) {
    const data = event.detail;

    console.log("Anonymous ID:", data.anonymous_id);
    console.log("Audiences:", data.audiences);
    console.log("Interests:", data.interests);
    console.log("Ingest pending:", data.ingest_pending);
  });
</script>

Ejemplo de Uso en el Sitio

El cliente puede usar las audiencias para activar logica propia:

<script>
  window.addEventListener("midas:audiences-ready", function (event) {
    const audiences = event.detail.audiences || [];
    const interests = event.detail.interests || [];

    if (event.detail.ingest_pending) {
      console.log("Waiting for page event to land in CDP; consider retry");
      return;
    }

    if (audiences.includes("aud:rcn:test-interests")) {
      console.log("Visitor belongs to test-interests audience");
    }

    if (interests.includes("noticias")) {
      console.log("Visitor has noticias interest");
    }
  });
</script>

Recomendacion de Orden

Si otro script del cliente necesita usar las audiencias, debe escuchar el evento antes o justo despues de cargar el script de audiencias:

<head>
  <script>
    window.addEventListener("midas:audiences-ready", function (event) {
      window.CLIENT_AUDIENCE_DATA = event.detail;
    });
  </script>

  <script src="https://cdn.example.com/scriptHead.js" async></script>
</head>

De esta forma, el sitio puede reaccionar apenas la informacion este disponible.

Checklist Rapido

  • [ ] Cookie __eventn_id legible por JavaScript
  • [ ] CLIENT_ID / client_id configurado con el tenant correcto (ej. rcn)
  • [ ] Token x-api-key configurado (publico/restringido o via proxy)
  • [ ] URL: /resolve?anon=...&client_id=...
  • [ ] Manejo de audiences / interests vacios
  • [ ] Reintento cuando ingest_pending === true (5–10s)
  • [ ] Listener de midas:audiences-ready registrado antes del resolve