getting-started

O script de rastreamento do Flowsery Analytics suporta vários atributos data para personalizar o comportamento de rastreamento. Este guia cobre todas as opções de configuração disponíveis.

Novo no Flowsery Analytics?

Comece pelo guia de instalação para adicionar o script de rastreamento ao seu site.

Atributos do script

ID do site, data-fl-website-id (obrigatório)

O seu identificador único de site do Flowsery Analytics. Este é o único atributo obrigatório.

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

Domínio, data-domain (opcional)

Define o escopo do cookie para os IDs de visitante e de sessão. Por padrão usa location.hostname, então sites com um único domínio podem omiti-lo. Defina-o quando quiser que um único cookie de visitante seja compartilhado entre subdomínios. Por exemplo, data-domain="example.com" permite que example.com, app.example.com e blog.example.com compartilhem o mesmo ID de visitante. Não tem efeito no modo sem cookies.

Rastreamento de subdomínios

Por padrão, o Flowsery Analytics rastreia todos os subdomínios do seu domínio raiz. O data-domain controla o escopo do cookie, não os hostnames que são rastreados. Por exemplo, se o seu domínio raiz é example.com, o Flowsery Analytics também opera em app.example.com, blog.example.com, shop.example.com, etc.

Hostnames permitidos, data-allowed-hostnames (opcional)

Lista de domínios adicionais separados por vírgula para rastreamento entre domínios.

  • Padrão: Vazio (sem rastreamento entre domínios)
  • Exemplo: app.io,shop.example.com
  • Caso de uso: Rastrear usuários em diferentes domínios raiz
Rastreamento entre domínios
<script
  defer
  data-fl-website-id="flid_******"
  data-allowed-hostnames="app.io,myapp.org"
  src="https://cdn.flowsery.com/main.js"
></script>

URL da API: data-api (opcional)

Endpoint de API personalizado para envio de eventos. Aceita uma URL completa ou um caminho relativo.

  • Exemplo: https://api.example.com/events ou /custom-events
  • Caso de uso: Endpoints de API personalizados, proxies de analise de terceiros ou configurações avançadas de proxy

Se você fornecer um caminho relativo, ele sera adicionado ao seu domínio.

Detecção automática de proxy

O Flowsery Analytics detecta automaticamente configurações com proxy. Use isso apenas se precisar de um caminho de endpoint personalizado ou se quiser enviar eventos para um servidor completamente diferente.

Permitir Localhost: data-local (opcional)

Ative o rastreamento em localhost para desenvolvimento e testes. Aceita "true" ou "false". Padrão: false.

Permitir protocolo File: data-allow-file-protocol (opcional)

Ative o rastreamento ao abrir arquivos HTML diretamente no navegador (protocolo file://). Aceita "true" ou "false". Padrão: false.

Modo debug, data-debug (opcional)

Ative o modo debug para permitir rastreamento dentro de iframes. Aceita "true" ou "false". Padrão: false. Por padrão, o Flowsery Analytics não rastreia dentro de iframes para evitar rastreamento duplicado.

Desativar console, data-disable-console (opcional)

Desative todos os logs de console do rastreador Flowsery Analytics. Aceita "true" ou "false". Padrão: false.

Desativar pagamentos, data-disable-payments (opcional)

Desative o rastreamento automático de pagamentos e a atribuição de receita a partir de parâmetros de URL (Stripe session_id, LemonSqueezy order_id, Polar checkout_id). Aceita "true" ou "false". Padrão: false.

  • Caso de uso: Quando você usa atribuição de receita do lado do servidor para evitar eventos de pagamento duplicados

Rastreamento manual de pagamentos

Chamadas manuais window.flowsery("payment", { email }) ainda funcionam quando esta opção esta ativada. Apenas a detecção automática a partir de parâmetros de URL e desativada.

Atributos de elementos HTML

Estes atributos são adicionados aos elementos HTML da sua página para ativar o rastreamento automático.

Rastreamento de objetivos, data-fs-goal (opcional)

Rastreie cliques em qualquer elemento como objetivo personalizado. Apenas letras minúsculas, números, sublinhados e hifens. Max 64 caracteres.

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

Parâmetros de objetivo, data-fs-goal-* (opcional)

Adicione parâmetros personalizados aos eventos de objetivo. O nome do parâmetro é derivado do nome do atributo (kebab-case, convertido para snake_case). Max 10 parâmetros por evento. Nomes de parâmetros: max 64 caracteres. Valores: max 255 caracteres.

Objetivo com 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>

Rastreamento de rolagem, data-fs-scroll (opcional)

Rastreie automaticamente quando um elemento se torna visível durante a rolagem. Gatilho padrão: elemento 50% visível. Mesmas regras de nomenclatura que data-fs-goal.

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

Limite de rolagem, data-fs-scroll-threshold (opcional)

Personalize o limite de visibilidade para rastreamento de rolagem. Número decimal entre 0 e 1. Padrão: 0.5 (50% do elemento visível). Valores comuns: 0.1 (10%), 0.5 (50%), 0.9 (90%), 1.0 (100%).

Atraso de rolagem, data-fs-scroll-delay (opcional)

Adicione um atraso em milissegundos antes que o evento de rolagem seja rastreado. Padrão: 0 (sem atraso).

Rastreamento de rolagem com limite e atraso
<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 rolagem, data-fs-scroll-*

Adicione parâmetros personalizados aos eventos de rastreamento de rolagem, semelhantes a data-fs-goal-*.

Exemplos de configuração comuns

Ambiente de desenvolvimento

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

Produção com proxy

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

O Flowsery Analytics detecta automaticamente as configurações de proxy. Não será necessária a API de dados se você fizer proxy de /js/main.js e /api/track.

Rastreamento entre domínios

<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 a mesma configuração em todos os domínios rastreados.

Rastreamento de navegação por hash

Para aplicações de página única com roteamento por hash:

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

Resumo das regras de validação

Nomes de objetivos e eventos

  • Caracteres: Letras minúsculas, números, sublinhados (_), hifens (-)
  • Comprimento: Máximo de 64 caracteres

Nomes de parâmetros personalizados

  • Caracteres: Letras minúsculas, números, sublinhados (_), hifens (-)
  • Comprimento: Máximo de 64 caracteres
  • Conversão: atributos kebab-case são automaticamente convertidos para snake_case

Valores de parâmetros personalizados

  • Comprimento: Máximo de 255 caracteres
  • HTML/XSS: Caracteres perigosos são automaticamente higienizados
  • Limite: Máximo de 10 parâmetros personalizados por evento

Limite de rolagem

Número decimal, intervalo de 0.0 a 1.0, padrão 0.5.

Atraso de rolagem

Inteiro (milissegundos), intervalo 0 ou maior, padrão 0.

Solução de problemas

Rastreamento não funciona no localhost

Adicione data-local="true" para ativar o rastreamento local.

Objetivos personalizados não disparam

Verifique se o nome do seu objetivo segue as regras de validação: apenas minúsculas, sem espaços ou caracteres especiais (exceto _ e -), max 64 caracteres.

Rastreamento entre domínios não funciona

Verifique: mesmo data-fl-website-id em todos os domínios, todos os domínios adicionais listados em data-allowed-hostnames, os usuários clicam nos links entre os domínios.

Rastreamento de rolagem não dispara

Problemas comuns: elemento não esta no viewport tempo suficiente, limite definido muito alto, IntersectionObserver não suportado.