Easy Analytics System - Alpha System Plugins

Visão Geral

O Easy Analytics System (EAS) é uma biblioteca JavaScript do lado do cliente, projetada para análise web abrangente. Ele permite que proprietários de sites coletem insights valiosos sobre o comportamento do usuário, desempenho da página e engajamento geral do site. O EAS é leve, configurável e inclui recursos como gerenciamento de consentimento, rastreamento de eventos personalizados e coleta detalhada de dados.

A versão do script documentada aqui é 1.0.0.

Recursos

Rastreamento de Visitantes e Sessões: Identificação única de visitantes e gerenciamento de sessões.
Gerenciamento de Consentimento: Modal de consentimento integrado que respeita as escolhas do usuário (opt-in/opt-out). Suporta armazenamento de consentimento baseado em cookies e sem cookies (localStorage).
Rastreamento de Visualizações de Página: Rastreia automaticamente carregamentos de página e informações relevantes da página.
Métricas de Desempenho: Coleta dados detalhados de Navigation Timing (TTFB, FCP, LCP, etc.).
Dados do Dispositivo e Ambiente: Coleta informações sobre o dispositivo do usuário, navegador, SO, resolução de tela, idioma, etc.
Rastreamento de Interação:
- Rastreamento automático de cliques em elementos interativos comuns.
- Rastreamento de interações personalizadas definidas via atributos HTML.
Rastreamento de Erros JavaScript: Captura e reporta erros de JS e rejeições de promessas não tratadas.
Rastreamento de Abandono de Formulário: Identifica formulários que os usuários começam a preencher, mas não enviam.
Rastreamento de Eventos Personalizados: API para enviar dados de eventos personalizados.
Agrupamento de Conteúdo: Agrupe dados analíticos por seções de conteúdo em seu site.
Suporte a Não Rastrear (DNT): Respeita a configuração DNT do navegador.
Detecção de Bots: Filtra o tráfego de bots conhecidos (configurável).
Configuração Flexível: As opções podem ser definidas via objeto JavaScript ou parâmetros de URL.
Opções de Armazenamento: Usa cookies por padrão, com fallback para localStorage para IDs e consentimento. Dados de sessão usam sessionStorage com fallbacks para localStorage/memória.
Modo de Depuração: Fornece logs no console para desenvolvimento e solução de problemas.

Começando

Instalação

Inclua o script de analytics no seu arquivo HTML. Geralmente, é recomendado colocá-lo antes da tag de fechamento </body>. Você também pode usar defer se o colocar no <head>.

<script defer src="https://cdn.alphasystem.dev/plugins/easy-analytics-system/latest/script-min.js"></script>

Configuração

Uma chave de API (API key) é obrigatória para o funcionamento do sistema de analytics. Você também precisa especificar o serverEndpoint para onde os dados serão enviados. A configuração pode ser fornecida de várias maneiras:

1. Objeto Global `window.analyticsConfig` (Recomendado)

Antes que o script EAS seja carregado, defina um objeto global window.analyticsConfig:

<script>
  window.analyticsConfig = {
    apiKey: "SUA_CHAVE_DE_API",
    serverEndpoint: "https://seu-servidor-analytics.com/api/track",
    // ... outras opções de configuração
  };
</script>

<script defer src="https://cdn.alphasystem.dev/plugins/easy-analytics-system/latest/script-min.js"></script>

2. Nome do Arquivo do Script

Se o seu arquivo de script for nomeado com a sua chave de API (por exemplo, SUA_CHAVE_DE_API.js), a biblioteca tentará usar o nome do arquivo (sem .js) como a chave de API. Este método é menos comum e principalmente útil se você não puder definir window.analyticsConfig ou parâmetros de URL.

<!-- Assume que o script está hospedado em um local onde seu nome é a chave de API -->
<script src="https://cdn.example.com/SUA_CHAVE_DE_API.js" defer></script>

Observação: serverEndpoint e outras configurações ainda seriam idealmente definidas via window.analyticsConfig ou parâmetros de URL se este método for usado apenas para a chave de API.

3. Parâmetros de Consulta da URL

Você pode passar opções de configuração como parâmetros de consulta na URL do script. Isso substitui as opções de window.analyticsConfig e o método do nome do arquivo do script para a chave de API.

<script src="caminho/para/eas-analytics.js?apiKey=SUA_CHAVE_DE_API&serverEndpoint=https://seu-servidor-analytics.com/api/track&debug=true" defer></script>

Valores booleanos são definidos por true ou 1.
Valores numéricos são analisados correspondentemente.

Prioridade de Configuração:

Parâmetros de Consulta da URL
Objeto window.analyticsConfig
Nome do Arquivo do Script (apenas para apiKey)
Valores padrão

Opções de Configuração

A tabela a seguir detalha todas as opções de configuração disponíveis, seus valores padrão, tipos e descrições:

Opção	Tipo	Valor Padrão	Descrição
`apiKey`	String	`null`	Obrigatório. Sua chave de API exclusiva para o serviço de analytics.
`serverEndpoint`	String	`"#"`	Obrigatório. O endpoint da URL para onde os dados de analytics serão enviados.
`cookieVisitorIdName`	String	`"_ana_vid"`	Nome do cookie ou chave do localStorage usado para armazenar o ID do visitante.
`cookieSessionIdName`	String	`"_ana_sid"`	Nome da chave do sessionStorage/localStorage usado para armazenar o ID da sessão.
`cookieConsentName`	String	`"_ana_consent"`	Nome do cookie ou chave do localStorage usado para armazenar o status de consentimento do usuário.
`cookieExpirationDays`	Number	`365`	Período de expiração em dias para os cookies de ID do visitante e consentimento.
`sessionTimeoutMs`	Number	`1800000` (30 minutos)	Duração da inatividade em milissegundos após a qual uma sessão é considerada expirada e um novo ID de sessão é gerado.
`showConsentModal`	Boolean	`true`	Se `true`, um modal de consentimento é exibido para usuários que não deram ou negaram consentimento.
`consentModalTitle`	String	`"Privacidade e Uso de Dados"`	Texto do título para o modal de consentimento.
`consentModalText`	String	`"Usamos cookies e coletamos dados analíticos para melhorar nosso serviço. Ao clicar em \"Aceitar\", você concorda com nossas práticas..."`	Texto principal do conteúdo para o modal de consentimento.
`privacyPolicyUrl`	String	`"#"`	URL para sua política de privacidade. Se definida para uma URL válida (não `"#"`), um link será adicionado ao modal de consentimento.
`acceptButtonText`	String	`"Aceitar"`	Texto para o botão "Aceitar" no modal de consentimento.
`declineButtonText`	String	`"Recusar"`	Texto para o botão "Recusar" no modal de consentimento.
`gatherPerformance`	Boolean	`true`	Se `true`, coleta métricas de desempenho da página (Navigation Timing API).
`gatherNetworkInfo`	Boolean	`true`	Se `true`, coleta informações de rede (tipo efetivo, RTT, downlink) se disponível via `navigator.connection`.
`gatherInteractionDetails`	Boolean	`true`	Se `true`, rastreia automaticamente cliques em elementos interativos comuns como `<a>`, `<button>`, etc.
`gatherDeviceDetails`	Boolean	`true`	Se `true`, coleta detalhes sobre o dispositivo do usuário (SO, navegador, resolução de tela, etc.).
`gatherPageDetails`	Boolean	`true`	Se `true`, coleta detalhes sobre a página atual (URL, título, referenciador).
`trackJSErrors`	Boolean	`true`	Se `true`, captura e envia erros de JavaScript (`window.onerror`) e rejeições de promessas não tratadas.
`trackDeclaredInteractions`	Boolean	`true`	Se `true`, rastreia interações em elementos com atributos `data-analytics-*` específicos. Veja Interações Declaradas.
`interactionAttributePrefix`	String	`"data-analytics-"`	Prefixo para atributos HTML usados em interações declaradas (por exemplo, `data-analytics-event`).
`trackFormAbandonment`	Boolean	`true`	Se `true`, rastreia formulários com os quais os usuários interagem, mas não enviam.
`formAbandonmentTimeoutMs`	Number	`120000` (2 minutos)	Timeout em milissegundos após a primeira interação com um formulário, após o qual é considerado abandonado se não enviado.
`formSelector`	String	`"form"`	Seletor CSS para identificar formulários para rastreamento de abandono.
`contentGroupingAttribute`	String	`"data-analytics-content-group"`	Nome do atributo HTML usado para definir grupos de conteúdo. Veja Agrupamento de Conteúdo.
`respectDNT`	Boolean	`true`	Se `true`, respeita o sinal "Do Not Track" do navegador e evita o envio de dados (exceto para atualizações de consentimento ou relatórios de erro JS forçados).
`trackBotsViaUA`	Boolean	`true`	Se `true`, tenta identificar bots via strings de User-Agent e pode interromper o rastreamento. Se `false`, o tráfego de bots pode ser rastreado.
`debug`	Boolean	`false`	Se `true`, habilita logs detalhados no console do navegador para fins de depuração.
`useCookies`	Boolean	`true`	Se `true`, usa cookies para armazenar ID do visitante e consentimento. Se `false`, usa `localStorage`.
`enableLocalStorageFallback`	Boolean	`true`	Se o `sessionStorage` não estiver disponível (por exemplo, devido às configurações do navegador), definir isso como `true` permite usar o `localStorage` como fallback para dados de sessão. Se ambos falharem, os dados da sessão são armazenados na memória.

Conceitos Fundamentais

Rastreamento de Visitantes e Sessões

ID do Visitante (client_id): Um UUID exclusivo gerado para cada visitante. É armazenado em um cookie (padrão _ana_vid) ou localStorage (se useCookies for false) e persiste por cookieExpirationDays.
ID da Sessão (session_id): Um UUID exclusivo gerado para cada sessão do usuário. Uma sessão começa quando um usuário visita o site pela primeira vez ou após um período de inatividade (sessionTimeoutMs). Os dados da sessão são armazenados no sessionStorage por padrão (chave _ana_sid), com fallbacks para localStorage ou armazenamento em memória, se necessário. A sessão é mantida ativa pela atividade do usuário.

Gerenciamento de Consentimento

O EAS inclui um sistema robusto de gerenciamento de consentimento:

Status do Consentimento: Pode ser given (concedido), denied (negado) ou not_set (não definido).
Armazenamento: O status do consentimento é armazenado em um cookie (padrão _ana_consent) ou localStorage (se useCookies for false).
Modal de Consentimento: Se showConsentModal for true e o consentimento for not_set, um diálogo modal (renderizado em um Shadow DOM para isolamento de estilo) é exibido, permitindo que os usuários aceitem ou recusem o rastreamento.
- A aparência e o texto do modal são configuráveis (veja consentModalTitle, consentModalText, etc.).
- Um link para sua política de privacidade (privacyPolicyUrl) pode ser incluído.
Comportamento baseado no Consentimento:
- given: Capacidades completas de rastreamento são habilitadas.
- denied: O rastreamento é significativamente limitado. A maioria da coleta de dados é desabilitada. O ID do visitante é removido do localStorage se useCookies for false. Erros de JS ainda podem ser reportados com contexto mínimo se trackJSErrors for verdadeiro.
- not_set: Se o modal for exibido, a inicialização completa aguarda a escolha do usuário. Se o modal estiver desabilitado, o rastreamento é limitado de forma semelhante a denied.
Atualizando o Consentimento: Se um usuário alterar seu status de consentimento, um evento (consent_update) é enviado.

Coleta e Envio de Dados

A função interna collectData() monta o payload de dados para cada evento.
Os dados são enviados para o serverEndpoint usando navigator.sendBeacon() para eventos de descarga de página (para confiabilidade) ou fetch() para outros eventos.
Os payloads são objetos JSON.

Mecanismos de Armazenamento

O EAS usa o armazenamento do navegador para diversos propósitos:

ID do Visitante:
- Cookie: config.cookieVisitorIdName (padrão: _ana_vid) se config.useCookies for true.
- localStorage: Mesma chave, se config.useCookies for false.
Status do Consentimento:
- Cookie: config.cookieConsentName (padrão: _ana_consent) se config.useCookies for true.
- localStorage: Mesma chave, se config.useCookies for false.
ID e Dados da Sessão:
- sessionStorage: Preferencial. Chaves: config.cookieSessionIdName (padrão: _ana_sid) e ${config.cookieSessionIdName}_stime.
- localStorage: Fallback se o sessionStorage não estiver disponível e config.enableLocalStorageFallback for true.
- Em memória: Último recurso se tanto sessionStorage quanto localStorage não estiverem disponíveis. Os dados da sessão serão perdidos quando a página for fechada ou recarregada.

Os cookies são definidos com os atributos SameSite=Lax e Secure.

Capacidades de Rastreamento

Rastreamento Automático

Uma vez inicializado e com o consentimento concedido (se necessário), o EAS rastreia automaticamente vários tipos de dados:

Visualizações de Página

Tipo de Evento: pageview
Acionado no carregamento da página.
Dados Coletados:
- URL, caminho, hostname, referenciador, título do documento (gatherPageDetails).
- Métricas de desempenho (gatherPerformance).
- Informações do dispositivo, navegador, SO (gatherDeviceDetails).
- Informações de rede (gatherNetworkInfo).
- ID do visitante, ID da sessão, timestamps.

Métricas de Desempenho

Coletadas se gatherPerformance for true.
Usa performance.getEntriesByType("navigation")[0] ou fallback para performance.timing.
Métricas Incluem: Tempo de busca de DNS, tempo de conexão TCP, tempo de TLS, tempo de requisição, tempo de resposta, tempo de DOM interativo, tempo de DOM content loaded, tempo de carregamento da página, TTFB (Time to First Byte), contagem de redirecionamentos, tamanhos de transferência.

Informações do Dispositivo, Navegador e SO

Coletadas se gatherDeviceDetails for true.
Detalhes Incluem: String do User-Agent, idioma, resolução de tela, tamanho da viewport, profundidade de cor, offset do fuso horário, tipo de dispositivo (desktop, tablet, mobile), nome e versão do navegador, sistema operacional.

Informações de Rede

Coletadas se gatherNetworkInfo for true e navigator.connection estiver disponível.
Detalhes Incluem: Tipo de conexão efetiva (por exemplo, '4g'), RTT (Round Trip Time), velocidade de downlink, preferência de economia de dados.

Interações do Usuário (Cliques)

Coletadas se gatherInteractionDetails for true.
Tipo de Evento: click (padrão, pode ser sobrescrito por interações declaradas)
Rastreia automaticamente cliques em:
- Tags <a> (âncora)
- Elementos <button>
- Elementos com role="button"
- <input type="submit"> ou <input type="button">
Dados Coletados: Tipo de elemento, ID, classes, conteúdo de texto (primeiros 100 caracteres), URL do link (para tags <a>), coordenadas do clique, URL de destino.

Interações Declaradas

Coletadas se trackDeclaredInteractions for true.
Permite rastrear interações específicas adicionando atributos HTML aos elementos.
Usa atributos prefixados com config.interactionAttributePrefix (padrão data-analytics-).
Atributo Obrigatório: data-analytics-event="seu_nome_de_evento": Define o tipo de evento.
Atributos Opcionais: Quaisquer outros atributos data-analytics-* serão coletados como pares chave-valor em event_data. Por exemplo, data-analytics-category="CTA" torna-se event_data: { category: "CTA" }.
Exemplo:
```
<button data-analytics-event="video_play" data-analytics-video-id="123" data-analytics-source="homepage">Play Video</button>
```
Isso enviaria um evento com event_type: "video_play" e event_data: { video_id: "123", source: "homepage", element_type: "button", ... }.

Erros de JavaScript

Coletados se trackJSErrors for true.
Tipo de Evento: js_error
Escuta por window.onerror e window.onunhandledrejection.
Dados Coletados: Mensagem de erro, URL de origem, número da linha, número da coluna, stack trace (se disponível), tipo de erro (onerror ou unhandledrejection).
Erros de JS são enviados com alta prioridade. O payload incluirá session_id apenas se o consentimento tiver sido concedido, mas o relatório de erro em si é sempre tentado se trackJSErrors estiver habilitado.

Abandono de Formulário

Coletado se trackFormAbandonment for true.
Tipo de Evento: form_abandonment
Rastreia interações do usuário (foco, entrada) com formulários que correspondem a config.formSelector (padrão "form").
Se um usuário interage com um formulário, mas não o envia dentro de config.formAbandonmentTimeoutMs (padrão 2 minutos), um evento de abandono é enviado.
Dados Coletados: Identificador do formulário (ID, nome ou caminho CSS), tempo gasto antes do abandono, ação do formulário, método do formulário.

Descarga de Página e Mudanças de Visibilidade

Tipo de Evento: page_unload
- Enviado quando o usuário navega para fora da página ou fecha a aba/navegador.
- Inclui duration_ms (tempo gasto na página).
Tipo de Evento: visibility_change
- Enviado quando a visibilidade da página muda para hidden.
- Inclui duration_ms (tempo gasto na página até ficar oculta) e time_since_last_activity_ms.

Rastreamento Manual

Eventos Personalizados (`window.customAnalyticsTrack`)

Você pode rastrear manualmente eventos personalizados usando a função global window.customAnalyticsTrack. Esta função está disponível após o carregamento do script EAS.

window.customAnalyticsTrack(eventName, eventDetails, targetElement);

eventName (String, obrigatório): O nome para seu evento personalizado (por exemplo, "inscricao_newsletter", "produto_adicionado_carrinho").
eventDetails (Objeto, opcional): Um objeto contendo quaisquer dados adicionais que você queira associar a este evento. Padrão é {}.
targetElement (Elemento DOM, opcional): O elemento DOM associado a este evento. Se fornecido, seu grupo de conteúdo (se houver) será incluído. Padrão é document.body.

Exemplo:

// Supondo um botão com id="subscribeBtn"
document.getElementById("subscribeBtn").addEventListener("click", () => {
  window.customAnalyticsTrack(
    "inscricao_newsletter",
    {
      origem: "promo_rodape",
      email_usuario_fornecido: true, // Exemplo de detalhe personalizado
    },
    document.getElementById("subscribeBtn")
  );
});

Observação: Eventos personalizados só serão enviados se o sistema de analytics estiver totalmente inicializado e o consentimento tiver sido concedido (se aplicável).

Agrupamento de Conteúdo

O agrupamento de conteúdo permite categorizar dados analíticos com base em seções do seu site.

Habilite definindo o config.contentGroupingAttribute (padrão "data-analytics-content-group") em elementos HTML.
Quando um evento ocorre (por exemplo, visualização de página, clique, evento personalizado), o script procura por este atributo no elemento alvo ou em seus elementos pais.
O valor do atributo é enviado como content_group no payload de dados.