SDK web (navegador)

@traqio/web es el SDK de Traqio para sitios y aplicaciones web. Cuando un visitante llega desde un enlace de seguimiento de Traqio, la URL de llegada lleva el click id del anuncio — el trackID — en traq_click. El SDK lo lee, lo guarda en almacenamiento first-party (localStorage, más una cookie en tu propio dominio) y lo devuelve cuando el visitante convierte, para que la conversión se vincule a su clic de forma determinista, no adivinada. También registra eventos y visitas web, con consentimiento y borrado. Sin fingerprinting, sin cookies de terceros, sin identificador publicitario; unos 7 KB con gzip, un solo paquete para React, Vue, Angular y HTML simple.

Requisitos#

• Cualquier navegador actualizado (el SDK usa fetch y localStorage).
• Una clave web para el sitio. La clave de una app móvil se rechaza aquí, y al revés.
• Enlaces que lleguen a tu sitio: un enlace de seguimiento cuyo destino sea una página del sitio, para que el trackID llegue en la URL.

Configuración#

1. Crear una clave web#

   En la consola, abre Integraciones → SDK del sitio y crea una clave web. Indica cada origen que ejecuta el SDK — esquema y host, sin ruta: https://example.com, https://www.example.com, https://app.example.com. No hay comodín. Una petición desde cualquier otro origen, o sin cabecera Origin (curl, un servidor), se rechaza con un 403.

2. Instalar el paquete#

   npm install @traqio/web

   O, sin paso de build, una etiqueta en cada página — se inicializa sola y expone window.Traqio:

   <script src="https://cdn.jsdelivr.net/npm/@traqio/web@0.1/build/traqio.min.js"
           data-sdk-key="YOUR_WEB_KEY" async></script>

3. Inicializar en cada página#

   React / Next.jsVue / NuxtAngularJavaScript

   // app/traqio.tsx — mounted once, in the root layout
   "use client";
   import { useEffect } from "react";
   import { Traqio } from "@traqio/web";
   
   export function TraqioInit(): null {
     useEffect(() => {
       void Traqio.init({ sdkKey: process.env.NEXT_PUBLIC_TRAQIO_WEB_KEY! });
     }, []);
     return null;
   }

   Una vez, lo antes posible. init lee el trackID de la URL actual antes que nada, así que un visitante que se va enseguida lo conserva. Es seguro con renderizado en el servidor: en un servidor no hace nada.

4. Guardar el trackID con el usuario#

   La conversión que cuenta — un registro, una suscripción, una compra — suele ocurrir en tu backend, donde se conoce el id de usuario. El SDK escribe la cookie traq_click en tu dominio registrable (example.com), así que tu backend la recibe con la propia petición de registro:

   // Node / Express — the browser sends the cookie with the sign-up request itself
   app.post("/signup", async (req, res) => {
     const trackId = req.cookies.traq_click ?? req.body.traq_click ?? null;
     const user = await users.create({ email: req.body.email, traqClick: trackId });
     // …
   });

   Si tu backend está en otro dominio, envíalo explícitamente — Traqio.getTrackId() lo devuelve, o null cuando el visitante no viene de un anuncio:

   <form id="signup" action="/signup" method="post">
     <input type="hidden" name="traq_click" />
     …
   </form>
   <script>
     // Filled at submit time, so it works whenever the SDK finished loading.
     document.getElementById("signup").addEventListener("submit", (e) => {
       e.target.elements.traq_click.value = window.Traqio?.getTrackId() ?? "";
     });
   </script>

   Después, tu backend reporta el registro con el trackID mediante un SDK de servidor — Node.js, PHP / Laravel o Python — que lo vincula al clic.

5. Registrar eventos y el id de usuario#

   Traqio.setUserId(user.id); // after sign-in
   
   Traqio.track("signup");
   Traqio.track("purchase", { value: 49, currency: "EUR", transactionId: payment.id, store: "stripe" });

   Los eventos se agrupan, se reintentan, se conservan entre páginas y se envían cuando la pestaña se oculta o se abandona la página. Un evento registrado es una conversión: registra los pasos que importan, no cada página vista.

Qué hace hoy y qué no#

El SDK de navegador nunca envía el trackID por sí mismo. Una clave que cualquiera puede leer en tu página no debe poder acreditar una campaña: el vínculo entre una conversión y su clic lo hace tu backend, con una clave de servidor secreta, mediante un SDK de servidor. Los eventos que envía el propio navegador se registran sin campaña, y todavía ningún evento web se envía a las redes publicitarias.

Consentimiento#

Traqio.init({ sdkKey: "YOUR_WEB_KEY", waitForConsent: true });

// when your consent banner gets an answer
consentBanner.onAnswer((granted) => Traqio.setConsent(granted));

Con waitForConsent, no se escribe nada en el dispositivo — ni localStorage ni cookies — hasta setConsent(true); el SDK sigue funcionando para la página actual, en memoria. setConsent(true) guarda entonces lo que la página había retenido, trackID incluido; setConsent(false) elimina todo lo que el SDK había guardado. La misma respuesta decide si los datos de este visitante pueden compartirse con las redes publicitarias — ver privacidad.

Referencia de la API#

interface WebInitOptions {
  sdkKey: string;           // the site's web key (tq_web_…)
  endpoint?: string;        // default "https://api.traqio.app"
  userId?: string;          // your user id, once known
  consent?: boolean;        // ad-sharing consent, if already known
  waitForConsent?: boolean; // store nothing until setConsent(true) — default false
  trackIdDays?: number;     // how long the trackID is kept — default 30
  cookies?: boolean;        // false = localStorage only — default true
}

Límites#

• Safari conserva 7 días el almacenamiento escrito por JavaScript en los sitios que clasifica como rastreadores: el trackID puede caducar allí antes de lo que indica trackIdDays.
• Un clic en el navegador integrado de una app seguido de una conversión en otro navegador, sin iniciar sesión, no lleva trackID: esa conversión se muestra sin atribuir, nunca adivinada.

Preguntas frecuentes#

¿Qué es el trackID?

El click id del anuncio en el que hizo clic el visitante. Un enlace de seguimiento de Traqio lo añade a la URL de llegada en el parámetro traq_click; @traqio/web lo lee y lo guarda en almacenamiento first-party (localStorage y una cookie en tu propio dominio), para que la conversión se vincule después a ese clic exacto en lugar de adivinarse.

¿La clave web es un secreto?

No. Está en tu página, así que cualquiera puede leerla. La protege su lista de orígenes permitidos: la API de Traqio solo la acepta desde los orígenes declarados, comprobados en la cabecera Origin que pone el propio navegador. Por ser pública, una clave web no puede atribuir una conversión a un clic: para eso hace falta una clave de servidor secreta, usada por tu backend.

¿@traqio/web funciona con renderizado en el servidor?

Sí. Nada toca window ni document al importar el módulo, e init() no hace nada en un servidor. Llámalo desde código que se ejecute en el navegador: un componente cliente, un plugin .client o un inicializador protegido con isPlatformBrowser.

¿Cuánto tiempo se guarda el trackID?

30 días por defecto (opción trackIdDays). El servidor aplica de todos modos tu ventana de atribución, así que guardarlo más tiempo no tiene efecto. Safari limita a 7 días el almacenamiento escrito por JavaScript en los sitios que clasifica como rastreadores: cuenta con 7 días allí.