JavaScript web library

The JavaScript library runs in your visitors' browsers. It captures pageviews and interactions automatically, and gives you a small set of calls for the things only your code knows: who the user is, and which actions matter to your business.

Installing the library

There are two ways to add it.

The snippet (recommended)

Copy the web snippet from Project settings in the app and paste it into the <head> of every page. It is already filled in with your project key and your region's address. See Install the web snippet for the full steps.

A package from npm

An npm package for bundled apps (React, Vue, Next.js and similar) is coming soon. Until it is published, use the snippet: it works in single-page apps too, and records page changes made by your app's router.

Calling the library

Once the snippet has loaded, it defines a global library object. Its exact name is shown in the snippet in Project settings. The examples below call it analytics; use the name from your snippet in your own code.

Identify your users

Until you identify a visitor, their events are tied to an anonymous ID kept in their browser. When someone signs in or signs up, tell the library who they are:

analytics.identify("user_123", {
  email: "[email protected]",
  plan: "growth",
});

• Use a stable ID from your own system, such as your database's user ID. Avoid email addresses as the ID, because they can change.
• Events from before the user signed in are linked to the same person.
• Pass only the properties you need. Personal information you send becomes data you are responsible for under privacy law.

When the user signs out, reset the library, so the next person on the same device is not linked to them:

analytics.reset();

Capture custom events

Pageviews, clicks and form submissions are captured automatically. For the actions that matter most, capture an event of your own:

analytics.capture("plan_upgraded", {
  from_plan: "starter",
  to_plan: "growth",
  billing_period: "annual",
});

• Name events with a verb in the past tense, such as signup_completed or report_exported, and keep one naming style across your team.
• Add properties that you will want to filter or break down by.
• Custom events appear in the activity view and in every insight, funnel and retention chart.

Let visitors opt out

If your consent banner or privacy settings let visitors refuse analytics, stop capturing for that browser:

analytics.opt_out_capturing();

To start again after the visitor gives consent:

analytics.opt_in_capturing();

To check the current choice:

if (analytics.has_opted_out_capturing()) {
  // Show "Analytics: off" in your privacy settings.
}

The choice is stored in the visitor's browser and respected on later visits. If you need consent before anything is captured, the snippet can be set to start in the opted-out state; contact support and we will help you configure it for your consent flow.

Next steps

• Turn on session replay and choose what it masks.
• Use a custom tracking domain so ad blockers are less likely to block events.