Version: Latest (v3)v1.1

Use the JavaScript Service Worker SDK

This guide explains how to use the JavaScript service worker SDK in browser extensions and serverless runtimes.

Overview

The JavaScript service worker SDK brings RudderStack’s analytics capabilities to environments where the standard browser JavaScript SDK cannot operate. This specialized SDK targets non-browser contexts that require background processing and offline functionality.

This SDK exposes the same interface and applicable features as RudderStack’s Node.js SDK.

Some key features of the service worker SDK are:

• Browser extension compatibility: You can integrate analytics into Chrome extensions using manifest v3, supporting both content scripts and background scripts.
• Serverless runtime support: The SDK works seamlessly in serverless environments like Cloudflare Workers and Vercel Edge functions.
• Background processing: Service workers run independently of web pages, enabling reliable data collection even when users navigate away, and features like offline support and push notifications.

Install the service worker package

1. Run the following command to install the service worker package:

npm install @rudderstack/analytics-js-service-worker --save

2. Run the following snippet and use the exported object throughout your project:

import { Analytics } from '@rudderstack/analytics-js-service-worker';

const rudderClient = new Analytics('<WRITE_KEY>', '<DATA_PLANE_URL>/v1/batch');

This NPM module is meant to be used only in non-browser environments. To integrate RudderStack with your Node.js apps, RudderStack recommends using the Node.js SDK instead.

Note that the APIs are the same in both the cases.

Usage in Chrome extensions

You can use the JavaScript SDK in Chrome extensions with the manifest v3 as:

• Content script (via the JavaScript SDK package), OR
• Background script (via JavaScript service worker SDK).

See the Usage in Chrome Extensions for more information.

Usage in serverless runtimes

You can use the JavaScript service worker SDK in serverless runtimes like Cloudflare workers or Vercel Edge functions.

Cloudflare worker

To use the JavaScript SDK service worker in Cloudflare workers:

1. Start with the Cloudflare worker sample.
2. Integrate the SDK in the worker.js file:

import { Analytics } from '@rudderstack/analytics-js-service-worker';

const rudderClient = new Analytics(
  "<WRITE_KEY>",
  "<DATA_PLANE_URL>/v1/batch",
  {
    flushAt: 1
  }
);

3. Use the JavaScript SDK within the fetch methods with promisified flush:

const flush = () => new Promise((resolve) => rudderClient.flush(resolve));

rudderClient.track({
  userId: '123456',
  event: 'test cloudflare worker',
  properties: {
    data: {
      url: 'test cloudflare worker',
    },
  },
});

await flush();

For more information, see this sample implementation.

Vercel Edge

To use the JavaScript SDK service worker in Vercel Edge functions:

1. Start with the Vercel Edge function sample.
2. Integrate the SDK in the app/api/edge-function-sample/route.ts file:

import { Analytics } from '@rudderstack/analytics-js-service-worker';

const rudderClient = new Analytics(
  "<WRITE_KEY>",
  "<DATA_PLANE_URL>/v1/batch",
  {
    flushAt: 1
  }
);

3. Use the JavaScript SDK within the fetch methods as usual:

rudderClient.track({
  userId: '123456',
  event: 'test vercel edge worker',
  properties: {
    data: {
      url: 'test vercel edge worker',
    },
  }
});

For more information, see this sample implementation.

Questions? Contact us by email or on Slack