Primeiros passos

Configuração do script

Todas as opções e atributos de dados disponíveis do script de rastreamento

O script de rastreamento do Flowsery Analytics suporta varios atributos data para personalizar o comportamento de rastreamento. Este guia cobre todas as opcoes de configuracao disponiveis.

Novo no Flowsery Analytics?

Comece pelo guia de instalacao para adicionar o script de rastreamento ao seu site.

Atributos do script

ID do site — data-fl-website-id (obrigatorio)

Seu identificador unico de site do Flowsery Analytics.

Tag script basica
<script
  defer
  data-fl-website-id="flid_******"
  data-domain="your_domain.com"
  src="https://analytics.flowsery.com/js/script.js"
></script>

Dominio — data-domain (obrigatorio)

O dominio raiz do seu site. Usado para gerenciamento de cookies entre subdominios.

Rastreamento de subdominios

Por padrao, o Flowsery Analytics rastreia todos os subdominios do seu dominio raiz. Por exemplo, se seu dominio raiz e example.com, o Flowsery Analytics opera em app.example.com, blog.example.com, shop.example.com, etc.

Hostnames permitidos — data-allowed-hostnames (opcional)

Lista de dominios adicionais separados por virgula para rastreamento entre dominios.

  • Padrao: Vazio (sem rastreamento entre dominios)
  • Exemplo: app.io,shop.example.com
  • Caso de uso: Rastrear usuarios em diferentes dominios raiz
Rastreamento entre dominios
<script
  defer
  data-fl-website-id="flid_******"
  data-domain="your_domain.com"
  data-allowed-hostnames="app.io,myapp.org"
  src="https://analytics.flowsery.com/js/script.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 configuracoes avancadas de proxy

Se voce fornecer um caminho relativo, ele sera adicionado ao seu dominio.

Deteccao automatica de proxy

O Flowsery Analytics detecta automaticamente configuracoes 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". Padrao: 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". Padrao: false.

Modo debug — data-debug (opcional)

Ative o modo debug para permitir rastreamento dentro de iframes. Aceita "true" ou "false". Padrao: false. Por padrao, o Flowsery Analytics nao 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". Padrao: false.

Desativar pagamentos — data-disable-payments (opcional)

Desative o rastreamento automatico de pagamentos e a atribuicao de receita a partir de parametros de URL (Stripe session_id, LemonSqueezy order_id, Polar checkout_id). Aceita "true" ou "false". Padrao: false.

  • Caso de uso: Quando voce usa atribuicao 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 opcao esta ativada. Apenas a deteccao automatica a partir de parametros de URL e desativada.

Atributos de elementos HTML

Estes atributos sao adicionados aos elementos HTML da sua pagina para ativar o rastreamento automatico.

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

Rastreie cliques em qualquer elemento como objetivo personalizado. Apenas letras minusculas, numeros, sublinhados e hifens. Max 64 caracteres.

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

Parametros de objetivo — data-fs-goal-* (opcional)

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

Objetivo com parametros
<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 visivel durante a rolagem. Gatilho padrao: elemento 50% visivel. 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. Numero decimal entre 0 e 1. Padrao: 0.5 (50% do elemento visivel). 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. Padrao: 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>

Parametros de rolagem — data-fs-scroll-*

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

Exemplos de configuracao comuns

Ambiente de desenvolvimento

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

Producao com proxy

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

O Flowsery Analytics detecta automaticamente configuracoes com proxy. Nenhum data-api e necessario se voce fizer proxy tanto de /js/script.js quanto de /api/events.

Rastreamento entre dominios

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

Use a mesma configuracao em todos os dominios rastreados.

Rastreamento de navegacao por hash

Para aplicacoes de pagina unica com roteamento por hash:

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

Resumo das regras de validacao

Nomes de objetivos e eventos

  • Caracteres: Letras minusculas, numeros, sublinhados (_), hifens (-)
  • Comprimento: Maximo de 64 caracteres

Nomes de parametros personalizados

  • Caracteres: Letras minusculas, numeros, sublinhados (_), hifens (-)
  • Comprimento: Maximo de 64 caracteres
  • Conversao: atributos kebab-case sao automaticamente convertidos para snake_case

Valores de parametros personalizados

  • Comprimento: Maximo de 255 caracteres
  • HTML/XSS: Caracteres perigosos sao automaticamente higienizados
  • Limite: Maximo de 10 parametros personalizados por evento

Limite de rolagem

Numero decimal, intervalo de 0.0 a 1.0, padrao 0.5.

Atraso de rolagem

Inteiro (milissegundos), intervalo 0 ou maior, padrao 0.

Solucao de problemas

Rastreamento nao funciona no localhost

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

Objetivos personalizados nao disparam

Verifique se o nome do seu objetivo segue as regras de validacao: apenas minusculas, sem espacos ou caracteres especiais (exceto _ e -), max 64 caracteres.

Rastreamento entre dominios nao funciona

Verifique: mesmo data-fl-website-id em todos os dominios, todos os dominios adicionais listados em data-allowed-hostnames, os usuarios clicam nos links entre os dominios.

Rastreamento de rolagem nao dispara

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