7 min de leitura

Adicionar o Zenovay Analytics ao SvelteKit

O Zenovay Analytics integra-se perfeitamente com o SvelteKit, oferecendo insights de visitantes em tempo real sem adicionar nenhuma dependência ao seu projeto. As aplicações SvelteKit vão de sites totalmente estáticos a apps com renderização no servidor com roteamento complexo, e o Zenovay lida com todos esses modos imediatamente. 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. Seja em um site de marketing, um painel SaaS ou uma loja de e-commerce com SvelteKit, este guia cobre tudo, desde a instalação básica até o rastreamento de eventos personalizados, identificação de usuários e modo sem cookies compatível com GDPR. Você estará pronto em cerca de dois minutos.

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 e copie seu código de rastreamento em Settings → Tracking Code.

Passo 2: Adicionar 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 as navegações do lado do cliente.

Passo 3: Verifique sua instalação

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

Substitua YOUR_TRACKING_CODE pelo seu código de rastreamento real do Painel do Zenovay.

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 extra.

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) {
  // O Zenovay rastreia visualizações de página automaticamente, mas você pode adicionar dados personalizados
  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 esse 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 as 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 — isso causará erro!
// window.zenovay('track', 'page_load'); // ❌

// Em vez disso, rastreie no lado do cliente em +page.svelte
// import { browser } from '$app/environment';
// if (browser && window.zenovay) { ... } // ✅

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 o login ou em um layout que carregue os 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';

// Rastrear uma meta de conversão
trackGoal('newsletter_signup', { source: 'footer' });

// Rastrear uma compra
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 as 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 está agora sendo rastreado pelo 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