Browser SDK 2

Amplitude's Browser SDK 2 lets you send events to Amplitude.

Install the SDK

Install the dependency with npm, yarn, or the script loader.

<script src="https://cdn.amplitude.com/script/AMPLITUDE_API_KEY.js"></script>
<script>
  window.amplitude.init('AMPLITUDE_API_KEY', {
    fetchRemoteConfig: true,
    autocapture: true
  });
</script>

<script src="https://cdn.eu.amplitude.com/script/AMPLITUDE_API_KEY.js"></script>
<script>
  window.amplitude.init('AMPLITUDE_API_KEY', {
    serverZone: 'EU',
    fetchRemoteConfig: true,
    autocapture: true
  });
</script>

# Install Analytics SDK only
npm install @amplitude/analytics-browser
# Or install Unified SDK to get access to all Amplitude products
npm install @amplitude/unified

// If using Analytics SDK only
import * as amplitude from '@amplitude/analytics-browser';
// If using Unified SDK
import * as amplitude from '@amplitude/unified';

# Install Analytics SDK only
yarn add @amplitude/analytics-browser
# Or install Unified SDK to get access to all Amplitude products
yarn add @amplitude/unified

// If using Analytics SDK only
import * as amplitude from '@amplitude/analytics-browser';
// If using Unified SDK
import * as amplitude from '@amplitude/unified';

Initialize the SDK

This SDK requires initialization before you can instrument any events and requires your Amplitude project's API key. You can pass an optional userID and config object in this call.

// Option 1, initialize with Amplitude API key only
amplitude.init(AMPLITUDE_API_KEY);

// Option 2, initialize with options
amplitude.init(AMPLITUDE_API_KEY, options);

// Option 3, initialize with user ID if it's already known
amplitude.init(AMPLITUDE_API_KEY, 'user@amplitude.com');

// Option 4, initialize with a user ID and options
amplitude.init(AMPLITUDE_API_KEY, 'user@amplitude.com', options);

runOutsideAngular(function () { amplitude.init(...args); })

Configure the SDK

Configure batching behavior

To support high-performance environments, the SDK sends events in batches. The SDK queues in memory every event the track method logs. Customize this behavior with the flushQueueSize and flushIntervalMillis configuration parameters. If you plan to send large batches of data at once, set useBatch to true and setServerUrl to the batch API: https://api2.amplitude.com/batch. Both standard and batch modes use the same event upload threshold and flush time intervals

EU data residency

To send data to Amplitude's EU-based servers, set the server zone when you initialize the client. If set, the SDK sends to the region determined by this setting.

amplitude.init(AMPLITUDE_API_KEY, {
  serverZone: 'EU',
});

Debugging

Control the level of logs the SDK prints to the console with the following logLevel settings:

Set the logLevel parameter.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  logLevel: amplitude.Types.LogLevel.Warn,
});

The default logger outputs log to the developer console. You can provide your own logger implementation based on the Logger interface for any customization purpose. For example, collecting any error messages from the SDK in a production environment.

Set the logger by configuring the loggerProvider with your own implementation.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  loggerProvider: new MyLogger(),
});

Debug mode

Enable the debug mode by setting the logLevel to "Debug", for example:

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  logLevel: amplitude.Types.LogLevel.Debug,
});

With the default logger, extra function context information is output to the developer console when invoking any SDK public method, including:

• type: Category of this context, for example "invoke public method".
• name: Name of invoked function, for example "track".
• args: Arguments of the invoked function.
• stacktrace: Stacktrace of the invoked function.
• time: Start and end timestamp of the function invocation.
• states: Useful internal states snapshot before and after the function invocation.

Autocapture

Starting in SDK version 2.10.0, the Browser SDK can autocapture events when you enable it, and adds a configuration to control the collection of autocaptured events. Browser SDK can autocapture the following event types:

• Attribution
• Page views
• Sessions
• Form interactions
• File downloads
• Element interactions
• Page URL enrichment
• Network tracking

Remote configuration

Autocapture supports remote configuration. For more information, see Autocapture Settings.

Disable Autocapture

To disable Autocapture, see the following code sample.

// Disable individual default tracked events
amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    attribution: false,
    pageViews: false,
    sessions: false,
    formInteractions: false,
    fileDownloads: false,
    elementInteractions: false,
    pageUrlEnrichment: false,
  },
});

// Disable all default tracked events
amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: false,
});

Track marketing attribution

Amplitude tracks marketing attribution by default. Browser SDK 2 captures UTM parameters, referrer information, and click IDs as user properties.

https://www.amplitude.com/?utm_source=newsletter&utm_campaign=product_analytics_playbook&utm_medium=email&utm_term=product%20analytics&utm_content=banner-link

Set config.autocapture.attribution to false to disable marketing attribution tracking.

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    attribution: false, 
  },
});

Advanced configuration for marketing attribution tracking

Exclude referrers

The default value of config.autocapture.attribution.excludeReferrers is the top level domain with cookie storage enabled. For example, if you initialize the SDK on https://www.docs.developers.amplitude.com/, the SDK first checks amplitude.com. If it doesn't allow cookie storage, then the SDK checks developers.amplitude.com and subsequent subdomains. If it allows cookie storage, then the SDK sets excludeReferrers to an RegExp object /amplitude\.com$/ which matches and then exlucdes tracking referrers from all subdomains of amplitude.com, for example, data.amplitude.com, analytics.amplitude.com and etc.

In addition to excluding referrers from the default configuration, you can add other domains by setting the custom excludeReferrers. Custom excludeReferrers overrides the default values. For example, to also exclude referrers from google.com, set excludeReferrers to [/amplitude\.com$/, 'google.com'].

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    attribution: {
      // Override the default setting to exclude all subdomains
      excludeReferrers: [],
    },
  },
});

amplitude.init(AMPLITUDE_API_KEY, {
    autocapture: {
    attribution: {
      excludeReferrers: [/your-domain\.com$/, 'www.test.com'],
    },
  },
});

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    attribution: {
      excludeReferrers: [/test\.com$/],
    },
  },
});

Track page views

Amplitude tracks page view events by default. The default behavior sends a page view event on initialization. The event type for this event is [Amplitude] Page Viewed.

Set config.autocapture.pageViews to false to disable page view tracking.

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    pageViews: false, 
  },
});

Advanced configuration for tracking page views

Use the advanced configuration to better control when the SDK sends page view events.

For example, you can configure Amplitude to track page views only when the URL path contains a certain substring.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    pageViews: { 
      trackOn: () => {
        return window.location.pathname.includes('home');
      },
    },
  },
});

Browser SDK tracks the following information in page view events.

Review this example to understand how to enrich default page view events, such as adding more properties along with page view tracking.

Page title masking

Amplitude lets you to mask page titles in events that include the [Amplitude] Page Title property. This protects your sensitive page title information. Use the data-amp-mask attribute on your <title> element to exclude the actual page title from this property.

When the <title> element has the data-amp-mask attribute, Amplitude replaces the page title with a masked value across all events that capture page title information. For example:

<head>
  <!-- This page title will be masked in all events that capture page titles -->
  <title data-amp-mask>John Doe - Personal Banking Dashboard</title>
</head>

<head>
  <!-- Works with any attribute value -->
  <title data-amp-mask="true">Sensitive Customer Information</title>
</head>

Track sessions

Amplitude tracks session events by default. A session is the period of time a user has your website open. See How Amplitude defines sessions for more information. When a new session starts, Amplitude tracks a session start event and is the first event of the session. The event type for session start is [Amplitude] Start Session. When an existing session ends, Amplitude tracks a session end event, which is the last event of the session. The event type for session end is [Amplitude] End Session.

You can opt out of tracking session events by setting config.autocapture.sessions to false. Refer to the code sample below.

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    sessions: false, 
  },
});

Track form interactions

Amplitude tracks form interaction events by default. The SDK tracks [Amplitude] Form Started when the user initially interacts with the form element. An initial interaction can be the first change to a text input, radio button, or dropdown. The SDK tracks a [Amplitude] Form Submitted when the user submits the form. If a user submits a form with no initial change to any form fields, Amplitude tracks both [Amplitude] Form Started and [Amplitude] Form Submitted events.

Amplitude can track forms constructed with <form> tags and <input> tags nested. For example:

<form id="subscriber-form" name="subscriber-form" action="/subscribe">
  <input type="text" />
  <input type="submit" />
</form>

Set config.autocapture.formInteractions to false to disable form interaction tracking

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    formInteractions: false, 
  },
});

Track file downloads

Amplitude tracks file download events by default. The SDK tracks [Amplitude] File Downloaded when the user clicks an anchor or <a> tag linked to a file. Amplitude determines that the anchor or <a> tag linked to a file if the file extension matches the following regex:

pdf|xlsx?|docx?|txt|rtf|csv|exe|key|pp(s|t|tx)|7z|pkg|rar|gz|zip|avi|mov|mp4|mpe?g|wmv|midi?|mp3|wav|wma

Set config.autocapture.fileDownloads to false to disable file download tracking.

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    fileDownloads: false,
  },
});

Track element interactions

You can enable element interaction tracking to capture clicks and changes for elements on your page, which is required for Visual labeling. Review our page on Autocapture privacy and security for more information about the data collected with these events.

Set config.autocapture.elementInteractions to true to enable element click and change tracking.

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    elementInteractions: true, 
  },
});

Advanced configuration for element interactions

Use the advanced configuration to control element interaction tracking.

For example, you could configure Amplitude only to capture clicks on elements with a class of amp-tracking on the blog pages of a site as follows:

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  autocapture: {
    elementInteractions: {
      cssSelectorAllowlist: [
        '.amp-tracking'
      ],
      // When you use `cssSelectorAllowlist` to target specific elements, set `actionClickAllowlist`  [tl! ~~:2]
      // to ensure that Amplitude tracks interactions with non-standard clickable elements during page transitions or DOM updates.
      actionClickAllowlist: [],
      pageUrlAllowlist: [
        new RegExp('https://amplitude.com/blog/*')
      ]
    }
  }
});

By default, if you don't use these settings, Amplitude tracks the default selectors on all page on which you enable the plugin.

import { DEFAULT_CSS_SELECTOR_ALLOWLIST } from '@amplitude/plugin-autocapture-browser';

const selectors = [
  ...DEFAULT_CSS_SELECTOR_ALLOWLIST,
  '.class-of-a-thing-i-want-to-track',
];

Track frustration interactions

Enable frustration interaction tracking to capture rage clicks and dead clicks. Amplitude defines "rage click" and
"dead click" events as:

• Rage click: A user clicks the same element, within 50px, four times in under a second.
• Dead click: A user clicks an interactable element, but no navigation change happens and the DOM doesn't change.

Set config.autocapture.frustrationInteractions to true to enable capture of dead clicks and rage clicks.

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    frustrationInteractions: true, 
  },
});

Advanced configuration for frustration interactions

Use the advanced configuration to control frustration interaction tracking.

Track network requests

Track when network requests fail (only XHR and fetch). By default, tracks network requests with a response code in the range 500-599, excluding requests made to any amplitude.com domain.

Set config.autocapture.networkTracking to true to enable network request tracking

amplitude.init(AMPLITUDE_API_KEY, {
  autocapture: {
    networkTracking: true, 
  },
});

When you enable this setting, Amplitude tracks the [Amplitude] Network Request event whenever the application makes a network request.

Advanced configuration for network tracking

Set config.autocapture.networkTracking to a NetworkTrackingOptions to configure which network requests get tracked.

Safe headers

When you set requestHeaders: true or responseHeaders: true, Amplitude captures only safe headers and excludes sensitive ones that may contain authentication credentials or personally identifiable information.

Network body capture

If a network request or response body is in JSON, you can capture part of the response body by configuring responseBody.allowlist and responseBody.blocklist. You can capture part of the request body by configuring requestBody.allowlist and requestBody.blocklist.

The allowlist and blocklist are lists of JSON Pointer-like strings that capture specific fields. (For example: ['foo/bar', 'hello/**']). allowlist tells the client which fields to capture. excludelist tells the client to exclude fields from capture (by default, nothing captured)

Example request/response body

{
  "a": "A",
  "b": {
    "c": "C",
    "d": {
      "e": "E",
      "f": "F"
    }
  },
  "g": "G"
}

Track an event

Events represent how users interact with your application. For example, the Button Clicked event might be an action you want to track.

// Track a basic event.
amplitude.track('Button Clicked');

// Track events with optional properties.
const eventProperties = {
  buttonColor: 'primary',
};
amplitude.track('Button Clicked', eventProperties);

You can also pass a BaseEvent object to track. For more information, review the BaseEvent interface for all available fields.

const event_properties = {
  buttonColor: 'primary',
};

const event = {
  event_type: "Button Clicked", 
  event_properties,
  groups: { 'role': 'engineering' },
  group_properties: { 'groupPropertyKey': 'groupPropertyValue' }
};

amplitude.track(event);

Track events to multiple projects

By default, Amplitude SDKs send data to one Amplitude project. To send data to more than one project, add an instance of the Amplitude SDK for each project you want to receive data. Then, pass instance variables to wherever you want to call Amplitude. Each instance allows for independent apiKey, userId, deviceId, and settings values.

const defaultInstance = amplitude.createInstance();
defaultInstance.init(API_KEY_DEFAULT);

const envInstance = amplitude.createInstance();
envInstance.init(API_KEY_ENV, {
  instanceName: 'env',
});

User properties

User properties are details like device details, user preferences, or language to help you understand your users at the time they performed an action in your app.

Identify is for setting the user properties of a particular user without sending any event. The SDK supports the operations set, setOnce, unset, add, append, prepend, preInsert, postInsert, and remove on individual user properties. Declare the operations through a provided Identify interface. You can chain together multiple operations in a single Identify object. The Identify object is then passed to the Amplitude client to send to the server.

Set a user property

The Identify object provides controls for setting user properties. To set a user property:

1. Instantiate an Identify object
2. Call methods on that object
3. Instruct the SDK to make a call with the Identify object

const identifyEvent = new amplitude.Identify();
// Use methods in the following sections to update the Identify object
amplitude.identify(identifyEvent);

Identify.set

This method sets the value of a user property. For example, you can set a role property of a user.

const identifyEvent = new amplitude.Identify();
identifyEvent.set('location', 'LA'); 
amplitude.identify(identifyEvent);

Identify.setOnce

This method sets the value of a user property only one time. Subsequent calls using setOnce() are ignored. For example, you can set an initial login method for a user. setOnce() ignores later calls.

const identifyEvent = new amplitude.Identify();
identifyEvent.setOnce('initial-location', 'SF'); 
identify(identifyEvent);

Identify.add

This method increments a user property by a numerical value. If the user property doesn't have a value set yet, it's initialized to 0 before it's incremented. For example, you can track a user's travel count.

const identifyEvent = new amplitude.Identify();
identifyEvent.add('travel-count', 1); 
amplitude.identify(identifyEvent);

Arrays in user properties

Call the prepend, append, preInsert, or postInsert methods to use arrays as user properties.

Identify.prepend

This method prepends a value or values to a user property array. If the user property doesn't have a value set yet, it's initialized to an empty list before the new values are prepended.

const identifyEvent = new Identify();
identifyEvent.prepend('visited-locations', 'LAX'); 
identify(identifyEvent);

Identify.append

This method appends a value or values to a user property array. If the user property doesn't have a value set yet, it's initialized to an empty list before the new values are prepended.

const identifyEvent = new amplitude.Identify();
identifyEvent.append('visited-locations', 'SFO'); 
amplitude.identify(identifyEvent);

Identify.postInsert

This method post-inserts a value or values to a user property if it doesn't exist in the user property yet. Post-insert means inserting the values at the end of a given list. If the user property doesn't have a value set yet, it's initialized to an empty list before the new values are post-inserted. If the user property has an existing value, this method is a no-op.

const identifyEvent = new amplitude.Identify();
identifyEvent.postInsert('unique-locations', 'SFO'); 
amplitude.identify(identifyEvent);

Identify.remove

This method removes a value or values to a user property if it exists in the user property. Remove means remove the existing values from the given list. If the user property has an existing value, this method is a no-op.

const identifyEvent = new amplitude.Identify();
identifyEvent.remove('unique-locations', 'JFK') 
amplitude.identify(identifyEvent);

User groups

Amplitude supports assigning users to groups and performing queries, such as Count by Distinct, on those groups. If at least one member of the group has performed the specific event, then the count includes the group.

For example, you want to group your users based on what organization they're in by using an 'orgId'. Joe is in 'orgId' '10', and Sue is in 'orgId' '15'. Sue and Joe both perform a certain event. You can query their organizations in the Event Segmentation Chart.

When setting groups, define a groupType and groupName. In the previous example, 'orgId' is the groupType and '10' and '15' are the values for groupName. Another example of a groupType could be 'sport' with groupName values like 'tennis' and 'baseball'.

Setting a group also sets the groupType:groupName as a user property, and overwrites any existing groupName value set for that user's groupType, and the corresponding user property value. groupType is a string, and groupName can be either a string or an array of strings to tell that a user is in multiple groups.

// set group with a single group name
amplitude.setGroup('orgId', '15');

// set group with multiple group names
amplitude.setGroup('sport', ['soccer', 'tennis']);

Pass an Event object with groups to a Track call to set an event-level group. With event-level groups, the group designation applies only to the specific logged event, and doesn't persist to the user unless you explicitly set it with setGroup.

amplitude.track({
  event_type: 'event type',
  event_properties: { eventPropertyKey: 'event property value' },
  groups: { 'orgId': '15' }
})

Group properties

Use the Group Identify API to set or update the properties of particular groups. These updates only affect events going forward.

The groupIdentify() method accepts a group type and group name string parameter, as well as an Identify object that's applied to the group.

const groupType = 'plan';
const groupName = 'enterprise';
const groupIdentifyEvent = new amplitude.Identify()
groupIdentifyEvent.set('key1', 'value1');
amplitude.groupIdentify(groupType, groupName, groupIdentifyEvent); 

Track revenue

The preferred method of tracking revenue for a user is to use revenue() in conjunction with the provided Revenue interface. Revenue instances store each revenue transaction and allow you to define several special revenue properties (like revenueType and productIdentifier) that are used in Amplitude's Event Segmentation and Revenue LTV charts. These Revenue instance objects are then passed into revenue() to send as revenue events to Amplitude. This lets automatically display data relevant to revenue in the platform. You can use this to track both in-app and non-in-app purchases.

To track revenue from a user, call revenue each time a user generates revenue. In this example, the user purchased 3 units of a product at $3.99.

const event = new amplitude.Revenue()
  .setProductId('com.company.productId')
  .setPrice(3.99)
  .setQuantity(3);

amplitude.revenue(event);

Revenue interface

Flush the event buffer

The flush method triggers the client to send buffered events immediately.

amplitude.flush();

By default, Browser SDK callsflush automatically at an interval. If you want to flush all events, control the async flow with the optional Promise interface, for example:

amplitude.init(API\_KEY).promise.then(function() {
  amplitude.track('Button Clicked');
  amplitude.flush();
});

Custom user identifier

If your application has a login system that you want to track users with, call setUserId to update the user's identifier.

amplitude.setUserId('user@amplitude.com');

Custom session identifier

Assign a new session ID with setSessionId. When you set a custom session ID, make sure the value is in milliseconds since epoch (Unix Timestamp).

amplitude.setSessionId(Date.now());

Custom device identifier

Assign a new device ID with deviceId. When you set a custom device ID, make sure the value is sufficiently unique. Amplitude recommends using a UUID.

amplitude.setDeviceId(uuid());

Reset when the user logs out

Use reset as a shortcut to anonymize users after they log out. reset does the following:

1. Sets userId to undefined.
2. Sets deviceId to a new UUID value.

With an undefined userId and a new deviceId, the user appears to Amplitude as a new user.

amplitude.reset();

Opt users out of tracking

Set setOptOut to true to disable logging for a specific user.

amplitude.setOptOut(true);

Amplitude doesn't save or send events to the server while setOptOut is enabled. The setting persists across page loads.

Set setOptOut to false to re-enable logging.

amplitude.setOptOut(false);

Optional tracking

By default, the SDK tracks these properties automatically. You can override this behavior by passing a configuration called trackingOptions when initializing the SDK, setting the appropriate options to false.

amplitude.init(AMPLITUDE_API_KEY, {
  trackingOptions: {
    ipAddress: false,
    language: false,
    platform: false,
  },
});

Callback

All asynchronous APIs are optionally awaitable through a Promise interface. This also serves as a callback interface.

amplitude.init("apikey", "12321.com").promise.then(function() { 
 // init callback
})

amplitude.track('Button Clicked').promise.then(function(result) {
 result.event; // {...} (The final event object sent to Amplitude)
 result.code; // 200 (The HTTP response status code of the request.
 result.message; // "Event tracked successfully" (The response message)
});

// Using async/await
const initResult = await amplitude.init("apikey", "12321.com").promise;

const results = await amplitude.track('Button Clicked').promise;
result.event; // {...} (The final event object sent to Amplitude)
result.code; // 200 (The HTTP response status code of the request.
result.message; // "Event tracked successfully" (The response message)

Plugins

Plugins allow you to extend Amplitude SDK's behavior by, for example, modifying event properties (enrichment plugin) or sending to third-party endpoints (destination plugin). A plugin is an Object with optional fields name and type and methods setup(), execute() and teardown().

add

The add method adds a plugin to Amplitude.

amplitude.add(new Plugin());

remove

The remove method removes the given plugin name from the client instance if it exists.

amplitude.remove(plugin.name);

Create a custom plugin

Plugin examples

const enrichPageUrlPlugin = (): EnrichmentPlugin => {
  return {
    execute: async (event: Event) => {
      event.event_properties = {
        ...event.event_properties,
        page_url: location.href,
      };
      return event;
    },
  }
}
 
amplitude.add(enrichPageUrlPlugin());
amplitude.init(API_KEY);

const customDestination = (customUrl: string): DestinationPlugin => {
  return {
    type: 'destination',
    execute: async (event: Event) => {
      const payload = {
        k: 'apikey',
        d: event,
      };

      const response = await fetch(customUrl, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Accept: '\*/\*',
        },
        body: JSON.stringify(payload),
      });

      return {
        code: response.status,
        event: event,
        message: response.statusText,
      };
    },
  };
};

amplitude.init(API_KEY);
amplitude.add(myDestinationPlugin('https://custom.url.com'));

Available plugins

Amplitude provides several official plugins to extend the Browser SDK functionality:

Page URL enrichment plugin

The page URL enrichment plugin is enabled by default with autocapture. It automatically adds page URL-related properties to all events, including current page information, previous page location, and page type classification.

To disable page URL enrichment, set autocapture.pageUrlEnrichment to false:

amplitude.init(API_KEY, {
  autocapture: {
    pageUrlEnrichment: false,
  },
});

For custom configuration or if you disabled autocapture entirely, you can still add the plugin manually:

import { pageUrlEnrichmentPlugin } from '@amplitude/plugin-page-url-enrichment-browser';

const pageUrlEnrichment = pageUrlEnrichmentPlugin();
amplitude.add(pageUrlEnrichment);
amplitude.init(API_KEY);

Troubleshooting and debugging

Debugging in a browser can help you identify problems related to your code's implementation, as well as potential issues within the SDKs you're using. Here's a basic guide on how to use the browser's built-in Developer Tools (DevTools) for debugging.

Console

You can find JavaScript errors under Inspect > Console, which might have the details about the line of code and file that caused the problem. The console also allows you to execute JavaScript code in real time.

• Enable debug mode by following these instructions. Then With the default logger, extra function context information will be output to the developer console when any SDK public method is invoked, which can be helpful for debugging.

• Amplitude supports SDK deferred initialization. Events tracked before initialization will be dispatched after the initialization call. If you cannot send events but can send the event successfully after entering amplitude.init(API_KEY, 'USER_ID') in the browser console, it indicates that your amplitude.init call might not have been triggered in your codebase or you aren't using the correct Amplitude instance during initialization. Therefore, check your implementation."

Network Request

Use the Inspect > Network tab to view all network requests made by your page. Search for the Amplitude request.

Check the response code and ensure that the response payload is as expected.

Instrumentation Explorer/Chrome Extension

The Amplitude Instrumentation Explorer is an extension available in the Google Chrome Web Store. The extension captures each Amplitude event you trigger and displays it in the extension popup. It's important to ensure that the event has been sent out successfully and to check the context in the event payload.

Common Issues

The following are common issues specific to Browser SDK. For more general common issues, see SDK Troubleshooting and Debugging.

Ad blocker

Ad Blocker might lead to event dropping. The following errors indicate that the tracking has been affected by Ad Blocker. When loading through a script tag, an error may appear in the console/network tab while loading the SDK script. When loaded with npm package, there could be errors in the network tab when trying to send events to the server. The errors might vary depending on the browser.

• Chrome (Ubuntu, MacOS)
  Console: error net::ERR_BLOCKED_BY_CLIENT
  Network: status (blocked:other)
• Firefox (Ubuntu)
  Console: error text doesn’t contain any blocking-specific info
  Network: Transferred column contains the name of plugin Blocked by uBlock Origin
• Safari (MacOS)
  Console: error contains text Content Blocker prevented frame ... from loading a resource from ...
  Network: it looks like blocked requests aren't listed. Not sure if it’s possible to show them.

Amplitude recommends using a proxy server to avoid this situation.

Cookies related

Here is the information SDK stored in the cookies. This means that client behavior, like disabling cookies or using a private browser/window/tab, will affect the persistence of these saved values in the cookies. If these values aren't persistent or aren't increasing by one, that could be the reason.

CORS

Cross-Origin Resource Sharing (CORS) is a security measure implemented by browsers to restrict how resources on a web page can be requested from a different domain. It might cause this issue if you used setServerURL.

Access to fetch at 'xxx' from origin 'xxx' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

Cross-origin resource sharing (CORS) prevents a malicious site from reading another site's data without permission. The error message suggests that the server you're trying to access isn't allowing your origin to access the requested resource. This is due to the lack of the Access-Control-Allow-Origin header in the server's response.

• If you have control over the server, you can "Update the server's CORS policy". Add the Access-Control-Allow-Origin header to the server's responses. This would allow your origin to make requests. The value of Access-Control-Allow-Origin can be * to allow all origins, or it can be the specific URL of your web page.

• If you don't have control over the server, you can set up a proxy server that adds the necessary CORS headers. The web page makes requests to the proxy, which then makes requests to the actual server. The proxy adds the Access-Control-Allow-Origin header to the response before sending it back to the web page.

If you have set up an API proxy and run into configuration issues related to that on a platform you’ve selected, that’s no longer an SDK issue but an integration issue between your application and the service provider.

Events fired but no network requests

If you set the logger to "Debug" level, and see track calls in the developer console, the track() method has been called. If you don't see the corresponding event in Amplitude, the Amplitude Instrumentation Explorer Chrome extension, or the network request tab of the browser, the event wasn't sent to Amplitude. Events are fired and placed in the SDK's internal queue upon a successful track() call, but sometimes these queued events may not send successfully. This can happen when an in-progress HTTP request is cancelled. For example, if you close the browser or leave the page.

There are two ways to address this issue:

1. If you use standard network requests, set the transport to beacon during initialization or set the transport to beacon upon page exit. sendBeacon doesn't work in this case because it sends events in the background, and doesn't return server responses like 4xx or 5xx. As a result, it doesn't retry on failure. sendBeacon sends only scheduled requests in the background. For more information, see the sendBeacon section.

2. To make track() synchronous, add the await keyword before the call.

Advanced topics

Cross-domain tracking

You can track anonymous behavior across two different domains. Amplitude identifies anonymous users by their device IDs which must be passed between the domains. To maintain the same session and ensure a continuous user journey, also pass session IDs to the other domain.

For example:

• Site 1: www.example.com
• Site 2: www.example.org

Users who start on Site 1 and then navigate to Site 2 must have the device ID generated from Site 1 passed as a parameter to Site 2. Site 2 then needs to initialize the SDK with the device ID.
The SDK can parse the URL parameter automatically if deviceId is in the URL query parameters.

Starting from v2.8.0, the SDK can automatically get session ID from the URL to keep the same session and ensure a continuous user journey.

1. From Site 1, grab the device ID from getDeviceId() and the session ID from getSessionId().
2. Pass the device ID and session ID to Site 2 through a URL parameter when the user navigates. (for example: www.example.com?ampDeviceId=device_id_from_site_1&ampSessionId=1716245958483)
3. Initialize the Amplitude SDK on Site 2 with init('API_KEY', null).

If the deviceId and sessionId aren't set in init('API_KEY', null, { deviceId: 'custom-device-id', sessionId: 1716245958483 }), the SDK automatically falls back to using the URL parameters respectively.

Evaluation window with ampTimestamp

To improve security and prevent the use of stale session or device IDs, you can include an ampTimestamp parameter that acts as an evaluation window. The SDK only uses ampSessionId and ampDeviceId URL parameters if the ampTimestamp value is in the future (greater than the current time).

For example:

www.example.com?ampDeviceId=device_id&ampSessionId=session_id&ampTimestamp=1640995500000

When ampTimestamp expires (is less than the current time), the SDK ignores the ampSessionId and ampDeviceId parameters. It falls back to generating new values or using stored values from cookies. If ampTimestamp isn't provided, the SDK behaves as before for backward compatibility.

This feature ensures that cross-domain tracking parameters remain valid only for a limited time window. This prevents potential security issues from long-lived URLs with embedded tracking parameters.

Amplitude recommends that you follow the same session ID format as the Browser SDK using Date.now() because the SDK checks if an event is in session every time it tracks an event. For example:

// if session ID is set to 12345
// https://www.example.com?ampDeviceId=my-device-id&ampSessionId=12345
amplitude.init(API_KEY)
// session ID is set to 12345 after init()

amplitude.track("event")
// session ID is set back to Date.now() 
// because the tracked "event" is not in the previous session 12345

Use sendBeacon

Unlike standard network requests, sendBeacon sends events in the background, even if the user closes the browser or leaves the page.

Set the transport to use sendBeacon for all events

To send an event using sendBeacon, set the transport SDK option to 'beacon' in one of two ways

amplitude.init(API_KEY, 'user@amplitude.com', 
  {
    transport: TransportType.SendBeacon,
    // To make sure the event will be scheduled right away.
    flushIntervalMillis: 0,
    flushQueueSize: 1,
  }
);

Set the transport to use beacon only when exiting page

Amplitude recommends adding your own event listener for pagehide event.

window.addEventListener('pagehide',
  () => {
    amplitude.setTransport('beacon') 
    // Sets https transport to use `sendBeacon` API
    amplitude.flush()
  },
);

Content Security Policy (CSP)

If your web app configures the strict Content Security Policy (CSP) for security concerns, adjust the policy to whitelist the Amplitude domains:

• When using "Script Loader", add https://*.amplitude.com to script-src.
• Add https://*.amplitude.com to connect-src.

Cookie management

The Browser SDK uses cookie storage to persist information that multiple subdomains of the same domain may likely want to share. This includes information like user sessions and marketing campaigns, which are stored in separate cookie entries.

Cookie prefix

• AMP: The SDK creates user session cookies with AMP prefix and the first ten digits of the API key: AMP_{first_ten_digits_API_KEY}.
• AMP_MKTG: The SDK creates marketing campaign cookies with AMP_MKTG and the first ten digits of the API key: AMP_MKTG_{first_ten_digits_API_KEY}.
• AMP_TEST: On initialization, the SDK creates a cookie with AMP_TEST prefix to check whether the cookie storage is working properly. Then the SDK sets the value as the current time, retrieves the cookie by a key and checks if the retrieved value matches the original set time. You can safely delete the AMP_TEST prefix cookies if, for some reason, they're not successfully deleted.
• AMP_TLDTEST: On initialization, the SDK creates a cookie with AMP_TLDTEST prefix to find a subdomain that supports cookie storage. For example, when checking for cookie support on https://analytics.amplitude.com/amplitude/home the SDK first tries to find a subdomain that matches the root domain (amplitude.com) and then falls back to the full domain (analytics.amplitude.com). You can safely delete the AMP_TLDTEST prefix cookies if, for some reason, they're not successfully deleted.

Cookie domain

By default, the SDK assigns these cookies to the top-level domain which supports cookie storage. Cookies can be shared on multiple subdomains which allows for a seamless user experience across all subdomains.

For example, if a user logs into the website on one subdomain (data.amplitude.com) where the SDK is initialized. On initialization, the SDK assigns cookies to .amplitude.com. If the user then navigates to another subdomain (analytics.amplitude.com), the login information can be seamlessly shared by shared cookies.

Cookie data

The SDK creates two types of cookies: user session cookies and marketing campaign cookies.

Disable cookies

Opt-out of using cookies by setting identityStorage to localStorage so that the SDK will use LocalStorage instead. LocalStorage is a great alternative, but because access to LocalStorage is restricted by subdomain, you can't track anonymous users across subdomains of your product (for example: www.amplitude.com vs analytics.amplitude.com).

amplitude.init("api-key", null, {
  identityStorage: "localStorage",
});

Offline mode

Beginning with version 2.4.0, the Amplitude Browser SDK supports offline mode. The SDK checks network connectivity every time it tracks an event. If the device is connected to network, the SDK schedules a flush. If not, it saves the event to storage. The SDK also listens for changes in network connectivity and schedules a flush of all stored events when the device reconnects, based on the config.flushIntervalMillis setting.

To disable offline mode, add offline: amplitude.Types.OfflineDisabled to the amplitude.init() call as shown below.

amplitude.init(AMPLITUDE_API_KEY, {
  offline: amplitude.Types.OfflineDisabled
});

Marketing Attribution Tracking

Amplitude tracks marketing attribution and excludes all referrers from subdomains by default. Learn more about exclude referrers. Once you enable marketing attribution tracking, Amplitude generates identify events to assign the campaign values as user properties in specific scenarios. Refer to the following section to learn when Amplitude tracks marketing attribution and updates user properties.

Tracking scenarios

Amplitude tracks changes in marketing attribution in two scenarios: during SDK initialization and event processing.

Amplitude SDK initialization (Hard page refresh)

• At the start of a session, the referrer isn't excluded and campaign has any change or customer first visit.
• In the middle of the session, the referrer isn't excluded, not direct traffic, and campaign has any change.

To debug, you can get the referrer by typing document.referrer in your Browser console and compare it with your config.autocapture.attribution.excludeReferrers. If document.referrer is empty, then it's considered as a direct traffic. You can get the session ID under AMP_{last 10 digits of your API key} on the "Cookies" tab of the Ampitude Chrome extension and get the previous campaign stored under AMP_MKTG_{last 10 digits of your API key}.

Processing the event

• At the start of a session, the referrer isn't excluded, and campaign has any change.

For more information, see the scenarios outlined below that demonstrate when Amplitude does or doesn't track marketing attribution. These examples are illustrative, not exhaustive.

Tracking occurs when either of the following applies:

Amplitude doesn't track marketing attribution under any of the following conditions:

Rogue referral problem for SPAs

SPA typically don't experience a true page load after a visitor enters the site, which means the referrer information doesn't update when clicking internal links. UTM parameters may be dropped during SPA redirects, while the referrer remains unchanged. This is a known issue in the industry. To address this problem, you can either:

• Control the page and location parameters and / or
• Unset the referrer after the first hit

Remote configuration

Beginning with version 2.10.0, the Amplitude Browser SDK supports remote configuration. By default, the SDK disables this feature.

Autocapture supports remote configuration options for tracking default events. When you enable this setting, the remote configuration overrides your client-side configuration. Find the remote configuration options in Data > Settings > Autocapture.

To enable remote config, add fetchRemoteConfig: true to the amplitude.init() call as shown below.

amplitude.init(AMPLITUDE_API_KEY, {
  fetchRemoteConfig: true
});

In Amplitude, navigate to Data > Settings > Autocapture to add or update a remote configuration.

Proxy remote config requests

To proxy remote configuration requests through your own server (for example, to bypass ad blockers), configure the remoteConfig option:

amplitude.init(AMPLITUDE_API_KEY, {
  remoteConfig: {
    serverUrl: 'https://your-proxy.example.com/config'
  }
});

When remoteConfig.serverUrl is set, the SDK sends remote configuration requests to your custom URL instead of Amplitude's endpoints. Analytics events still use serverUrl or the default Amplitude endpoints.