bigdelta-browser

Official browser SDK for Bigdelta, a web analytics platform with event tracking, session recording, and marketing attribution.

This README covers installing and using the SDK. For the rest of the platform, see the Bigdelta documentation.

Installation

To get started with using Bigdelta Browser SDK, install the package to your project via npm, yarn or script loader.

Every Bigdelta workspace has its own tracking key (a UUID). All examples below use <TRACKING_KEY> as a placeholder - replace it with your workspace's real key.

Installing via package manager

This SDK is available as a package on npm registry named @bigdelta/bigdelta-browser. You can install the package using npm or yarn CLI.

Using npm CLI

npm install @bigdelta/bigdelta-browser

Using yarn CLI

# yarn
yarn add @bigdelta/bigdelta-browser

Import the package into your project and initialize it with your tracking key.

import { Bigdelta } from '@bigdelta/bigdelta-browser';

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { pageViews: { enabled: true, singlePageAppTracking: 'any' }} });

Installing via script tag

This SDK is also available through CDN.

<script type="application/javascript"
        src="https://cdn.jsdelivr.net/npm/@bigdelta/bigdelta-browser/dist/index.iife.min.js"></script>
<script type="text/javascript">
    const client = new Bigdelta({
        trackingKey: '<TRACKING_KEY>',
        defaultTrackingConfig: {pageViews: {enabled: true, singlePageAppTracking: 'any'}}
    });
</script>

Track behavior

Important: Events are tracked from the first page view, before the visitor is identified. Until client.identify() is called, events are related to an anonymous users record whose id is generated by the SDK and kept in storage, so the same visitor stays consistent across pages and sessions. That record is flagged with the is_anonymous property.

Send event

You can track an event by calling client.track() with the event name and its properties.

client.track({ event_name: 'My Custom Event', properties: { my_property: 'property_value' }});

The following properties are default properties automatically included with every track event:

• Screen Height
• Screen Width
• Referrer
• Referring Domain
• Operating System
• Device Type
• Browser
• Browser Version

All events are sent via HTTPS.

Important Notes

• Data Sensitivity: Be careful not to collect sensitive user information without consent.

Track page views

Manually

You can track a page view event by calling client.trackPageView(). By default, 'Page View' is used as the event name, and the following properties are recorded:

• The page title.
• The page location.
• The page protocol.
• The page domain.
• The page path.
• The page query parameters.

You can always specify a custom name and add additional properties as shown below:

client.trackPageView({ event_name: 'My Custom Event', properties: { my_property: 'property_value' }}));

Automatically

Page View events can be tracked automatically on every page load by enabling the defaultTrackingConfig.pageViews during client creation (disabled by default), as shown below:

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { pageViews: { enabled: true }}});

Dynamic page views in single-page applications are tracked on any URL changes by default. You can control this behavior with the defaultTrackingConfig.pageViews.singlePageAppTracking option, as shown below:

// Track any URL changes.
const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { pageViews: { enabled: true, singlePageAppTracking: 'any' }}});

// Track when the path or query string changes, ignoring changes in the hash.
const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { pageViews: { enabled: true, singlePageAppTracking: 'path-with-query' }}});
    
// Only track when the path changes, disregarding changes in the query string or hash.
const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { pageViews: { enabled: true, singlePageAppTracking: 'path' }}});

// Disable dynamic page views tracking in single-page applications.
const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { pageViews: { enabled: true, singlePageAppTracking: 'disabled' }}});

Attribute marketing data

The library will automatically populate Page View events with any UTM parameters (utm_source, utm_campaign, utm_medium, utm_term, utm_content) or advertising click IDs (dclid, fbclid, gbraid, gclid, ko_click_id, li_fat_id, msclkid, rtd_cid, ttclid, twclid, wbraid) that are present on the page.

This default behavior can be turned off by disabling the defaultTrackingConfig.marketingAttribution option during client creation, as shown below:

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { pageViews: { enabled: true }, 
    marketingAttribution: false }});

First-touch attribution

The library also captures first-touch attribution on the very first Page View, even while the visitor is still anonymous. The first touch — the UTM parameters, the advertising click IDs, the referring domain and a derived channel type — is stored locally and never overwritten by later visits. Once you identify the visitor, it is attached to each identified record (e.g. user and account) using set_once, so the original acquisition source is recorded on the record only if it was not already set. On records these are written as plain properties (initial_utm_source, initial_utm_medium, initial_utm_campaign, initial_utm_term, initial_utm_content, initial_referring_domain, the initial_* click IDs and channel_type). This is disabled together with marketingAttribution, and cleared by reset.

Ensure idempotence

By default, all events, even if identical, are treated as unique and recorded in the system each time they are sent. However, you can specify a special property, $deduplication_id (of type string), to assign a unique identifier to an event. It allows deduplication of events that are accidentally sent multiple times. All subsequent events with the same $deduplication_id will be ignored and not recorded in the system.

client.track({ event_name: 'My Custom Unique Event', properties: { my_property: 'property_value', $deduplication_id: 'unique_id' }});

Track sessions

A session is a series of events that capture a single use of your product or a visit to your website. Analyzing sessions allows you to understand user behavior, including entry and exit points, duration of visits, activity, bounce rates, and more.

Bigdelta automatically computes sessions based on the events you send. This means you don't need to implement any special tracking. Our SDK adds a session identifier to each event and manage sessions automatically.

Events from the same user, browser, and device share the same session until there is no activity for more than 30 minutes, after which subsequent events are grouped into a new session. A session can include multiple tabs and windows, as long as they are in the same browser and on the same device. For example, moving from one Tab to another counts as a single session, but switching from one Browser to another starts a new session. You can also create a new session manually by calling client.reset().

Events with the created_at property manually set are not included in sessions. Additionally, you can exclude certain events (e.g., actions triggered automatically on behalf of the user) from session calculations, as shown below:

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { sessions: { enabled: true, 
    excludeEvents: ['Event Name'] }}});

If session tracking is not needed, it can be disabled, as shown below:

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { sessions: { enabled: false } }});

Record sessions

Session recording captures the DOM of your pages so you can replay what a visitor saw and did. It is disabled by default and is enabled per client, as shown below:

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { sessionRecording: { enabled: true } }});

Each page load produces one recording, grouped under the session it belongs to. Recording stops automatically after 30 minutes on the same page.

The recorder is not part of the main bundle and is downloaded on demand when recording starts. No additional setup is required for either installation method.

To bundle the recorder instead of loading it at runtime, for example when a content security policy disallows third-party scripts, import it once before creating the client:

import '@bigdelta/bigdelta-browser/recording';

Protect user data in recordings

All form inputs are masked by default. Password, email and telephone inputs are always masked and this cannot be disabled.

To record what visitors type into a particular field, name it with unmaskSelector:

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { sessionRecording: { enabled: true,
    unmaskSelector: '[data-bigdelta-unmask]' }}});

<input type="text" name="website" data-bigdelta-unmask />

Only elements matching the selector are revealed, and everything else stays masked. Password, email and telephone inputs stay masked even when the selector matches them, so a broad selector cannot expose them.

Page text is recorded as-is. To hide it, add the bigdelta-mask class to an element, which replaces the text of that element and its children:

<p class="bigdelta-mask">Order total: 42.00 EUR</p>

To leave an element out of the recording entirely, add the bigdelta-block class. The element is replaced with an empty placeholder of the same size:

<div class="bigdelta-block"><ThirdPartyWidget /></div>

When you cannot change the markup, the same can be expressed with CSS selectors:

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { sessionRecording: { enabled: true,
    maskTextSelector: '[data-private]', blockSelector: '#intercom-container' }}});

To mask everything and reveal only what you choose, use maskAllText together with unmaskSelector:

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { sessionRecording: { enabled: true,
    maskAllText: true, unmaskSelector: '.site-navigation' }}});

unmaskSelector reveals both page text and input values for the elements it matches.

Tune recording uploads

Recorded events are buffered and uploaded in chunks. Two options control this:

• flushIntervalMs — how often the buffer is uploaded. Defaults to 15000, clamped to between 5000 and 30000.
• maxRecordingDurationMs — how long a single page load records before stopping. Defaults to 1800000 (30 minutes), clamped to between 60000 (1 minute) and 7200000 (2 hours).

const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', defaultTrackingConfig: { sessionRecording: { enabled: true,
    flushIntervalMs: 30000, maxRecordingDurationMs: 600000 }}});

Values outside these ranges are clamped, not rejected.

Manage relations

Bigdelta automatically adds relationships provided during identification to each tracked event. However, if your events are also related to other workspace objects, you should explicitly define these relationships for each event via relations, as shown below:

client.track({ event_name: 'My Custom Event', properties: { my_property: 'property_value' }, relations: [{ object_slug: 'invoice', record_id: '63f2164c-2000-4f6c-b377-107368566222' }] });

Set related record properties

If a certain event is supposed to change related record properties, you can easily do that using the set and set_once parameters when specifying relations, as shown below:

// `set` - sets the value if it was never set before, or overrides the latest value if one exists.
// `set_once` - sets the value if it was never set before or ignores it otherwise.
client.track({ event_name: 'My Custom Event', properties: { my_property: 'property_value' }, relations: [{ object_slug: 'invoice', record_id: '63f2164c-2000-4f6c-b377-107368566222', set: { 'coupon': 'PROMO10' }, set_once: { 'invoice_no': 'IN001' }}]});

Identify users & companies

You can manage user identity through the client.identify() and client.reset() methods. Utilizing these methods correctly ensures that events are appropriately linked to the user, regardless of their transitions across devices and browsers.

Important: Calling client.identify() is not required for tracking. Events sent before it are related to an anonymous users record; once you identify a visitor, subsequent events are related to the id you provide instead.

When you identify a visitor who was previously anonymous, the anonymous record is merged into the identified one: its properties and all of its past events are transferred, so the activity you collected before sign-up is kept. This happens once — later identify() calls for an already identified visitor do nothing.

Identify

You can identify a user with a unique ID to monitor their activity across devices and associate them with their events. Once you have the current user's identity, you should call identify() as shown below, typically after they log in or sign up:

client.identify({ users: '<user id>' });

Get identifier

Identifiers provided via client.identify() are persisted and can be accessed later using client.getIdentifier(), as shown below:

client.identify({ invoices: '<invoice id>' });
client.getIdentifier('invoices'); // returns <invoice id>

Reset

When your users logout you can trigger a reset method which will help reset the user identity. We’ll disassociate all future tracked events from the currently identified user.

client.reset();

Set record properties

Related record properties could be set when tracking, as described here. However, if you need to set properties separately from the event or manage records that are not related to the event, you can use client.setRecordProperties(), as shown below:

client.setRecordProperties([
{
  id: 'd63506b4-cea0-4fde-9a0e-cb2edee48929',
  slug: 'users',
  properties: {
    set: {
      name: 'user',
    },
    set_once: {
      email_address: '[email protected]',
    },
  },
},
{
  id: client.getIdentifier('accounts'),
  slug: 'accounts',
  properties: {
    set: {
      title: 'account',
    },
    set_once: {
      owner: '[email protected]',
    },
  },
}]);

Protect user data with Bigdelta

Bigdelta prioritizes user privacy while providing flexibility in data collection. By default, Bigdelta is configured to transmit tracking data, but you have options to control this behavior.

Disable tracking

To prioritize user privacy, you can proactively disable tracking during initialization of the Bigdelta client. Set the disableTrackingByDefault property to true:

const client = new Bigdelta({trackingKey: '<TRACKING_KEY>', disableTrackingByDefault: true});

Dynamically toggle tracking

Bigdelta client allows you to dynamically manage tracking based on user preferences or specific scenarios. Use the following methods:

• client.enableTracking() activates the transmission of tracking data (this is the default state).
• client.disableTracking() deactivates the transmission of tracking data.

Control IP address and geolocation tracking

For more precise control over user privacy, Bigdelta offers the option to specifically toggle the tracking of IP address and geolocation information. Use the trackIpAndGeolocation property during initialization:

const client = new Bigdelta({
    trackingKey: '<TRACKING_KEY>',
    trackIpAndGeolocation: false  // Disable IP and geolocation tracking
});

Choose persistent storage

By default, cookies with a localStorage fallback are used to store state in the browser. You can control this behavior with the storageType option, as shown below:

// Use cookies explicitly.
const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', storageType: 'cookies'});

// Use localStorage explicitly.
const client = new Bigdelta({ trackingKey: '<TRACKING_KEY>', storageType: 'localStorage'});