Overview

The Spreeflo SDK is a small JavaScript snippet you embed on your website to track visitors, identify contacts, send web push notifications, and feed data into the Web Analytics dashboard. You must be subscribed to the Professional plan for visitor data to be captured.

This guide walks through embedding the SDK, the operations it exposes, and what you'll see in the Web Analytics dashboard once data is flowing.

Install the SDK

Add the loader script to every page you want to track, ideally inside the <head> tag. Replace YOUR_CLIENT_KEY with the client key shown in Web Analytics > Settings.

<!-- Spreeflo SDK -->
<script src="https://spreeflo.com/cdn/sdk/sdk-loader.js"></script>
<script>
  Spreeflo.init({ client_key: "YOUR_CLIENT_KEY" });
</script>

The loader is tiny and queues any commands you call before the full SDK has finished downloading, so you can call Spreeflo.identify or Spreeflo.track immediately after init.

init accepts the following options:

Spreeflo.init({
  client_key,
  track_links,
  track_data_attributes
}): void;

Attribute	Data type	Description	Value
`client_key`	string	Required. Your tracking key from Web Analytics > Settings.	`"ws_abc123xyz"`
`track_links`	boolean \| "outbound"	Optional. Auto-track every link click, or outbound links only.	`true` or `"outbound"`
`track_data_attributes`	boolean	Optional. Enables declarative tracking on elements marked with `data-spree-track`. Defaults to `true`; pass `false` to disable.	`true`

Identify visitors

Anonymous visitors are tracked with a generated visitor ID. Once you know who they are (e.g. after sign-in), call identify to link them to a contact record.

Spreeflo.identify("user@example.com", {
  first_name: "John",
  last_name: "Doe"
});

identify accepts the following arguments:

Spreeflo.identify(email, attributes): Promise<void>;

Attribute	Data type	Description	Value
`email`	string	Required. The contact's email address — used as the unique identifier.	`"user@example.com"`
`attributes`	object	Optional. Key/value pairs upserted onto the contact record.	`{ first_name: "John" }`

Track pages and events

Page views are tracked automatically on each navigation. To record a custom page name or extra properties, call page manually:

Spreeflo.page("Pricing", { plan: "pro" });

Use track for custom events such as form submits, purchases, or any action you want to feed into segments and journeys.

Spreeflo.track("purchased", { id: "cart:1234", total: 49.99 });
Spreeflo.track("signed_up", undefined, { PLAN: "pro" });

track accepts the following arguments:

Spreeflo.track(event, eventData, attributes): void;

Attribute	Data type	Description	Value
`event`	string	Required. The event name, used to drive triggers and segments.	`"purchased"`
`eventData`	object	Optional. Event-specific payload (e.g. cart contents, order total).	`{ id: "cart:1234", total: 49.99 }`
`attributes`	object	Optional. Contact attributes to update at the same time.	`{ PLAN: "pro" }`

To bind a click handler to a specific element without writing your own listener, use trackLink:

const cta = document.getElementById("hero-cta");
Spreeflo.trackLink(cta, { location: "homepage-hero" });

Declarative event tracking

You can also fire events without writing any JavaScript by adding a data-spree-track attribute to any clickable element. The SDK delegates a single click listener at the document level and tracks the element's event name on click. This is enabled by default; set track_data_attributes: false in init to turn it off.

At minimum, only data-spree-track is required — its value becomes the event name. The example below fires a cta_clicked event each time the button is clicked:

<button data-spree-track="cta_clicked">
  Get started
</button>

Any extra attributes prefixed with data-spree-prop- are collected into the event-data payload, with the data-spree-prop- prefix stripped to form each property key. The button below fires track("signed_up", { plan: "pro", source: "hero-cta" }) on click:

<button
  data-spree-track="signed_up"
  data-spree-prop-plan="pro"
  data-spree-prop-source="hero-cta"
>
  Sign up
</button>

The attribute works on any clickable element, including links. The example below fires nav_clicked with { destination: "pricing" } when the link is clicked, in addition to the link's normal navigation:

<a
  href="/pricing"
  data-spree-track="nav_clicked"
  data-spree-prop-destination="pricing"
>
  See pricing
</a>

The click listener is delegated, so the attributes also work on elements added to the page after the SDK has initialized (e.g. content rendered by a framework or injected dynamically).

Update contact attributes

Numeric contact attributes can be mutated atomically without needing to read the current value. Use these for counters like total_purchases, credits_remaining, or visit_streak.

Spreeflo.increment("total_purchases", 1);
Spreeflo.decrement("credits_remaining", 5);
Spreeflo.multiply("loyalty_points", 2);

Each method takes the same two arguments — an attribute key and a numeric amount:

Spreeflo.increment(attributeKey, amount): void;
Spreeflo.decrement(attributeKey, amount): void;
Spreeflo.multiply(attributeKey, amount): void;

Attribute	Data type	Description	Value
`attributeKey`	string	Required. The name of the numeric contact attribute to mutate.	`"total_purchases"`
`amount`	number	Required. The numeric amount applied to the existing value.	`1`

Each method applies a different operation to the current attribute value:

increment(attributeKey, amount) — adds amount to the current value. In the example above, total_purchases goes up by 1 each time the call runs (e.g. on every checkout).

decrement(attributeKey, amount) — subtracts amount from the current value. In the example, credits_remaining drops by 5 (e.g. after a credit-spending action).

multiply(attributeKey, amount) — multiplies the current value by amount. In the example, loyalty_points doubles (e.g. during a 2× loyalty-points promo).

The mutation is applied server-side against the latest stored value, so it's safe to call from concurrent sessions or browser tabs without racing.

Reset on logout

When a user signs out, call Spreeflo.reset() to clear the identified contact, generate a fresh anonymous visitor ID, and start a new session. Without this, the next user on the same browser will be attributed to the previous contact.

await Spreeflo.reset();

reset returns a Promise — await it before navigating (e.g. redirecting to a login page) so the web-push unsubscribe and visitor-ID rotation complete before the page unloads:

Spreeflo.reset(): Promise<void>;

Web Analytics dashboard

Once the SDK is sending data, the Web Analytics page in your dashboard summarizes the activity. Use the date range, segment, hostname, and contact-type filters at the top to narrow any view. Filters can also be drilled in by clicking values inside any of the tables.

Summary and charts

The top of the page shows summary cards for visitors, sessions, page views, bounce rate, and average session duration. Below that, a tabbed chart panel lets you switch between:

Visitors & Sessions — a time series of unique visitors and sessions.

Bounce Rate — the percentage of single-page sessions over time.

New vs Returning — the split between first-time and returning visitors.

Avg Session Duration — average time visitors spent per session.

Cohort Retention — a table showing how many visitors returned in each subsequent period.

Dimension tables

Below the chart, four table groups break the same metrics down by dimension. Each table has a search-zoom button that opens a fullscreen view.

Acquisition — Channels, Sources / Referrers, and UTM dimensions (source, medium, campaign, content, term).

Activity — Pages, Entry Pages, Exit Pages, and custom Events recorded via Spreeflo.track.

Technology — Browsers (drill into versions), Operating Systems (drill into versions), and Devices.

Geography — Countries, Regions, and Cities.

Settings and marketing status

Click the cog icon in the header to open Tracking Settings. Here you can:

Copy your Client Key for use in the SDK snippet.

Toggle whether anonymous visitors and identified visitors are counted as marketing contacts.

Manage Whitelisted Hostnames — only listed hostnames are tracked. Leave the list empty to track all traffic, or scope it to e.g. app.example.com to exclude staging or marketing-site traffic.

Reconfigure the tracking setup wizard from scratch.

Tip: Custom events you send through Spreeflo.track can be used as triggers in journeys (see the Custom Event Trigger) and as conditions inside segments.

Need Immediate Help? Contact our support team at support@spreeflo.com or check our other guides for more information.