Esta guía cubre la instalación y el uso del SDK de Clickstream de SurveyAnalytica en proyectos web. El SDK está publicado en npm y funciona en cualquier entorno JavaScript, incluidos Vanilla JS, Next.js y React. Para aplicaciones móviles, consulte la guía de SDKs móviles.

Antes de comenzar, complete la configuración del flujo de trabajo para obtener su API Key y la URL del Endpoint.

Instalación

Sitios en Vanilla JS / HTML

Incluya el paquete UMD directamente en su página. No se requiere ningún paso de compilación.

<script src="https://cdn.jsdelivr.net/npm/@surveyanalytica/clickstream-web/dist/index.umd.js"></script>
<script>
  SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
    endpoint: 'YOUR_ENDPOINT_URL'
  });
</script>

Proyectos npm (Next.js, React, etc.)

npm install @surveyanalytica/clickstream-web

Luego inicialícelo una sola vez, en el punto de entrada de su aplicación:

import { SAClickstream } from '@surveyanalytica/clickstream-web';

SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
  endpoint: 'YOUR_ENDPOINT_URL'
});

Para Next.js, llame a init dentro de un Client Component o en _app.js / layout.js. El SDK es seguro para el renderizado del lado del servidor: todo acceso a las API del navegador está protegido internamente.

Seguimiento de vistas de página

El SDK registra las vistas de página automáticamente. Cada vez que cambia la URL (incluida la navegación en aplicaciones de una sola página mediante la History API), se envía un evento page_view con la URL actual, el título de la página y el referente. No se necesita ningún código más allá de la llamada a init.

Para enviar una vista de página manualmente:

SAClickstream.page('/checkout', { campaign: 'summer-sale' });

Seguimiento de eventos personalizados

SAClickstream.track('button_clicked', {
  label: 'Buy Now',
  productId: 'sku-9821',
  price: 49.99
});

Los valores de las propiedades pueden ser cadenas, números, booleanos u objetos anidados. Mantenga los nombres de los eventos cortos y consistentes en todo su código (por ejemplo, use siempre button_clicked en lugar de mezclar buttonClick y btn_tap).

Identificación de usuarios después del inicio de sesión

Antes del inicio de sesión, el SDK asigna a cada visitante un ID anónimo aleatorio almacenado en localStorage. Después del inicio de sesión, llame a identify con el ID de contacto de su backend:

// After a successful login
SAClickstream.identify('contact-id-from-your-backend');

Esto envía un evento uid_transition que vincula la sesión anónima con el contacto conocido. Los eventos registrados antes del inicio de sesión se asocian al contacto mediante el ID anónimo almacenado en el registro del contacto: no se pierde ningún dato.

Gestión del consentimiento

Si su sitio utiliza un banner de consentimiento de cookies, respete la elección del usuario:

// User accepted tracking
SAClickstream.setConsent(true);

// User declined tracking
SAClickstream.setConsent(false);

Cuando el consentimiento se establece en false, el seguimiento se detiene de inmediato y se elimina la asociación del ID anónimo. No se envían más eventos hasta que el consentimiento se vuelva a otorgar.

Cómo se envían los eventos

El SDK agrupa los eventos y los envía cada 500 milisegundos, o de inmediato cuando se han acumulado 20 eventos en la cola. Las solicitudes fallidas se reintentan hasta tres veces con retrasos crecientes. Esto mantiene bajo el uso de la red sin perder eventos durante problemas temporales de conectividad.

Solución de problemas

Los eventos no aparecen en mi flujo de trabajo

• Confirme que el flujo de trabajo esté en estado Activo.
• Revise la consola del navegador en busca de errores de red en las solicitudes a la URL de su endpoint.
• Verifique que la API Key coincida con la KEY que se muestra en el panel del trigger; cópiela y péguela en lugar de escribirla.
• Asegúrese de que init se llame antes de cualquier llamada a track o page.

Se están registrando vistas de página duplicadas

Si llama a SAClickstream.page() manualmente además del seguimiento automático, verá dos eventos por navegación. Desactive el seguimiento automático (autoPage: false en las opciones de init) o elimine sus llamadas manuales a page().