SDK reference

1Installation

npm i @wnstn/canopy          # vanilla core
npm i @wnstn/canopy-nextjs   # React / Next.js wrapper (includes the core)

Using the script tag instead of bundling? Skip this page's install sections — the quick start covers the tag attributes, and everything below about options and hooks still applies via window.Canopy.init(options).

2Initializing

createCanopy (a factory — no new, no side effects at import time) validates your options, starts the tracker, and returns an instance:

import { createCanopy } from "@wnstn/canopy";

const canopy = createCanopy({
  siteId: "canopy_example_com",
  debug: process.env.NODE_ENV === "development",
});

Initialization is idempotent: calling it twice updates the existing instance's options instead of creating a second tracker. If siteId is missing, initialization throws a CanopyError (see error handling).

Options

3Instance methods

Typical lifecycle for a logged-in app:

canopy.identify({ userId: user.id, plan: user.plan });  // after login
canopy.track("feature_used", { name: "export" });        // anywhere
canopy.reset();                                          // on logout

4Module-level functions

The package also exports standalone functions that work before initialization by queueing internally. Once createCanopy runs, the queue replays in order — so import order and init order never matter:

import { track, pageview, identify } from "@wnstn/canopy";

track("signup_started");        // queued
pageview({ path: "/landing" }); // queued
identify({ userId: "123" });    // queued
createCanopy({ siteId: "canopy_example_com" }); // queue replays here

5Hooks

Hooks intercept every send — including automatic pageviews and outbound clicks — which makes them the place for redaction, filtering, and logging. All three can be async, and an error thrown inside a hook is caught and logged so it never breaks tracking:

createCanopy({
  siteId: "canopy_example_com",
  hooks: {
    beforeSend: (event) => {
      if (event.n === "outbound") return false;      // skip outbound clicks
      if (event.props?.email) event.props.email = "[redacted]";
      return event;                                   // or a modified event
    },
    afterSend: (event) => console.debug("sent", event.n),
    onError: (event, error) => reportToSentry(error),
  },
});

6Automatic behavior

After initialization the tracker quietly does the work you would otherwise wire up by hand:

Transport

Events are sent with navigator.sendBeacon when available so they survive page unload, falling back to fetch with keepalive. Requests are made with credentials: "omit" — nothing identifying rides along, and no response handling delays navigation.

Sessions

A session is a random UUID generated in memory when the first event needs it — never written to a cookie, localStorage, or anywhere else. It survives SPA navigations (the page never reloaded) and disappears when the tab closes, which is why Canopy needs neither a consent banner nor a privacy policy exception. reset() discards it on demand, e.g. on logout.

Debugging

Set debug: true to log each send to the console, and check the network tab for a 202 response from your endpoint.

7Error handling

Failures surface as CanopyError — a standard Error with a machine-readable code and typed helpers, so callers can branch on the kind of failure without string matching:

try {
  createCanopy({}); // missing siteId
} catch (e) {
  if (e instanceof CanopyError && e.isConfigError()) {
    // code: "CONFIG_ERROR"
  }
}

8Next.js wrapper

@wnstn/canopy-nextjs re-exports the entire core API and adds a provider and hooks. Mount CanopyProvider once in your root layout — it initializes the tracker synchronously on the client and keeps options fresh across renders:

import { CanopyProvider } from "@wnstn/canopy-nextjs";

export default function RootLayout({ children }) {
  return (
    <CanopyProvider siteId={process.env.NEXT_PUBLIC_CANOPY_SITE_ID!}>
      {children}
    </CanopyProvider>
  );
}

The provider accepts every core option plus scriptSrc: set it to a URL to additionally render a next/script tag, or false to suppress the script entirely (the default — the provider initializes the bundled tracker itself, so a script tag is usually unnecessary). CanopyScript is also exported standalone if you want just the tag.

Hooks

9Event payload

For reference — and for building your own ingestion clients — this is exactly what the tracker POSTs. Field meanings and server-side limits are documented in the HTTP API reference:

{
  "v": "0.1.0",                          // SDK version
  "s": "canopy_example_com",             // site ID
  "sid": "3f9c2a1e-...",                 // in-memory session ID
  "n": "pageview",                       // event name
  "u": "https://example.com/pricing",    // full URL
  "r": "https://google.com",             // referrer
  "p": "/pricing",                       // path + query
  "t": "Pricing — Example",              // page title
  "w": 1440,                             // viewport width
  "props": { "utm_source": "newsletter" },
  "env": "production",
  "ts": 1739755562410
}