Amplitude JavaScript SDK (Legacy)

8.21.10 · maintenance · verified Sun Apr 19

The `amplitude-js` library is the original JavaScript SDK for integrating web applications with Amplitude Analytics, enabling developers to track user events, user properties, and revenue data. Currently at version 8.21.10, this SDK primarily receives maintenance updates, with new feature development and a TypeScript-first approach now concentrated in the newer `@amplitude/analytics-browser` package. While `amplitude-js` continues to be functional for existing projects, it is no longer recommended for new browser-based instrumentations and has deprecated support for React Native since version 8.0.0, advising migration to `@amplitude/react-native` for cross-platform applications and `@amplitude/node` for server-side environments. Its release cadence has slowed significantly, focusing on bug fixes and dependency upgrades. It differentiates itself as the foundational Amplitude SDK before the introduction of more specialized and modern alternatives.

Common errors

```
Events not showing in Amplitude dashboard
```
cause Common causes include incorrect API key during `init()`, network connectivity issues, ad blockers preventing event transmission, or events being queued and not yet flushed to the server.

fix Verify your API key is correct during `amplitude.getInstance().init()`. Ensure events are being sent (e.g., `uploadIntervalMillis` configuration or `flushQueueSize`). Check browser console for errors or network requests to Amplitude. Use Amplitude's Chrome extension for real-time debugging.
```
Uncaught TypeError: amplitude.getInstance is not a function
```
cause This typically occurs if the Amplitude SDK script has not been loaded or has loaded incorrectly before `amplitude.getInstance()` is called. It can also happen in module environments if `amplitude` is not correctly imported.

fix Ensure the Amplitude SDK script tag is placed correctly in your HTML (ideally at the end of `<body>` or using `defer`). If using modules, verify `import amplitude from 'amplitude-js';` or `const amplitude = require('amplitude-js');` is at the top of your file and the module resolution is correct.
```
TypeError: undefined is not an object (evaluating 'e._q.push')
```
cause This error, often seen in environments with multiple SDKs or complex bundling, suggests an issue with Amplitude's internal queue mechanism, possibly due to conflicting snippets or incorrect initialization of the global `amplitude` object.

fix Check for multiple Amplitude snippets loaded on the page. Ensure the Amplitude snippet is loaded only once and initialized correctly. If using the snippet, ensure it's not being overridden. Consider consolidating to a single, consistent loading mechanism (e.g., npm package) if possible.
```
Amplitude cookie format changed, resulting in new device IDs for returning users.
```
cause This is a known breaking change introduced in `amplitude-js` v6.0. If applications using the same Amplitude project are not updated simultaneously, older SDK versions will write cookies in the old format, leading to new device IDs being generated for returning users once they encounter an application with the updated SDK.

fix Upgrade all client-side applications that share the same Amplitude API key to `amplitude-js` v6.0.0 or newer at the same time to ensure consistent cookie handling. Refer to the migration guide for additional options like `cookieForceUpgrade`.

Warnings

breaking The cookie format changed in v6.0 to be more compact. If you use the same Amplitude project across multiple applications and track anonymous users, all `amplitude-js` instances across those applications must be updated simultaneously. Failure to do so will result in anonymous users having different device IDs across your applications, leading to broken user journeys and inaccurate analytics.
Fix: Upgrade all instances of `amplitude-js` to version 6.0.0 or higher across all related applications concurrently. Consider using the `cookieForceUpgrade` option if necessary to force all browsers to upgrade and delete old cookies.
deprecated Support for React Native was removed from `amplitude-js` in version 8.0.0. The SDK is no longer maintained for React Native projects, and using it in such environments will lead to unexpected behavior and missing features.
Fix: Migrate your React Native projects to the dedicated `@amplitude/react-native` SDK. Refer to the official Amplitude migration guide for detailed steps.
gotcha The `amplitude-js` library is in maintenance mode, and new feature development is focused on the `@amplitude/analytics-browser` (TypeScript) SDK for web environments. Using `amplitude-js` for new projects means you will miss out on new features, improved developer experience, and better TypeScript support.
Fix: For all new browser-based Amplitude instrumentations, use the `@amplitude/analytics-browser` SDK. If you are starting a new React Native project, use `@amplitude/react-native`. For Node.js environments, use `@amplitude/node`.
gotcha Setting `flushIntervalMillis` to `0` was previously being overwritten by a default value of 10 seconds due to a bug. This could lead to unexpected delays in event transmission even when immediate flushing was desired.
Fix: Upgrade to `amplitude-js` version 8.21.9 or higher to ensure `flushIntervalMillis=0` correctly disables the flush interval and allows for immediate event processing.
gotcha When initiating `amplitude.init()` in `_app.js` within a Next.js application, it can cause 500 errors on pages that use `getServerSideProps` due to potential incompatibilities with Server-Side Rendering.
Fix: Avoid calling `amplitude.init()` directly in `_app.js` when using `getServerSideProps`. Instead, initialize the SDK client-side or consider dynamic imports and conditional initialization to ensure it only runs in the browser context for such pages. The `@amplitude/analytics-browser` SDK may offer more robust SSR solutions.

Install

npm install amplitude-js npm
yarn add amplitude-js yarn
pnpm add amplitude-js pnpm

Imports

amplitude (global)
```

<script type="text/javascript">
  amplitude.getInstance().init('YOUR_API_KEY');
</script>
```
For browser environments, `amplitude-js` is often loaded via a script tag, exposing `amplitude` as a global variable. This is the most common way to use it in traditional web pages.
amplitude (CommonJS)
wrong:
```
import amplitude from 'amplitude-js'; // Incorrect for older Node.js/CommonJS setups
```
correct:
```
const amplitude = require('amplitude-js');
```
When used in a CommonJS environment (e.g., older Node.js projects or bundlers configured for CJS), the package exports the main Amplitude instance. While modern environments often support ESM, `require` is still a common pattern for this specific SDK due to its legacy nature.
amplitude (ESM)
wrong:
```
const amplitude = require('amplitude-js'); // While technically works in some ESM contexts, prefer 'import'
```
correct:
```
import amplitude from 'amplitude-js';
```
For modern JavaScript environments with ESM support, the SDK can be imported as a default export. However, developers are strongly encouraged to consider the newer `@amplitude/analytics-browser` for new browser projects, which is TypeScript-first and designed for modern module systems.

Quickstart

This quickstart demonstrates how to initialize the Amplitude SDK, set a user ID and properties, and log two different events with associated properties. It showcases basic event tracking functionality in a browser context.

import amplitude from 'amplitude-js'; // Or const amplitude = require('amplitude-js');

// Initialize Amplitude with your API key
// Replace 'YOUR_API_KEY' with your actual Amplitude Project API Key
amplitude.getInstance().init('YOUR_API_KEY', null, {
  includeReferrer: true,
  includeUtm: true,
  saveEvents: true,
  logLevel: 'WARN',
  // Optional: Configure event upload interval (default is 10 seconds)
  uploadIntervalMillis: 5000,
  // Optional: Set the server zone if your project is in the EU
  // serverZone: 'EU'
});

// Set a user ID after initialization
amplitude.getInstance().setUserId('user_12345');

// Set user properties
amplitude.getInstance().setUserProperties({
  plan: 'premium',
  signup_date: new Date().toISOString(),
  country: 'USA',
});

// Log an event
amplitude.getInstance().logEvent('Button Clicked', {
  button_name: 'Submit Form',
  form_id: 'contact_form_1',
  page: window.location.pathname,
});

// Log another event after some user interaction
setTimeout(() => {
  amplitude.getInstance().logEvent('Page Viewed', {
    page_name: 'Product Details',
    product_id: 'SKU789',
    category: 'Electronics',
  });
  console.log('Amplitude initialized and events logged. Check your Amplitude dashboard.');
}, 2000);

view raw JSON →