JavaScript SDK

Last updated 29 October 2026 · 2 minute read

The browser script sends page views and your own events to your Eventfox and nowhere else. It is under 5 KB gzipped, has no dependencies and never throws into your page.

Script tag

Eventfox serves the script itself, so any site can use it without a build step:

<script defer src="https://eventfox.example.com/ef.js" data-key="pk_live_xxxxxxxxxxxxxxxx"></script>

Optional attributes are data-consent="pending", data-auto-pageviews="false" and data-debug="true". The host is taken from the script's own src. The functions are on window.eventfox.

The npm package

The browser SDK, @eventfox/web, is MIT-licensed. Start it once, as early as you can in the browser:

import { init } from "@eventfox/web";

init({
  key: "pk_live_xxxxxxxxxxxxxxxx", // the project's public key
  host: "https://eventfox.example.com", // your Eventfox address
});

init does nothing on the server, so it is safe to import during server-side rendering. Calling it twice does nothing the second time. Page views are sent for you, including on history.pushState, replaceState and back and forward, so single-page apps need nothing more.

Options

Option	Default	Meaning
`key`	required	The project's public key. It can only add events, so it is safe in your page source.
`host`	required	The address of your Eventfox, with no trailing slash.
`autoPageviews`	`true`	Set `false` to send page views yourself with `page()`.
`requireConsent`	`false`	Set `true` to send and store nothing until `optIn()` is called.
`debug`	`false`	Logs what the script does to the browser console.

Functions

import { track, page, optIn, optOut, reset } from "@eventfox/web";

track("signup_completed", { plan: "pro" }); // a custom event, with optional properties
page();                                     // a page view (only needed with autoPageviews: false)
optIn();                                    // start sending, after consent
optOut();                                   // stop sending and forget the visitor
reset();                                    // forget the visitor ID and start afresh

Event names are 1 to 200 characters. Properties can be strings, numbers, booleans, null, arrays of those, or one level of nested object. See Custom events.

With requireConsent: true (or data-consent="pending" on the script tag), nothing is sent or stored until you call optIn(), which then sends a page view for the current page. Call it from your cookie banner's accept button. optOut() stops sending and clears the visitor ID; in Standard mode it also remembers the choice in localStorage. In a Privacy mode project the script stores nothing in the browser, so there is nothing to consent to.

What it sends

Page views and your events, each with the page address (without the query string, apart from three UTM values), the referrer on the first page view, and, in Standard mode when returning visitors are recognised, a random visitor ID kept in localStorage. Never cookies, never fingerprints. Events are batched (up to 10, or every 5 seconds), sent with sendBeacon when the page is hidden, and retried after short waits if the network fails.