WorkOfNeo/analyticsos-skills

Rastreamento analyticsOS

O analyticsOS registra visualizações de página, cliques, rolagem, formulários, erros, velocidade e usuários logados através de um script por aplicação. Instalá-lo requer duas tags no <head> da página; a maior parte do trabalho consiste em colocá-las no lugar certo para a stack e manter dados pessoais fora.

O que você precisa da pessoa

A página de configuração do analyticsOS fornece um prompt com três valores. Peça qualquer um que estiver faltando; nunca adivinhe.

• Host: onde o analyticsOS é executado, ex. https://analytics.exemplo.com.
• Key: a chave pública da aplicação, prj_…. Não é um segredo: ela aparece em todas as páginas que carregam o script.
• Mode: Identified (aplicações com login, consentimento no acordo) ou Anonymous (sites públicos, nada armazenado no dispositivo).

Instalação

1. Encontre a stack e leia sua referência antes de alterar qualquer coisa:

   • Next.js (App Router ou Pages Router): references/nextjs.md
   • Flask ou outra aplicação Jinja: references/flask.md
   • Webflow: references/webflow.md
   • Qualquer outra coisa (HTML puro, Vite, Astro, SvelteKit, Rails, Django, PHP, WordPress…): references/any-site.md

2. Variáveis de ambiente, não valores fixos: ANALYTICS_HOST e ANALYTICS_KEY, com o prefixo que a build precisar para expô-las à página (NEXT_PUBLIC_ para Next.js, VITE_ para Vite). Coloque-as no .env local, adicione os nomes com valores vazios ao .env.example e diga à pessoa para defini-las nas configurações do host (Railway → Variáveis, Vercel → Variáveis de Ambiente…) para cada ambiente onde o rastreamento deve ser executado.

3. As duas tags, no <head> de cada página, apenas quando a chave estiver definida. Sem chave, nada deve carregar: esse é o interruptor para desligar em desenvolvimento local e previews.

   <script>
     window.aos =
       window.aos ||
       function () {
         ;(window.aos.q = window.aos.q || []).push(arguments)
       }
   </script>
   <script defer src="{ANALYTICS_HOST}/s/{ANALYTICS_KEY}.js"></script>
   

   A primeira tag enfileira chamadas feitas antes do script carregar; a segunda carrega o script com as configurações da aplicação.

4. Usuários logados (apenas modo Identified): veja references/events.md. No modo Anonymous, não adicione chamadas identify e não armazene nada sobre o visitante.

5. Nomeie as seções principais de páginas-chave com data-section="Preços" (hero, preços, formulário de cadastro…) para que os relatórios possam nomeá-las, e coloque data-private em qualquer elemento cujo texto nunca deve ser lido: nomes de clientes, valores, endereços, qualquer coisa pessoal.

6. Content-Security-Policy: se o projeto definir uma, permita o host em script-src e connect-src.

7. Nada mais: não adicione outros analytics, cookies ou banners de consentimento. O analyticsOS não precisa de nenhum deles.

8. Finalização: execute o build e o linter do projeto, liste os arquivos que você alterou e diga à pessoa para abrir a aplicação em um navegador. A página de configuração no analyticsOS marca a primeira visualização de página em segundos.

O que o script já captura

Não escreva código para nenhum destes; eles vêm com o script:

• visualizações de página, incluindo navegações do lado do cliente em aplicações de página única;
• cliques em links, botões e qualquer coisa com data-aos-event, além de links externos, downloads, cliques de raiva e cliques mortos;
• profundidade de rolagem e tempo na página;
• formulários iniciados, enviados e abandonados (nunca o que foi digitado);
• Core Web Vitals (LCP, INP, CLS, FCP, TTFB), erros de JavaScript e requisições de mesma origem com falha.

Eventos personalizados, cliques nomeados e identify estão em references/events.md.

Regras de privacidade

Estas valem em todo projeto, independentemente do que a pessoa pedir:

• Nunca envie um endereço de e-mail, nome, número de telefone ou qualquer coisa que alguém digitou: nem em traits de identify, nem em props de track, nem em nomes de data-aos-event.
• Identifique com o ID de usuário interno da aplicação, nunca o e-mail.
• Marque elementos que mostram dados pessoais com data-private. O script também nunca lê inputs, textareas ou contenteditable.
• Navegadores que enviam Do Not Track ou Global Privacy Control não são rastreados, e chamadas aos() são descartadas. Não ignore isso.

Quando nada chega

Abra a aplicação com a aba de rede do navegador:

• /s/{chave}.js deve carregar (200), então requisições para {host}/api/e respondem com 204.
• 403 do /api/e: o domínio da página não está nos Domínios Permitidos da aplicação (analyticsOS → configurações da aplicação). Adicione-o ou deixe a lista vazia durante os testes.
• 404: a chave está errada ou foi rotacionada há mais de 24 horas.
• Nenhuma requisição: a variável da chave não está definida naquele ambiente, uma Content-Security-Policy bloqueia o host, ou o navegador envia Do Not Track / Global Privacy Control.
• Next.js, eventos param após a primeira página: as tags foram adicionadas como elementos <script> simples em um layout aninhado. Use next/script no layout raiz (veja references/nextjs.md).