Version:

Install JavaScript SDK

Install and set up the JavaScript SDK v3 on your website.

This guide will help you install the JavaScript SDK on your website via CDN or using NPM.

info
If you are migrating from an older version, see the Migration Guide for details.

Using CDN

You can install the JavaScript SDK using CDN and load it either asynchronously or synchronously.

The following sections list the steps to get the installation snippet and integrate it in your website.

Asynchronous loading

To integrate the SDK with your website and load it asynchronously:

  1. Go to the Setup tab of your JavaScript source in the RudderStack dashboard.
  2. Click the Minified or Unminified tab followed by Copy snippet and paste the script in your website’s <head> section.
JavaScript SDK installation snippet

Synchronous loading

To integrate the SDK with your website and load it synchronously:

  1. Go to the Setup tab of your JavaScript source in the RudderStack dashboard.
  2. Click the Minified or Unminified tab followed by Copy snippet.
JavaScript SDK installation snippet
  1. Set asyncScript (highlighted below) to false.
var asyncScript = false;
JavaScript SDK synchronous installation
  1. Paste the modified script in your website’s <head> section.
info

Note that:

  • Depending on the browser, the SDK loads either the legacy or modern JavaScript SDK bundle. The legacy bundle is built for ES5 while the modern bundle (with Module Federation) is built for ES6.
  • You can also pass your loadOptions as a third argument in the rudderanalytics.load method. See Load JavaScript SDK for more information.

Installation workflow

The installation code snippets listed above perform the following actions:

  1. Based on browser capabilities, load either the legacy or modern bundle.
  2. Load the necessary polyfills for the SDK to load.
  3. Create an array to store the events until the SDK is ready.
  4. Store the method invocations in the below table to replay them when the SDK is ready.
  5. Load the SDK with the specified write key.
MethodDescription
loadLoads the SDK with the specified write keyThe write key (or source write key) is a unique identifier for your source. RudderStack uses this key to send events from a source to the specified destination. .
identifyIdentifies the users, records their traits, and associates them with their actions.
pageRecords your website’s page views along with any other information about the viewed page.
trackTracks user events along with the associated properties.
aliasMaps new user ID with an old ID.
groupLinks an identified user with a group like a company, organization, or an account.
resetResets information related to the previously identified user.
readyFired when the SDK has initialized itself and the other third-party native SDK destinations.
setAnonymousIdSets the anonymous user ID.
startSessionStarts a new session.
endSessionResets the current session.

Using NPM

While using the above snippets to integrate the JavaScript SDK with your website is recommended, you can alternatively use the NPM module for packaging RudderStack directly into your project.

To install the JavaScript SDK via NPM, run the following command:

npm install @rudderstack/analytics-js --save
warning

Use this NPM module only for browser installation.

To integrate RudderStack with your Node.js apps, see Node.js SDK documentation

Since the NPM module exports the related APIs on an already-defined object combined with the Node.js module caching, run the following code snippet once and use the exported object throughout your project:

  • For ECMAScript modules (ESM):
import { RudderAnalytics } from '@rudderstack/analytics-js';

const rudderAnalytics = new RudderAnalytics();
rudderAnalytics.load(WRITE_KEY, DATA_PLANE_URL, {});
  
export { rudderAnalytics };
  • For CJS using the require method:
var RudderAnalytics = require("@rudderstack/analytics-js");

const rudderAnalytics = new RudderAnalytics();
rudderAnalytics.load(WRITE_KEY, DATA_PLANE_URL);

exports.rudderanalytics = rudderAnalytics;

SDK imports for bundling tools that process dynamic imports

If you are using a tool to bundle your application and it is attempting to process the dynamic runtime imports of the dependencies, update your SDK imports from @rudderstack/analytics-js to @rudderstack/analytics-js/bundled to avoid any issues with dynamic imports failing to find plugin modules.

Most common toolchains like the ones based on webpack, rollup, and vite should not face any issues. If your particular setup/toolchain is affected, contact RudderStack Support.

Integration with Chromecast

RudderStack supports integrating the JavaScript SDK with Google Chromecast. You can build the web sender app by following these instructions and adding the JavaScript SDK.

See Google Cast developer guide for more details.



Questions? Contact us by email or on Slack