React Router and Remix

Spreelytics loads in React Router's framework mode and in Remix from your root.tsx, and page changes through <Link> and navigate() are tracked for you. For a React app that only uses React Router for routing, see React.

Installation

import { Links, Meta, Scripts, ScrollRestoration } from "react-router";

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
        <script
          src="https://cdn.spreelytics.com/cdn/sdk/spreelytics-loader.js"
          data-client-key="YOUR_CLIENT_KEY"
        />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Usage

Tracking events

To track an event, call track():

export function SignupButton() {
  return (
    <button onClick={() => window.Spreelytics?.track("signup_clicked", { plan: "growth" })}>
      Start free trial
    </button>
  );
}

You can also tag an element, and Spreelytics tracks each click on it with no code:

<button data-spree-track="signup_clicked" data-spree-prop-plan="growth">
  Start free trial
</button>

Identifying users

After someone signs up or logs in, call identify() with their email address:

window.Spreelytics?.identify("ada@example.com", { first_name: "Ada" });

Logging people out

When someone logs out, call reset(), and the next person on that browser starts fresh as a new visitor of their own:

window.Spreelytics?.reset();

Tracking a pageview yourself

Page changes are tracked for you, but when a step changes without the address changing, like in a multi-step form, call page() with a path:

window.Spreelytics?.page("/signup/step-2");

Tracking a specific link

For one link with your own properties, use trackLink():

import { useEffect, useRef } from "react";

export function PricingLink() {
  const link = useRef<HTMLAnchorElement>(null);

  useEffect(() => {
    if (link.current) window.Spreelytics?.push(["trackLink", link.current, { position: "hero" }]);
  }, []);

  return <a ref={link} href="/pricing">See pricing</a>;
}

Getting the visitor ID

getVisitorId() returns this browser's anonymous ID. Your checkout can pass it along with each payment, so revenue is credited to the visit that brought it:

const visitorId = window.Spreelytics?.getVisitorId();

Session replay

Once session replay is on for your audience it records by itself, and you can pause it on a page with private details with stopReplay(), then carry on with startReplay():

window.Spreelytics?.stopReplay();

window.Spreelytics?.startReplay();

Advanced usage

Setting options

The script works as it is. To change a setting, swap data-client-key for an init call that carries your key and options:

<script src="https://cdn.spreelytics.com/cdn/sdk/spreelytics-loader.js" />
<script dangerouslySetInnerHTML={{ __html: 'Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", track_links: "outbound" });' }} />

Every option below goes in that init call.

track_links

Link clicks are off by default. Set it to "outbound" for links to other sites, or true for every link:

Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", track_links: "outbound" });

Each click becomes a Link Click event.

track_data_attributes

Set it to false to stop recording clicks on elements tagged with data-spree-track:

Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", track_data_attributes: false });

cookie_domain

The visitor cookie sits on your main domain, so www.example.com and app.example.com count the same person once. Set false to count each subdomain apart:

Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", cookie_domain: false });

redact_url

To hide IDs in your URLs, pass a function that returns the address to send:

Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", redact_url: (url) => url.replace(/[0-9]+/g, ":id") });

api_host

Point this at your own path to send tracking through your domain, so ad blockers don't stop it:

Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", api_host: "https://www.example.com/sp" });

Avoid ad blockers with a proxy sets up that path.

cookieless

Set it to true to count a visitor without cookies, for example before they answer your cookie banner, then call allowCookies() to move them onto a cookie later in the same visit:

Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", cookieless: true });

window.Spreelytics?.allowCookies();

session_replay

These change how session replay records:

Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", session_replay: { mask_all_inputs: true, block_class: "private" } });

debug

Logs each step to the browser console while you test, so you can see every event as it goes out:

Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", debug: true });

Next steps

• Track events: properties and data attributes.
• Identify users: what you can save on a person.
• Revenue: connect payments to your traffic.
• Avoid ad blockers with a proxy: send tracking through your own domain.