7 min de leitura

Adicionar o Zenovay Analytics ao SvelteKit

Este guia aborda a adição do Zenovay Analytics a um app SvelteKit. O script de rastreamento carrega de forma assíncrona em menos de 1 KB, detecta automaticamente as navegações do lado do cliente via History API e respeita o ciclo de vida de SSR do SvelteKit para que nunca seja executado no servidor onde não há objeto window. Tópicos abordados: instalação básica, rastreamento de eventos personalizados, identificação de usuários e modo sem cookies.

Configuração rápida (2 minutos)

Adicione uma tag de script ao arquivo HTML raiz do SvelteKit. Sem pacotes npm, sem plugins Vite, sem alterações de adapter.

Passo 1: Obtenha seu código de rastreamento

Acesse o painel do Zenovay, abra Domains, clique em seu site e copie o snippet do card Tracking script na página de configurações General.

Passo 2: Adicione ao app.html

Abra src/app.html, o template HTML raiz de cada página do SvelteKit, e adicione o script do Zenovay dentro de <head>:

src/app.htmlHTML

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <link rel="icon" href="%sveltekit.assets%/favicon.png" />
  <script
    defer
    data-tracking-code="YOUR_TRACKING_CODE"
    src="https://api.zenovay.com/z.js"
  ></script>
  %sveltekit.head%
</head>
<body data-sveltekit-preload-data="hover">
  <div style="display: contents">%sveltekit.body%</div>
</body>
</html>

Pronto! O Zenovay rastreará automaticamente as visualizações de página em todas as suas rotas SvelteKit, incluindo navegações do lado do cliente.

O card Tracking script mostrando o snippet do script com abas HTML, React, Next.js e First-Party e um botão Verify Installation — Copie seu código de rastreamento de Domains → seu site → General → Tracking script.

Passo 3: Verifique a instalação

Visite seu site e verifique o painel do Zenovay. Você deverá ver um visitante em tempo real aparecer dentro de segundos.

Substitua YOUR_TRACKING_CODE pelo seu código de rastreamento real. Encontre-o em Domains → seu site → General → Tracking script.

Rastreamento de navegação SPA

O SvelteKit usa roteamento do lado do cliente por padrão. O Zenovay detecta automaticamente as mudanças de rota via History API (pushState / popstate), de modo que cada navegação registra uma nova visualização de página sem nenhuma configuração adicional.

Funciona com todos os métodos de navegação do SvelteKit:

Links com tags <a> (o SvelteKit intercepta esses)
Navegação programática com goto()
Botões de voltar/avançar do navegador
Funções de $app/navigation

Eventos personalizados

Rastreie interações do usuário usando a função global window.zenovay. Sempre proteja com uma verificação typeof window ou browser para evitar erros no SSR.

Usando a proteção `browser`

O SvelteKit fornece uma constante browser que é true apenas no cliente:

src/lib/components/SignupButton.svelteSVELTE

<script lang="ts">
import { browser } from '$app/environment';

export let plan: string;

function handleClick() {
  if (browser && window.zenovay) {
    window.zenovay('track', 'signup_click', { plan });
  }
}
</script>

<button on:click={handleClick}>
Sign Up for {plan}
</button>

Helper de rastreamento reutilizável

Crie um módulo utilitário para chamadas de rastreamento limpas e reutilizáveis:

src/lib/analytics.tsTypeScript

import { browser } from '$app/environment';

export function track(event: string, data?: Record<string, any>) {
if (browser && window.zenovay) {
  window.zenovay('track', event, data);
}
}

export function identify(userId: string, traits?: Record<string, any>) {
if (browser && window.zenovay) {
  window.zenovay('identify', userId, traits);
}
}

export function trackGoal(goalName: string, data?: Record<string, any>) {
if (browser && window.zenovay) {
  window.zenovay('goal', goalName, data);
}
}

export function trackRevenue(amount: number, currency = 'USD') {
if (browser && window.zenovay) {
  window.zenovay('revenue', amount, currency);
}
}

Depois use em qualquer componente:

src/routes/pricing/+page.svelteSVELTE

<script lang="ts">
import { track } from '$lib/analytics';

function handleUpgrade(plan: string) {
  track('upgrade_clicked', { plan, location: 'pricing_page' });
}
</script>

<button on:click={() => handleUpgrade('pro')}>
Upgrade to Pro
</button>

Rastrear visualizações de página no layout

Se quiser disparar metadados adicionais com cada visualização de página, use uma instrução reativa no seu layout raiz:

src/routes/+layout.svelteSVELTE

<script lang="ts">
import { page } from '$app/stores';
import { browser } from '$app/environment';

$: if (browser && $page.url) {
  // Zenovay auto-tracks page views, but you can add custom data
  if (window.zenovay) {
    window.zenovay('track', 'page_metadata', {
      path: $page.url.pathname,
      route_id: $page.route.id,
    });
  }
}
</script>

<slot />

O código acima é opcional. O Zenovay já rastreia visualizações de página automaticamente. Use este padrão apenas se precisar anexar metadados extras a cada navegação.

Considerações sobre renderização no servidor

O script do Zenovay é executado inteiramente no cliente. Durante o SSR, window não está disponível, portanto:

Nunca chame window.zenovay em +page.server.ts, +layout.server.ts ou hooks de servidor
Sempre proteja chamadas do lado do cliente com browser de $app/environment
A tag de script em app.html é executada apenas pelo navegador, portanto é segura ali

NÃO faça isso em arquivos de servidorTypeScript

// +page.server.ts — this will throw!
// window.zenovay('track', 'page_load'); // DO NOT do this

// Instead, track on the client side in +page.svelte
// import { browser } from '$app/environment';
// if (browser && window.zenovay) { ... } // correct

Modo sem cookies

Para rastreamento respeitoso à privacidade sem cookies ou localStorage, adicione o atributo data-cookieless:

Rastreamento sem cookies em src/app.htmlHTML

<script
defer
data-tracking-code="YOUR_TRACKING_CODE"
data-cookieless="true"
src="https://api.zenovay.com/z.js"
></script>

No modo sem cookies, o Zenovay usa um hash no servidor da sub-rede de IP do visitante, do agente de usuário e de um salt rotacionado diariamente para contar visitantes únicos sem armazenar nada no dispositivo do cliente.

Identificar usuários

Associe dados de analytics a usuários autenticados. Normalmente chame isso após login ou em um layout que carregue dados do usuário:

src/routes/+layout.svelte (autenticado)SVELTE

<script lang="ts">
import { browser } from '$app/environment';
import type { LayoutData } from './$types';

export let data: LayoutData;

$: if (browser && data.user && window.zenovay) {
  window.zenovay('identify', data.user.id, {
    email: data.user.email,
    plan: data.user.plan,
  });
}
</script>

<slot />

Rastrear metas e receita

src/lib/analytics.ts (metas e receita)TypeScript

import { trackGoal, trackRevenue } from '$lib/analytics';

// Track a conversion goal
trackGoal('newsletter_signup', { source: 'footer' });

// Track a purchase
trackRevenue(49.99, 'USD');

Suporte a TypeScript

Adicione declarações de tipo para a função global zenovay:

src/app.d.tsTypeScript

// See https://kit.svelte.dev/docs/types#app
declare global {
namespace App {
  // interface Error {}
  // interface Locals {}
  // interface PageData {}
  // interface Platform {}
}

interface Window {
  zenovay?: (...args: any[]) => void;
}
}

export {};

Rastreamento de form actions

Rastreie form actions do SvelteKit (progressive enhancement):

src/routes/contact/+page.svelteSVELTE

<script lang="ts">
import { enhance } from '$app/forms';
import { track } from '$lib/analytics';
</script>

<form
method="POST"
use:enhance={() => {
  track('form_submitted', { form: 'contact' });
  return async ({ result }) => {
    if (result.type === 'success') {
      track('form_success', { form: 'contact' });
    }
  };
}}
>
<input name="email" type="email" placeholder="Email" required />
<textarea name="message" placeholder="Message" required></textarea>
<button type="submit">Send</button>
</form>

Próximos passos

Seu app SvelteKit agora está sendo rastreado com Zenovay! Veja seus dados de analytics no painel.

Continue aprendendo:

Eventos personalizados - Padrões avançados de rastreamento de eventos
Metas - Configurar metas de conversão
Conformidade com privacidade - Configuração GDPR e CCPA
Frameworks personalizados - Guia de integração genérico