JavaScript SDK
3 minute read
RudderStack’s JavaScript SDK lets you track customer event data from your website and send it to your specified destinations. It is written in TypeScript and offers significant improvements in performance, size, and features compared to its predecessor.
This documentation covers the latest JavaScript SDK v3 (@rudderstack/analytics-js on npm).
Key features
- Fast, reliable, and less vulnerable to ad blockers.
- Load specific SDK features on demand using plugins.
- Lightweight storage data footprint with improved encryption.
- Complete control over the persistent data storage strategy.
- ITP (Intelligent Tracking Prevention) compliant as it implements server-side cookies.
- Smaller SDK of around 25KB (size reduction of approximately 30% from the previous version).
Get started
Migrating from older versions?
If you are upgrading from a version prior to v3, review these guides before getting started:
- Migration guide: Step-by-step instructions for updating your SDK implementation.
- Breaking changes: Understand the compatibility differences introduced in v3.
Learn about the benefits of upgrading to JavaScript SDK v3.
If you’re using npm module in your browser-side code, following code snippet will import the RudderStack JavaScript SDK and send its first page event.
// Step 1: Install the SDK - `npm i @rudderstack/analytics-js`
// Step 2: Initalize the SDK
import { RudderAnalytics } from '@rudderstack/analytics-js';
const rudderAnalytics = new RudderAnalytics();
rudderAnalytics.load(process.env.WRITE_KEY, process.env.DATA_PLANE_URL, {});
// Q: How to generate your WRITE_KEY and DATA_PLANE_URL?
// A: Create a new JavaScript source at https://app.rudderstack.com
export { rudderAnalytics };
// Step 3: Call event tracking methods such as `page`, `track`, `identify`, etc. as needed
rudderAnalytics.page();
// NOTICE: This code works only if you have set up your browser-side code to use `npm` modules. Follow the quickstart guide otherwise.
// https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/quickstart/
Follow the JavaScript SDK Quickstart to quickly start using RudderStack JavaScript SDK with any of your preferred methods (Using CDN, npm (ESM or CJS), or for single-page applications).
Core tasks
Find instructions for specific goals and common implementation tasks related to the JavaScript SDK:
| Guide | Description |
|---|---|
| Quickstart | Set up and use the JavaScript SDK on your website in no time. |
| Install the JavaScript SDK | Install the JavaScript SDK via CDN or NPM. |
| Load the SDK | Understand the different options for loading the SDK snippet. |
| Track event data | Use the SDK’s API calls (identify, track, page, etc.) to send data. |
| Configure data persistence | Customize how the SDK stores user information and preferences. |
| Use server-side cookies | Implement server-side cookies for improved tracking and ITP compliance. |
| Filter events | Control which events are sent to specific destinations. |
| Implement consent management | Configure the various consent management options in JavaScript SDK. |
| Detect Ad-blocked pages | Identify when the SDK might be blocked by ad blockers. |
| Use the service worker SDK | Implement tracking in service worker environments. |
| Use JavaScript SDK in Chrome extensions | Integrate the SDK within a Chrome browser extension. |
| Harden JavaScript SDK | Configure a hardened version of the JavaScript SDK for added security. |
Understand concepts
- JavaScript SDK key features: Learn about the significant enhancements in SDK v3.
- Data persistence in JavaScript SDK: Understand how and what data the SDK stores locally.
See FAQs for answers to the commonly-asked questions about the JavaScript SDK.
