7 min de lectura

Añadir Zenovay Analytics a SvelteKit

Zenovay Analytics se integra a la perfección con SvelteKit, proporcionándole estadísticas de visitantes en tiempo real sin añadir ni una sola dependencia a su proyecto. Las aplicaciones SvelteKit van desde sitios completamente estáticos hasta aplicaciones renderizadas en servidor con enrutamiento complejo, y Zenovay gestiona todos estos modos de forma inmediata. 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. Tanto si está desarrollando un sitio de marketing, un panel SaaS o una tienda de comercio electrónico con SvelteKit, esta guía cubre todo, desde la instalación básica hasta el seguimiento de eventos personalizados, la identificación de usuarios y el modo sin cookies compatible con el RGPD. Estará en funcionamiento en unos dos minutos.

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 y copie su código de seguimiento desde Settings → Tracking Code.

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.

Paso 3: Verificar la instalación

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

Reemplace YOUR_TRACKING_CODE con su código de seguimiento real del Panel de Zenovay.

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 rastrea páginas vistas automáticamente, pero puede añadir datos personalizados
  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 — ¡esto lanzará un error!
// window.zenovay('track', 'page_load'); // ❌

// En su lugar, rastree en el lado del cliente en +page.svelte
// import { browser } from '$app/environment';
// if (browser && window.zenovay) { ... } // ✅

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 el 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';

// Rastrear un objetivo de conversión
trackGoal('newsletter_signup', { source: 'footer' });

// Rastrear una compra
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