getting-started

El script de seguimiento de Flowsery Analytics admite varios atributos de datos para personalizar el comportamiento del seguimiento. Esta guía cubre todas las opciones de configuración disponibles.

¿Nuevo en Flowsery Analytics?

Comience primero con la guía de instalación para agregar el script de seguimiento a su sitio web.

Atributos del script

ID del sitio web -- data-fl-website-id (obligatorio)

Su identificador único de sitio web de Flowsery Analytics. Es el único atributo obligatorio.

Etiqueta script básica
<script
  defer
  data-fl-website-id="flid_******"
  src="https://cdn.flowsery.com/main.js"
></script>

Dominio -- data-domain (opcional)

Define el ámbito de la cookie para los IDs de visitante y de sesión. Por defecto usa location.hostname, por lo que los sitios de un solo dominio pueden omitirlo. Configúrelo cuando quiera que una única cookie de visitante se comparta entre subdominios; por ejemplo, data-domain="example.com" permite que example.com, app.example.com y blog.example.com compartan el mismo ID de visitante. No tiene efecto en el modo sin cookies.

Seguimiento de subdominios

Flowsery Analytics rastrea todos los subdominios de su dominio raíz por defecto: data-domain controla el ámbito de la cookie, no qué nombres de host se rastrean. Por ejemplo, si su dominio raíz es example.com, Flowsery Analytics también opera en app.example.com, blog.example.com, shop.example.com, etc.

Nombres de host permitidos -- data-allowed-hostnames (opcional)

Lista separada por comas de dominios adicionales para seguimiento entre dominios.

  • Predeterminado: Vacío (sin seguimiento entre dominios)
  • Ejemplo: app.io,shop.example.com
  • Caso de uso: Rastrear usuarios a través de diferentes dominios raíz
Seguimiento entre dominios
<script
  defer
  data-fl-website-id="flid_******"
  data-allowed-hostnames="app.io,myapp.org"
  src="https://cdn.flowsery.com/main.js"
></script>

URL de la API -- data-api (opcional)

Endpoint API personalizado para enviar eventos. Acepta una URL completa o una ruta relativa.

  • Ejemplo: https://api.example.com/events o /custom-events
  • Caso de uso: Endpoints API personalizados, proxies de análisis de terceros o configuraciones avanzadas de proxy

Si proporciona una ruta relativa, se agrega a su dominio.

Detección automática de proxy

Flowsery Analytics detecta automáticamente las configuraciones con proxy. Solo use esto si necesita una ruta de endpoint personalizada o desea enviar eventos a un servidor completamente diferente.

Permitir Localhost -- data-local (opcional)

Habilitar seguimiento en localhost para desarrollo y pruebas. Acepta "true" o "false". Predeterminado: false.

Permitir protocolo de archivo -- data-allow-file-protocol (opcional)

Habilitar seguimiento al abrir archivos HTML directamente en el navegador (protocolo file://). Acepta "true" o "false". Predeterminado: false.

Modo de depuración -- data-debug (opcional)

Habilitar el modo de depuración para permitir seguimiento dentro de iframes. Acepta "true" o "false". Predeterminado: false. Por defecto, Flowsery Analytics no rastrea dentro de iframes para evitar seguimiento duplicado.

Deshabilitar consola -- data-disable-console (opcional)

Deshabilitar todos los registros de consola del rastreador de Flowsery Analytics. Acepta "true" o "false". Predeterminado: false.

Deshabilitar pagos -- data-disable-payments (opcional)

Deshabilitar el seguimiento automático de pagos y la atribución de ingresos desde parámetros de URL (Stripe session_id, LemonSqueezy order_id, Polar checkout_id). Acepta "true" o "false". Predeterminado: false.

  • Caso de uso: Cuando se usa atribución de ingresos del lado del servidor para evitar eventos de pago duplicados

Seguimiento manual de pagos

Las llamadas manuales a window.flowsery("payment", { email }) siguen funcionando cuando esta opción está habilitada. Solo se deshabilita la detección automática desde parámetros de URL.

Atributos de elementos HTML

Estos atributos se agregan a los elementos HTML en su página para habilitar el seguimiento automático.

Seguimiento de objetivos -- data-fs-goal (opcional)

Rastrear clics en cualquier elemento como un objetivo personalizado. Solo letras minúsculas, números, guiones bajos, guiones. Máx. 64 caracteres.

<button data-fs-goal="add_to_cart">Add to Cart</button>

Parámetros de objetivos -- data-fs-goal-* (opcional)

Agregar parámetros personalizados a los eventos de objetivos. El nombre del parámetro se deriva del nombre del atributo (kebab-case, convertido a snake_case). Máx. 10 parámetros por evento. Nombres de parámetros: máx. 64 caracteres. Valores: máx. 255 caracteres.

Objetivo con parámetros
<button
  data-fs-goal="product_added"
  data-fs-goal-product-id="prod_123"
  data-fs-goal-product-name="Premium Plan"
  data-fs-goal-price="49">
  Add to Cart
</button>

Seguimiento de scroll -- data-fs-scroll (opcional)

Rastrear automáticamente cuando un elemento se hace visible durante el desplazamiento. Disparador predeterminado: elemento visible al 50%. Mismas reglas de nomenclatura que data-fs-goal.

<section data-fs-scroll="viewed_pricing">
  <h2>Pricing</h2>
</section>

Umbral de scroll -- data-fs-scroll-threshold (opcional)

Personalizar el umbral de visibilidad para el seguimiento de scroll. Decimal entre 0 y 1. Predeterminado: 0.5 (50% del elemento visible). Valores comunes: 0.1 (10%), 0.5 (50%), 0.9 (90%), 1.0 (100%).

Retraso de scroll -- data-fs-scroll-delay (opcional)

Agregar un retraso en milisegundos antes de que se registre el evento de scroll. Predeterminado: 0 (sin retraso).

Seguimiento de scroll con umbral y retraso
<section
  data-fs-scroll="read_testimonials"
  data-fs-scroll-threshold="0.7"
  data-fs-scroll-delay="3000">
  <!-- Tracks only if element stays visible for 3 seconds -->
</section>

Parámetros de scroll -- data-fs-scroll-*

Agregar parámetros personalizados a los eventos de seguimiento de scroll, similar a data-fs-goal-*.

Ejemplos de configuración comunes

Entorno de desarrollo

<script
  defer
  data-fl-website-id="flid_******"
  data-local="true"
  src="https://cdn.flowsery.com/main.js"
></script>

Producción con proxy

<script
  defer
  data-fl-website-id="flid_******"
  src="/js/main.js"
></script>

Flowsery Analytics detecta automáticamente configuraciones de proxy. No se necesita data-api si utiliza el proxy tanto /js/main.js como /api/track.

Seguimiento entre dominios

<script
  defer
  data-fl-website-id="flid_******"
  data-domain="example.com"
  data-allowed-hostnames="app.io,shop.example.net"
  src="https://cdn.flowsery.com/main.js"
></script>

Use la misma configuración en todos los dominios rastreados.

Seguimiento de navegación basada en hash

Para aplicaciones de página única con enrutamiento hash:

<script
  defer
  data-fl-website-id="flid_******"
  src="https://cdn.flowsery.com/main.hash.js"
></script>

Resumen de reglas de validación

Nombres de objetivos y eventos

  • Caracteres: Letras minúsculas, números, guiones bajos (_), guiones (-)
  • Longitud: Máximo 64 caracteres

Nombres de parámetros personalizados

  • Caracteres: Letras minúsculas, números, guiones bajos (_), guiones (-)
  • Longitud: Máximo 64 caracteres
  • Conversión: Los atributos en kebab-case se convierten automáticamente a snake_case

Valores de parámetros personalizados

  • Longitud: Máximo 255 caracteres
  • HTML/XSS: Los caracteres peligrosos se sanean automáticamente
  • Límite: Máximo 10 parámetros personalizados por evento

Umbral de scroll

Número decimal, rango de 0.0 a 1.0, predeterminado 0.5.

Retraso de scroll

Entero (milisegundos), rango 0 o superior, predeterminado 0.

Solución de problemas

El seguimiento no funciona en localhost

Agregue data-local="true" para habilitar el seguimiento local.

Los objetivos personalizados no se disparan

Verifique que el nombre de su objetivo siga las reglas de validación: solo minúsculas, sin espacios ni caracteres especiales (excepto _ y -), máx. 64 caracteres.

El seguimiento entre dominios no funciona

Verifique: mismo data-fl-website-id en todos los dominios, todos los dominios adicionales listados en data-allowed-hostnames, los usuarios hacen clic en enlaces entre dominios.

El seguimiento de scroll no se activa

Problemas comunes: el elemento no permanece en el viewport suficiente tiempo, umbral configurado demasiado alto, IntersectionObserver no compatible.