Docs·SDKs

htmx

Spreelytics loads on htmx sites from your base template, and pages swapped in with hx-boost or hx-push-url are tracked for you, since both update the address bar.

Installation

Get your tracking snippet

In Spreelytics, open Settings → Tracking script and copy your client key, which goes in place of YOUR_CLIENT_KEY in the snippet below.

Add the snippet to htmx

Paste the script into the <head> of your base template:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My site</title>
    <script src="https://unpkg.com/htmx.org@2.0.4"></script>
    <script
      src="https://cdn.spreelytics.com/cdn/sdk/spreelytics-loader.js"
      data-client-key="YOUR_CLIENT_KEY"
    ></script>
  </head>
  <body hx-boost="true">
    <!-- your pages -->
  </body>
</html>

Verify

Open your site and click through a few pages, and within a few seconds Settings → Tracking script switches to Tracking is live while you show up on the Realtime page.

Usage

Tracking events

To track an event, call track():

Spreelytics.track("signup_clicked", { plan: "growth" });

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:

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:

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:

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

Tracking a specific link

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

Spreelytics.push(["trackLink", document.querySelector("#pricing-cta"), { position: "hero" }]);

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 = 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():

Spreelytics.stopReplay();

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>
<script>
  Spreelytics.init({ client_key: "YOUR_CLIENT_KEY", track_links: "outbound" });
</script>

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

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

Option	Default	What it does
`manual_start`	`false`	Records nothing until `startReplay()`.
`mask_all_inputs`	`true`	Masks what's typed into form fields. Password and email fields are always masked.
`mask_text_selectors`	`[]`	CSS selectors whose text is masked.
`mask_text_class`	`"rr-mask"`	A class whose text is masked.
`block_class`	`"rr-block"`	A class whose elements are left out, shown as an empty box.
`block_selector`	None	A CSS selector for elements to leave out.
`ignore_class`	`"rr-ignore"`	A class for fields whose typing isn't recorded.
`ignore_selector`	None	A CSS selector for fields whose typing isn't recorded.
`collect_fonts`	`false`	Records your web fonts, so replays look exact. Recordings get much bigger.
`slim_dom_options`	`"all"`	Leaves scripts and page metadata out of recordings. `false` keeps them.

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.

PreviousEmber Next Avoid ad blockers with a proxy