JavaScript Tracking API

NPM Package

Sample usage:

import Siteblimp from '@siteblimp/tracking-js';

const sbClient = Siteblimp(siteKey);
sbClient.track("Test event", {sample: "property"});
sbClient.identify("test@example.com", {org: "example.com"});

Snippet

There are three methods available to install and configure the Siteblimp snippet.

Minimal snippet

<script>
  window._SB = {
    q: [],
    key: 'YOUR SITE KEY HERE'
  }
</script>
<script src="https://s.siteblimp.com" async></script>

Options

Options can be passed to the snippet by either setting the value directly to the window._SB object before including the snippet or by including as an attribute of the script tag. See examples below.

Available options include:

• key: [Required] The site key
• tracking_url: Overwrite the default value to send data to a different tracking server
• auto_click: Enable Page element click tracking (see more detail in Automated Tracking section). Disabled by default.

The tracking server URL can be overwritten from the default by passing the tracking_url parameter. Example:

<script>
  window._SB = {
    q: [],
    key: 'YOUR SITE KEY HERE',
    tracking_url: 'https://custom.tracking.com',
    auto_click = true
  }
</script>
<script src="https://s.siteblimp.com" async></script>

Tracking methods

Automated tracking

The tracking script will automatically track events for the following cases:

• New session
  • Includes Referrer, first/last visit timestamp, and count of visits as properties
• New instance
  • Includes referrer as property
• Page view
  • Includes URL, page title, and referrer as properties
• Page element clicked (Valid for <a>, <button>, <ul>, <li>, <input>, <textarea>)
  • Includes full CSS selector and inner text of element clicked (if available) as properties
  • Must be enabled with the auto_click snippet option.

Coming Soon

• Form submissions
• Page scroll %

Semi-Automated tracking

Tracking can be setup for individual page elements by adding attributes to the HTML tag. When included, the following events will automatically be tracked:

• View: On first page view or when the element is added to the page (for SPA pages)
• Hover: When either the element is in focus (via keyboard) or mouseover
• Click: When the element is clicked

With each event, the current page URL, page title, and referrer are included as properties. The provided event name will be postfixed with the event, such as: Signup Button Hover or Signup Button Click.

To setup element tracking, add the following attributes to the element:

• data-sb-event: The event name should be the value
• data-sb-prop: Querystring formatted key/value pairs (e.g. plan=premium&type=team)
• data-sb-once: No value required. If the attribute is present, the hover and click events will only be tracked one time per page (or instance of that element on the page for SPA)

Example:

<a href="/google-auth" data-sb-once data-sb-event="Authorize Google" data-sb-prop="location=footer&method=Google%20Auth">
  Authorize Google
</a>

Record events

Every event must have an event name provided. Properties are an optional object, which must be serializable to JSON. Nested values are accepted, but not recommended due to limited support when querying data.

window._SB.q.push(['track', event_name, {optional properties}])

Identities

The tracking script automatically generates the following identity information for each user and visit:

• anonymous_id - Permanent unique value to capture user activity each time a user visits the site. The anonymous_id is shared across multiple tabs/windows of the current site.
• session_id - Temporary unique value to capture a user's session on the site. A new value is automatically generated if more than 30 minutes of inactivity occur, starting a new session. The session_id is shared across multiple tabs/windows of the current site.
• instance_id - Temporary unique value to capture the unique instance of the site. The instance_id is not shared across multiple tabs/windows. It is reset when the window/tab/browser is closed.

Using the API methods below, two additional identities can be captured:

• identified_id - Any unique string value. Email address is generally preferred, unless the site visitors often have multiple email addresses. The identified_id is a permanent value shared across multiple tabs/windows.
• identified_org - Any unique string value. Company name or company domain is recommended. Org is used to roll multiple users into an organization or company. The identified_org is a permanent value shared across multiple tabs/windows.

The snippet will look for the most relevant persistent and temporary storage available. Cookies, followed by LocalStorage are the preferred methods for anonymous_id, session_id, identified_id, and identified_org. SessionStorage followed by WindowStorage are the preferred methods for instance_id.

Cookies will be stored on the site's primary domain, allowing values to persist across subdomains.

Identify anonymous visitors

To set the identified_id, use the following API method.

window._SB.q.push(['identify', identity, { options }])

The following parameters are optional:

{
  "org": "ORGANIZATION IDENTIFIER",
  "reset": true
}

• org - Sets the identified_org at the same time as the identified_id
• reset - When set to true and the identified_id is different than the identity already stored in Local Storage, reset will clear and regenerate the following: anonymous_id, session_id, identified_id, identified_org. This is useful for cases when the application allows switching of users. This can prevent connecting multiple identities to the same anonymous_id. It can also be useful for applications which are often used on shared web browsers.

Alias identities

There may be some cases when you need to connect one user identity to another. The following API method is provided:

window._SB.q.push(['alias', from_identity, to_identity, optional_original_identity])

The alias method should be used with care. It is preferred to use the identify method. The identity method uses alias behind the scenes:

alias(anonymous_id, identified_id, original_identified_id)

• original_identified_id is an optional parameter that does not change the result of the alias operation, but is stored with each unique alias operation. It is used for debugging aliasing problems.

Identify organizations

Organizations can be identified separately from users. It is supported to only identify the organization if the analytics only cares about team/company/account level analysis instead of users. Organizations can also be included in the options of the identify method.

window._SB.q.push(['org', identified_org])

Set User Properties

Users may have properties assigned. The system only maintains the most recent value in the user profile. User profiles can be used to set values such as geo-ip, payment plan level, customer since, conversion campaign, A/B test participant, etc.

Properties are an object, which must be serializable to JSON. Nested values are accepted, but not recommended due to limited support when querying data.

window._SB.q.push(['set', { properties }])

Force reset identities

Regenerates the following: anonymous_id, session_id, identified_id, identified_org. This is useful for cases when the application allows switching of users. The reset method will always force a reset of the values. Unlike the reset option of the identify method, no identity checking is done before permitting the reset. If the application is often used by multiple users or shared browsers, reset should be called on logout.

window._SB.q.push(['reset'])

Business actions tracking

Business actions require two steps for complete tracking:

1. Add an HTML data attribute to the link/buttons users click to start the action
2. Add a JavaScript tracking call when users complete the action

Signup Action

Signup tracking should be used when users signup for a subscription service the first time. If your subscription service is a B2B team product, it is recommended to include the organization name.

Data attribute: data-sb-signup

Example:

<a href="/signup" data-sb-signup>Signup</a>

JavaScript call when signup complete. Organization is optional:

window._SB.q.push(['signup', email, *organization])

Purchased Action

Purchase tracking should be used when a user purchases an item or starts a paid subscription.

Data attribute: data-sb-purchase

Example:

<a href="/purchase" data-sb-purchase>Purchase</a>

JavaScript call when purchase complete:

window._SB.q.push(['purchase'])

Login Action

When users login using either a login button or an automatic login (from remember me cookies), this login tracking should be used. If your subscription service is a B2B team product, it is recommended to include the organization name.

Data attribute: data-sb-login

Example:

<a href="/login" data-sb-login>Login</a>

JavaScript call when login complete. Organization is optional:

window._SB.q.push(['login', email, *organization])

Logout Action

It is recommended to capture logout actions. Here the purpose is to clean the user's identities which is important for cases where one user may use multiple email addresses on the same service or if it is a shared computer.

Data attribute: data-sb-logout

Example:

<a href="/logout" data-sb-logout>Logout</a>

JavaScript call when signup complete:

window._SB.q.push(['logout'])