Browser SDK

This SDK is for instrumenting web sites and applications to send data for the GitLab product analytics functionality.

How to use the Browser SDK

Using the NPM package

Add the NPM package to your package JSON using your preferred package manager:

::Tabs

:::TabTitle yarn

yarn add @gitlab/application-sdk-browser

:::TabTitle npm

npm i @gitlab/application-sdk-browser

::EndTabs

Then, for browser usage import the client SDK:

import { glClientSDK } from '@gitlab/application-sdk-browser';

this.glClient = glClientSDK({ appId, host });

Using the script directly

Add the script to the page and assign the client SDK to window:

<script src="https://unpkg.com/@gitlab/application-sdk-browser/dist/gl-sdk.min.js"></script>
<script>
  window.glClient = window.glSDK.glClientSDK({
    appId: 'YOUR_APP_ID',
    host: 'YOUR_HOST',
  });
</script>

You can use a specific version of the SDK like this:

<script src="https://unpkg.com/@gitlab/application-sdk-browser@0.2.5/dist/gl-sdk.min.js"></script>

Browser SDK initialization options

Apart from appId and host, you can configure the Browser SDK with the following options:

interface GitLabClientSDKOptions {
  appId: string;
  host: string;
  hasCookieConsent?: boolean;
  trackerId?: string;
  pagePingTracking?:
    | boolean
    | {
        minimumVisitLength?: number;
        heartbeatDelay?: number;
      };
  plugins?: AllowedPlugins;
}

Plugins

• Client Hints: An alternative to tracking the User Agent, which is particularly useful in browsers that are freezing the User Agent string. Enabling this plugin will automatically capture the following context:

  For example, iglu:org.ietf/http_client_hints/jsonschema/1-0-0 has the following configuration:

  {
     "isMobile":false,
     "brands":[
        {
           "brand":"Google Chrome",
           "version":"89"
        },
        {
           "brand":"Chromium",
           "version":"89"
        }
     ]
  }

• Link Click Tracking: With this plugin, the tracker adds click event listeners to all link elements. Link clicks are tracked as self-describing events. Each link-click event captures the link's href attribute. The event also has fields for the link's ID, classes, and target (where the linked document is opened, such as a new tab or new window).

• Performance Timing: It collects performance-related data from a user's browser using the Navigation Timing API. This API provides detailed information about the various stages of loading a web page, such as domain lookup, connection time, content download, and rendering times. This plugin helps to gather insights into how well a website performs for users, identify potential performance bottlenecks, and improve the overall user experience.

• Error Tracking: It helps to capture and track errors that occur on a website or application. By monitoring these errors, you can gain insights into potential issues with code or third-party libraries, which can help to improve the overall user experience, and maintain the quality of the website or application.

By default all plugins are enabled. You can disable or enable these plugins through the plugins object:

const tracker = glClientSDK({
  ...options,
  plugins: {
    clientHints: true,
    linkTracking: true,
    performanceTiming: true,
    errorTracking: true,
  },
});

Methods

identify

Used to associate a user and their attributes with the session and tracking events.

glClient.identify(userId, userAttributes);

page

Used to trigger a pageview event.

glClient.page(eventAttributes);

The eventAttributes object supports the following optional properties:

track

Used to trigger a custom event.

glClient.track(eventName, eventAttributes);

refreshLinkClickTracking

enableLinkClickTracking tracks only clicks on links that exist when the page has loaded. To track new links added to the page after it has been loaded, use refreshLinkClickTracking.

glClient.refreshLinkClickTracking();

trackError

NOTE: trackError is supported on the Browser SDK, but the resulting events are not used or available.

Used to capture errors. This works only when the errorTracking plugin is enabled. The plugin is enabled by default.

glClient.trackError(eventAttributes);

For example, trackError can be used in try...catch like below:

try {
  // Call the function that throws an error
  throwError();
} catch (error) {
  glClient.trackError({
    message: error.message, // "This is a custom error"
    filename: error.fileName || 'unknown', // The file in which the error occurred (e.g., "index.html")
    lineno: error.lineNumber || 0, // The line number where the error occurred (e.g., 2)
    colno: error.columnNumber || 0, // The column number where the error occurred (e.g., 6)
    error: error, // The Error object itself
  });
}

addCookieConsent

addCookieConsent is used to allow tracking of user identifiers via cookies. By default hasCookieConsent is false, and no user identifiers are passed. To enable tracking of user identifiers, call the addCookieConsent method. This step is not needed if you initialized the Browser SDK with hasCookieConsent set to true.

glClient.addCookieConsent();

setCustomUrl

Used to set a custom URL for tracking.

glClient.setCustomUrl(url);

setReferrerUrl

Used to set a referrer URL for tracking.

glClient.setReferrerUrl(url);

setDocumentTitle

Used to override the document title.

glClient.setDocumentTitle(title);

Contribute

If you would like to contribute to Browser SDK, follow the contributing guide.

Troubleshooting

If the Browser SDK is not sending events, or behaving in an unexpected way, take the following actions:

1. Verify that the appId and host values in the options object are correct.
2. Check if any browser privacy settings, extensions, or ad blockers are interfering with the Browser SDK.

For more information and assistance, see the Snowplow documentation or contact the Analytics Instrumentation team.