7 min de lectura

Añadir Zenovay Analytics a SvelteKit

Esta guía cubre la adición de Zenovay Analytics a una aplicación SvelteKit. El script de seguimiento se carga de forma asíncrona en menos de 1 KB, detecta automáticamente las navegaciones del lado del cliente a través de la History API y respeta el ciclo de vida SSR de SvelteKit para que nunca se ejecute en el servidor donde no existe el objeto window. Temas cubiertos: instalación básica, seguimiento de eventos personalizados, identificación de usuarios y modo sin cookies.

Configuración rápida (2 minutos)

Añada una etiqueta de script a su archivo HTML raíz de SvelteKit. Sin paquetes npm, sin plugins de Vite, sin cambios en el adaptador.

Paso 1: Obtenga su código de seguimiento

Inicie sesión en su panel de Zenovay, abra Dominios, haga clic en su sitio y copie el fragmento de la tarjeta Script de seguimiento en la página de configuración General.

Paso 2: Añadir a app.html

Abra src/app.html, la plantilla HTML raíz para todas las páginas de SvelteKit, y añada el script de 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>

¡Listo! Zenovay rastreará automáticamente las páginas vistas en todas sus rutas de SvelteKit, incluidas las navegaciones del lado del cliente.

La tarjeta de script de seguimiento mostrando el fragmento de script con pestañas HTML, React, Next.js y First-Party, y un botón Verificar instalación — Copie su código de seguimiento desde Dominios → su sitio → General → Script de seguimiento.

Paso 3: Verificar la instalación

Visite su sitio y compruebe el panel de Zenovay. Debería ver un visitante en tiempo real aparecer en cuestión de segundos.

Reemplace YOUR_TRACKING_CODE con su código de seguimiento real. Encuéntrelo bajo Dominios → su sitio → General → Script de seguimiento.

Seguimiento de navegación en SPA

SvelteKit utiliza enrutamiento del lado del cliente por defecto. Zenovay detecta automáticamente los cambios de ruta a través de la History API (pushState / popstate), por lo que cada navegación registra una nueva página vista sin ninguna configuración adicional.

Esto funciona con todos los métodos de navegación de SvelteKit:

Enlaces con etiqueta <a> (SvelteKit los intercepta)
Navegación programática con goto()
Botones de avance/retroceso del navegador
Funciones de $app/navigation

Eventos personalizados

Rastree interacciones del usuario mediante la función global window.zenovay. Proteja siempre con una comprobación typeof window o browser para evitar errores de SSR.

Uso del guard `browser`

SvelteKit proporciona una constante browser que es true solo en el 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>

Módulo de seguimiento reutilizable

Cree un módulo utilitario para llamadas de seguimiento limpias y reutilizables:

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);
}
}

A continuación, úselo en cualquier 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>

Seguimiento de páginas vistas en el layout

Si desea enviar metadatos adicionales con cada página vista, utilice una declaración reactiva en su layout raíz:

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 />

Lo anterior es opcional. Zenovay ya rastrea las páginas vistas automáticamente. Utilice este patrón solo si necesita adjuntar metadatos adicionales a cada navegación.

Consideraciones sobre el renderizado en servidor

El script de Zenovay se ejecuta completamente en el cliente. Durante el SSR, window no está disponible, por lo que:

Nunca llame a window.zenovay en +page.server.ts, +layout.server.ts o hooks del servidor
Siempre proteja las llamadas del lado del cliente con browser de $app/environment
La etiqueta de script en app.html solo la ejecuta el navegador, por lo que es segura allí

NO haga esto en archivos del 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 sin cookies

Para un seguimiento respetuoso con la privacidad sin cookies ni localStorage, añada el atributo data-cookieless:

Seguimiento sin cookies en src/app.htmlHTML

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

En modo sin cookies, Zenovay utiliza un hash del lado del servidor de la subred IP del visitante, el agente de usuario y una sal rotativa diaria para contar visitantes únicos sin almacenar nada en el dispositivo del cliente.

Identificar usuarios

Asocie los datos de análisis con los usuarios autenticados. Normalmente llame a esto después del inicio de sesión o en un layout que cargue datos del usuario:

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 />

Seguimiento de objetivos e ingresos

src/lib/analytics.ts (objetivos e ingresos)TypeScript

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

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

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

Soporte para TypeScript

Añada declaraciones de tipo para la función 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 {};

Seguimiento de acciones de formularios

Rastree acciones de formularios de SvelteKit (mejora progresiva):

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>

Siguientes pasos

¡Su aplicación SvelteKit ya está rastreando con Zenovay! Vea sus análisis en el panel de control.

Continúe aprendiendo:

Eventos personalizados - Patrones avanzados de seguimiento de eventos
Objetivos - Configure objetivos de conversión
Cumplimiento de privacidad - Configuración del RGPD y CCPA
Frameworks personalizados - Guía de integración genérica