Antes de começar
Esta documentação descreve a versão local implementada, não comprova um serviço hospedado em produção. Comece com uma instalação de homologação aprovada. Acesso ao provedor, entrega pelo remetente, comportamento do navegador e persistência da implantação ainda precisam de verificação.
Crie uma conta e um projeto e configure a origem exata do site, incluindo protocolo e porta quando aplicável. O ID público do projeto direciona solicitações de coleta; não é um segredo nem uma credencial de receita. A política de segurança de conteúdo do seu site deve permitir o host de análise escolhido.
1. Carregue o rastreador
Substitua os dois marcadores pelo host aprovado e pelo ID público do projeto. Apenas carregar o script não envia uma visualização de página.
<script src="https://YOUR-ANALYTICS-HOST/tracker.js"
data-project="PUBLIC_PROJECT_ID"></script>2. Conecte sua decisão de consentimento
Chame estes métodos pelo seu gerenciador de consentimento após o carregamento do script. Não conceda permissão apenas porque este exemplo contém consent(true). Envie somente os nomes de eventos realmente necessários; não coloque endereços de e-mail, tokens ou outros detalhes sensíveis em nomes de eventos ou valores de campanhas.
- Antes do consentimento, track() retorna consent_required sem enviar um evento.
- O ID do visitante é limitado à sessão e armazenado somente após o consentimento. A retirada do consentimento remove esse ID armazenado.
- Configure uma origem permitida exata; IDs públicos e verificações de origem do navegador não formam um sistema completo contra abusos.
// After the visitor grants the relevant permission:
reylin.consent(true);
await reylin.track('pageview');
// A deliberate application event:
await reylin.track('signup');
// When permission is withdrawn:
reylin.consent(false);Opcional: visualizações de páginas com consentimento em um aplicativo de página única
Escolha visualizações manuais OU esta política automática de rotas; não envie ambas para a mesma visita. As visualizações automáticas ficam desativadas até que você configure um mapeamento explícito. Caminhos exatos e prefixos terminados em /* são mapeados para rótulos estáticos não pessoais; nunca coloque identificadores de clientes nesses rótulos. Strings de consulta e fragmentos comuns não se tornam rótulos de página. A atribuição categórica existente de utm_source não muda.
A configuração pode ocorrer antes do consentimento, mas nenhum interceptador de navegação, identificador ou evento é criado até a permissão ser concedida. Uma nova concessão registra somente a página atual mapeada, nunca o histórico negado. GPC=true bloqueia concessões e coleta; a verificação ocorre em operações do rastreador e na navegação, não por um evento de mudança de navegador inventado. A retirada da permissão interrompe os interceptadores e cancela solicitações pendentes quando há suporte; eventos já entregues não podem ser desfeitos.
- pushState, replaceState e voltar/avançar são suportados; roteadores hash também observam hashchange. Notificações duplicadas e mudanças apenas na consulta não adicionam eventos automáticos.
- Caminhos concretos diferentes podem mapear para um único rótulo estático e ainda contar como eventos de navegação separados. Caminhos sem mapeamento não são enviados.
- initial:false ignora a página atual a cada instalação ou concessão; mudanças posteriores para rotas mapeadas são coletadas. Não há novas tentativas automáticas nem reprodução de eventos offline.
- Os métodos do roteador mantêm seus valores de retorno, argumentos e exceções nativos. A interrupção restaura apenas os wrappers do rastreador, preservando wrappers instalados depois por outro código. Ainda é necessária validação real no framework e no navegador.
// Configure once after the script loads; this does NOT grant consent.
reylin.startPageviews({
mode: 'history', // use 'hash' for #/pricing-style routers
routes: {'/':'/', '/pricing':'/pricing', '/docs/*':'/docs'},
initial: true
});
// Later, only after the visitor permits collection:
reylin.consent(true);
// Stop automatic navigation only (does not withdraw consent):
reylin.stopPageviews();
// Withdraw all tracking consent:
reylin.consent(false);3. Associe um pagamento único no seu servidor
O exemplo abaixo mostra uma estrutura de servidor, não um endpoint de checkout completo. Obtenha a associação consentida do visitante pelo fluxo validado do seu aplicativo. Mantenha a seleção de preços, as credenciais e a propriedade do projeto sob controle do servidor. Omita a associação quando ela não estiver disponível; não invente uma.
- Os metadados de Session e de PaymentIntent são distintos.
- Não envie chaves secretas ou restritas do Stripe ao navegador.
- Renovações de assinaturas exigem uma associação persistente de cliente separada; este exemplo de pagamento único não a implementa.
const metadata = consentedVisitorId
? { analytics_visitor_id: consentedVisitorId }
: {};
const session = await stripe.checkout.sessions.create({
mode: 'payment',
line_items: trustedLineItems,
success_url: trustedSuccessUrl,
cancel_url: trustedCancelUrl,
payment_intent_data: { metadata }
});4. Conecte a conta de receita correspondente
Esta conexão mede os pagamentos dos seus clientes; ela é separada do pagamento por este serviço de análise. Em Connections, escolha o projeto do qual você é proprietário, a conta correspondente em modo de teste e a chave de leitura restrita. A identidade da conta é verificada antes de armazenar um rascunho criptografado. O rascunho fornece uma URL estável de endpoint de webhook, mas rejeita entregas até ser ativado.
É necessário acesso de leitura à conta, aos PaymentIntents e aos reembolsos; a importação limitada opcional também precisa de acesso a Events. Use a URL do rascunho para configurar um endpoint de webhook na sua própria conta Stripe para payment_intent.succeeded, refund.created, refund.updated e refund.failed. Depois, informe o segredo de assinatura desse endpoint no formulário de ativação do rascunho. Conta, projeto, modo e URL existentes permanecem inalterados; somente a ativação habilita as entregas.
A configuração de produção é deliberadamente separada e exige ativação explícita no servidor, HTTPS e cookies Secure. Conexões de teste e produção não podem compartilhar um projeto. Uma conexão configurada não comprova uma entrega bem-sucedida.
5. Verifique toda a jornada
- Com o consentimento concedido, envie um evento de teste da origem permitida e examine a visualização Events do projeto.
- Crie um pagamento de teste correspondente. Confira fonte, moeda e recebimentos brutos, não a demonstração sintética.
- Teste um reembolso parcial, uma entrega repetida e um pagamento sem associação de visitante.
- Retire o consentimento e confirme que nenhum novo evento do navegador é enviado.
- Confira os avisos de conciliação pendente e não considere a configuração concluída até verificar a entrega real pelo provedor e o comportamento do navegador.
Conheça os limites atuais
As franquias mensais de eventos se aplicam aos projetos do proprietário da cobrança. Ao atingir o limite, a nova coleta pausa sem inventar dados nem cobrar excedentes automaticamente. A conciliação financeira e os relatórios existentes continuam disponíveis.
A importação opcional dos últimos 7 ou 30 dias cobre somente eventos disponíveis de pagamentos bem-sucedidos. Ela não reconstrói o histórico de visitantes nem todos os reembolsos históricos; relatórios importados exibem um aviso de histórico parcial. Funis ordenados de várias etapas estão implementados. A importação e os relatórios do Search Console exigem uma conexão de provedor autorizada separadamente; esta prévia pública não tem provedores conectados. Identidade entre dispositivos e substituição de sistemas contábeis não estão disponíveis.
Referências
Esta documentação descreve o código e seus limites; não confirma uma conexão ativa. Os exemplos técnicos mantêm os identificadores originais.