Web SDK (browser)

@traqio/web is the Traqio SDK for websites and web apps. When a visitor arrives from a Traqio tracking link, the landing URL carries the ad click id — the trackID — as traq_click. The SDK reads it, keeps it in first-party storage (localStorage, plus a cookie on your own domain) and hands it back when the visitor converts, so the conversion can be tied to its click deterministically, not by guesswork. It also records web events and visits, with consent and erasure. No fingerprinting, no third-party cookie, no advertising id; about 7 KB gzipped, one package for React, Vue, Angular and plain HTML.

Requirements#

• Any evergreen browser (the SDK uses fetch and localStorage).
• A web key for the site. The app key of a mobile app is refused here, and the reverse is true.
• Links that land on your site: a tracking link whose destination is a page of the site, so the trackID arrives in the URL.

Set up#

1. Create a web key#

   In the console, open Integrations → SDK for the site and create a web key. List every origin that runs the SDK — scheme and host, no path: https://example.com, https://www.example.com, https://app.example.com. There is no wildcard. A request from any other origin, or with no Origin header at all (curl, a server), is refused with a 403.

2. Install the package#

   npm install @traqio/web

   Or, without a build step, one tag on every page — it initialises itself and exposes 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. Initialise on every page#

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

   Once, as early as possible. init reads the trackID from the current URL before anything else, so a visitor who leaves at once still keeps it. It is safe during server-side rendering: on a server it does nothing.

4. Keep the trackID with the user#

   The conversion that counts — a sign-up, a subscription, a purchase — usually happens on your backend, where the user id is known. The SDK writes the cookie traq_click on your registrable domain (example.com), so your backend receives it with the sign-up request itself:

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

   If your backend is on another domain, send it explicitly — Traqio.getTrackId() returns it, or null when the visitor did not come from an ad:

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

   Your backend then reports the sign-up with the trackID through a server SDK — Node.js, PHP / Laravel or Python — which ties it to the click.

5. Track events and set the user id#

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

   Events are batched, retried, kept across page loads, and sent when the tab is hidden or the page is left. A tracked event is a conversion: track the steps that matter, not every page view.

What it does today, and what it does not#

The browser SDK never sends the trackID itself. A key anyone can read in your page must not be able to credit a campaign, so the tie between a conversion and its click is made by your backend, with a secret server key, through a server SDK. Events the browser sends itself are recorded without a campaign, and no web event is forwarded to ad networks yet.

Consent#

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

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

With waitForConsent, nothing is written to the device — no localStorage, no cookie — until setConsent(true); the SDK still works for the current page, in memory. setConsent(true) then stores what the page kept, trackID included; setConsent(false) removes everything the SDK stored. The same answer governs whether data about this visitor may be shared with ad networks — see privacy.

API reference#

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
}

Limits#

• Safari keeps storage written by JavaScript for 7 days on sites it classifies as tracking: the trackID can expire sooner there than trackIdDays says.
• A click in an app's in-app browser followed by a conversion in another browser, without signing in, carries no trackID: that conversion is shown as unattributed, never guessed.

Frequently asked questions#

What is the trackID?

The click id of the ad the visitor clicked. A Traqio tracking link adds it to the landing URL as the traq_click parameter; @traqio/web reads it and keeps it in first-party storage (localStorage and a cookie on your own domain), so the conversion can later be tied to that exact click instead of being guessed.

Is the web key a secret?

No. It sits in your page, so anyone can read it. It is protected by its list of allowed origins: the Traqio API accepts it only from the origins you declared, checked on the Origin header the browser sets itself. Because it is public, a web key cannot attribute a conversion to a click — that takes a secret server key, used by your backend.

Does @traqio/web work with server-side rendering?

Yes. Nothing touches window or document when the module is imported, and init() does nothing on a server. Call it from code that runs in the browser: a client component, a .client plugin, or an initializer guarded by isPlatformBrowser.

How long is the trackID kept?

30 days by default (the trackIdDays option). The server applies your attribution window anyway, so keeping it longer is harmless. Safari caps storage written by JavaScript at 7 days for sites that use it to track, so expect 7 days there.