Browser SDK

The Browser SDK lets you send events to Amplitude. This library is open-source, check it out on GitHub.

Getting started¶

Use this quickstart guide to get started with Amplitude Browser SDK.

Usage¶

Initialize the SDK¶

You must initialize the SDK before you can instrument any events. Your Amplitude project's API key is required. You can pass an optional user ID and config object in this call. You can use the SDK anywhere after it's initialized anywhere in an application.

// Option 1, initialize with API_KEY only
amplitude.init(API_KEY);

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

// Option 3, initialize with configuration
amplitude.init(API_KEY, 'user@amplitude.com', options);

Configuration¶

In addition to the basic configuration options, there also has options to configure attribution.

Configure batching behavior¶

To support high-performance environments, the SDK sends events in batches. Every event logged by the track method is queued in memory. Events are flushed in batches in background. You can customize batch behavior with flushQueueSize and flushIntervalMillis. By default, the serverUrl will be https://api2.amplitude.com/2/httpapi. For customers who want to send large batches of data at a time, set useBatch to true to set setServerUrl to batch event upload API https://api2.amplitude.com/batch. Both the regular mode and the batch mode use the same events upload threshold and flush time intervals.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  // Events queued in memory will flush when number of events exceed upload threshold
  // Default value is 30
  flushQueueSize: 50, 
  // Events queue will flush every certain milliseconds based on setting
  // Default value is 10000 milliseconds
  flushIntervalMillis: 20000,
  // Using batch mode with batch API endpoint, `https://api2.amplitude.com/batch`
  useBatch: true
});

EU data residency¶

You can configure the server zone when initializing the client for sending data to Amplitude's EU servers. The SDK sends data based on the server zone if it's set.

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

Debugging¶

You can control the level of logs printed to the developer console.

• 'None': Suppresses all log messages.
• 'Error': Shows error messages only.
• 'Warn': Shows error messages and warnings. This is the default value if logLevel isn't explicitly specified.
• 'Verbose': Shows informative messages.
• 'Debug': Shows error messages, warnings, and informative messages that may be useful for debugging, including the function context information for all SDK public method invocations. This logging mode is only suggested to be used in development phases.

Set the log level by configuring the logLevel with the level you want.

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 will be output to the developer console when invoking any SDK public method, including:

• 'type': Category of this context, e.g., "invoke public method".
• 'name': Name of invoked function, e.g., "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.

Tracking an event¶

Events represent how users interact with your application. For example, "Button Clicked" may be an action you want to note.

// 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 the track function. Refer to 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);

Tracking events to multiple projects¶

If you need to log events to multiple Amplitude projects, you'll need to create separate instances for each Amplitude project. Then, pass the instance variables to wherever you want to call Amplitude. Each instance allows for independent apiKeys, userIds, deviceIds, and settings.

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

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

Tracking default events¶

Starting version 1.9.1, Browser SDK now tracks default events. Browser SDK can be configured to track the following events automatically:

• Page views ¹
• Sessions
• Form interactions
• File downloads

You can enable Amplitude to start tracking all events mentioned above, use the code sample below. Otherwise, you can omit the configuration to keep them disabled.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    pageViews: true,
    sessions: true,
    formInteractions: true,
    fileDownloads: true,
  },
});

Alternatively, you can enable Amplitude to track all events mentioned above by setting config.defaultTracking to true.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: true,
});

Tracking page views¶

You can enable Amplitude to start tracking page view events by setting config.defaultTracking.pageViews to true. Refer to the code sample below.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    pageViews: true,
  },
});

By setting config.defaultTracking.pageViews to true, you enable Amplitude to use default page view tracking behavior. The default behavior sends a page view event on initialization. The event type for this event is "[Amplitude] Page Viewed".

Advanced configuration for tracking page views¶

You can also use advanced configuration for better control of when page view events are sent.

For example, you can configure Amplitude to track page views only when the URL path contains a certain substring, let’s say “home”. Refer to the code sample for how to achieve this.

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

The following information is tracked in the page view events.

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

Tracking sessions¶

You can enable Amplitude to start tracking session events by setting config.defaultTracking.sessions to true. Refer to the code sample below.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    sessions: true,
  },
});

By setting config.defaultTracking.sessions to true, you enable Amplitude to track session start and session end events. 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 is and is the first event of the session. The event type for session start is "[Amplitude] Start Session". When an existing session ends, a session start end is tracked and is the last event of the session. The event type for session end is "[Amplitude] End Session".

Tracking form interactions¶

You can enable Amplitude to start tracking form interaction events by setting config.defaultTracking.formInteractions to true. Refer to the code sample below.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    formInteractions: true,
  },
});

By setting config.defaultTracking.formInteractions to true, you enable Amplitude to track form start and form submit events. A form start event is tracked when the user initially interacts with the form. An initial interaction can be the first change to a text input, radio button, or dropdown. The event type for session start is "[Amplitude] Form Started". A form submit event is tracked when the user submits the form. The event type for session start is "[Amplitude] Form Submitted". If a form is submitted with no initial change to any form fields, both "[Amplitude] Form Started" and "[Amplitude] Form Submitted" are tracked.

Amplitude can track forms that are 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>

Tracking file downloads¶

You can enable Amplitude to start tracking file download events by setting config.defaultTracking.fileDownloads to true. Refer to the code sample below.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  defaultTracking: {
    fileDownloads: true,
  },
});

By setting config.defaultTracking.fileDownloads to true, you enable Amplitude to track file download events. A file download event is tracked when an anchor or <a> tag linked to a file is clicked. The event type for file download is "[Amplitude] File Downloaded". 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

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 via 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 over setting user properties. It works like this: first, instantiate an Identify object, then call Identify methods on it, and finally, the client can make a call with the Identify object.

const identifyEvent = new amplitude.Identify();
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', 'LAX');

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 and because only the initial value is tracked, setOnce() ignores later calls.

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

identify(identifyEvent);

Identify.add¶

This method increments a user property by some 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¶

You can use arrays as user properties. Directly set arrays or use prepend, append, preInsert and postInsert to generate an array.

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.preInsert¶

This method pre-inserts a value or values to a user property if it doesn't exist in the user property yet. Pre-insert means inserting the values at the beginning 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 pre-inserted. If the user property has an existing value, this method is a no-op.

const identifyEvent = new amplitude.Identify();
identifyEvent.preInsert('unique-locations', 'LAX');

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 indicate 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']);

You can also set event-level groups by passing an Event Object with groups to track. With event-level groups, the group designation applies only to the specific event being logged, and doesn't persist on 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);

Revenue tracking¶

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 (such as '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, 3 units of a product were purchased 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, flush is called automatically in an interval, if you want to flush the events altogether, you can 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 ID¶

If your app has its login system that you want to track users with, you can call setUserId at any time.

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

You can also assign the User ID as an argument to the init call.

amplitude.init(API_KEY, 'user@amplitude.com');

Custom session ID¶

You can assign a new Session ID using setSessionId. When setting a custom session ID, make sure the value is in milliseconds since epoch (Unix Timestamp).

amplitude.setSessionId(Date.now());

Custom device ID¶

If your app has its login system that you want to track users with, you can call setUserId at any time.

You can assign a new device ID using deviceId. When setting a custom device ID, make sure the value is sufficiently unique. Amplitude recommends using a UUID.

amplitude.setDeviceId(uuid());

Reset when user logs out¶

reset is a shortcut to anonymize users after they log out, by:

• setting userId to undefined
• setting deviceId to a new UUID value

With an undefined userId and a completely new deviceId, the current user would appear as a brand new user in dashboard.

amplitude.reset();

Opt users out of tracking¶

You can turn off logging for a given user by setting setOptOut to true.

amplitude.setOptOut(true);

Events aren't saved or sent to the server while setOptOut is enabled, and the setting persists across page loads.

Re-enable logging by setting setOptOut to false.

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(API_KEY, OPTIONAL_USER_ID, {
  trackingOptions: {
    deviceManufacturer: false,
    deviceModel: false,
    ipAddress: false,
    language: false,
    osName: false,
    osVersion: 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(result) { 
  // 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 type) or sending to third-party APIs (destination type). A plugin is an object with methods setup() and execute().

add¶

The add method adds a plugin to Amplitude. Plugins can help processing and sending events.

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 your custom plugin¶

Plugin.setup¶

This method contains logic for preparing the plugin for use and has config as a parameter. The expected return value is undefined. A typical use for this method, is to copy configuration from config or instantiate plugin dependencies. This method is called when the plugin is registered to the client via amplitude.add().

Plugin.execute¶

This method contains the logic for processing events and has event as parameter. If used as enrichment type plugin, the expected return value is the modified/enriched event. If used as a destination type plugin, the expected return value is a map with keys: event (BaseEvent), code (number), and message (string). This method is called for each event that's instrumented using the client interface, including Identify, GroupIdentify and Revenue events.

Plugin examples¶

Destination type plugin¶

Here's an example of a plugin that sends each event that's instrumented to a target server URL using your preferred HTTP client.

function myDestinationPlugin (serverUrl) {
  const name = 'my-destination-plugin';
  const type = amplitude.Types.PluginType.DESTINATION;
  let amplitudeConfig;

  /**
   * setup() is called on plugin installation
   * example: amplitude.add(new myDestinationPlugin());
   */
  const setup = function (config) {
    amplitudeConfig = config;
  }

  /**
   * execute() is called on each event instrumented
   * example: amplitude.track('New Event');
   */
  const execute = function (event) {
    const payload = {
      key: 'secret',
      data: event,
    };
    return fetch(this.serverUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Accept: '*/*',
      },
      body: JSON.stringify(payload),
    }).then(function(response) {
      return {
        code: response.status,
        event: event,
        message: response.statusText,
      };
    });
  }

  return {
    name,
    type,
    setup,
    execute,
  },
}

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

Enrichment type plugin¶

Here's an example of a plugin that modifies each event that's instrumented by adding an increment integer to event_id property of an event starting from 100.

const addEventIdPlugin = () => {
  const name = 'add-event-id';
  const type = amplitude.Types.PluginType.ENRICHMENT;
  let currentId = 100;
  let amplitudeConfig;

  /**
   * setup() is called on plugin installation
   * example: amplitude.add(new AddEventIdPlugin());
   */
  const setup = function (config) {
    amplitudeConfig = config;
  }

  /**
   * execute() is called on each event instrumented
   * example: client.track('New Event');
   */
  const execute = function (event: Event) {
    event.event_id = currentId++;
    return event;
  }

  return {
    name,
    type,
    setup,
    execute,
  }
}

amplitude.init(API_KEY);
amplitude.add(addEventIdPlugin());

Web attribution enrichment plugin¶

You need to download plugin-web-attribution-browser package and add the webAttributionPlugin before call init method.

npm install @amplitude/plugin-web-attribution-browser

yarn add @amplitude/plugin-web-attribution-browser

Add plugin to Amplitude instance.

amplitude.add(webAttributionPlugin());
amplitude.init(API_KEY);

See the configuration options. Learn more about what the Web Attribution Plugin supports.

Differences from base SDK¶

Enabling the Attribution plugin overwrites the default attribution tracking behavior of the SDK.

The SDK’s built in attribution tracking only tracks attribution at the start of sessions. This mean if a user re-enters the site through a new campaign channel (such as direct or an ad) in the middle of a session, this new channel isn't recorded.

If the trackNewCampaigns option is set to true, the campaigns are tracked, and the user’s session is reset when a new campaign is detected.

The Attribution plugin tracks all campaigns, regardless of whether the user is at the start of a session.

Set the resetSessionOnNewCampaign option to true to cause the user’s session to be reset when a new campaign is detected. The session isn't reset in the case where the referrer is just a different subdomain of your site.

Page view enrichment plugin¶

You need to download plugin-page-view-tracking-browser and add the pageViewTrackingPlugin before calling the init method.

npm install @amplitude/plugin-page-view-tracking-browser

yarn add @amplitude/plugin-page-view-tracking-browser

Add plugin to Amplitude instance.

amplitude.add(pageViewTrackingPlugin());
amplitude.init(API_KEY);

See the configuration options. Learn more about what the Page View Plugin supports.

Differences from base SDK¶

The base SDK sends Page View events when a user’s campaign is tracked if the attribution.trackPageViews option is set to true.

The page view plugin sends a Page View event on each page a user visits by default. It also offers options to customize this behavior.

Troubleshooting and Debugging¶

How to debug¶

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 are not using the correct amplitude instance during initialization. Therefore, please check your implementation."

Network Request¶

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

Please 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.

Check here for more details.

Common Issues¶

The following are common issues specific to Browser SDK. For additional general common issues, please refer to this document.

AD Blocker¶

Ad Blocker might lead to event dropping. The following errors indicate that the tracking has been affected by Ad Blocker. When loading via 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 are not listed. Not sure if it’s possible to show them.

We recommend 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. So, if these values are not persistent or are not 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 is not 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. 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.

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

If the deviceId isn't provided with the init like init('API_KEY', null, { deviceId: 'custom-device-id' }), then it automatically fallbacks to using the URL parameter.

Custom HTTP client¶

You can provide an implementation of Transport interface to the transportProvider configuration option for customization purpose, for example, sending requests to your proxy server with customized HTTP request headers.

class MyTransport {
  send(serverUrl, payload) {
    // check example: https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/analytics-client-common/src/transports/fetch.ts
  }
}

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  transportProvider: new MyTransport(),
});

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_TDLTEST: On initialization, the SDK creates a cookie with AMP_TDLTEST 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_TDLTEST 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¶

You can opt-out of using cookies by setting disableCookies to true 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).

Device ID lifecycle¶

The SDK initializes the device ID in the following order, with the device ID being set to the first valid value encountered:

1. Device id in configuration on initialization
2. "deviceId" value from URL param, for example http://example.com/?deviceId=123456789. Refer to cross domain tracking for more details
3. Device id in cookie storage. Refer to cookie management for more details
4. Device id in cookie storage of Browser SDK. Refer to cookie management for more details
5. A randomly generated 36-character UUID

When does a device ID change¶

A device ID changes in many scenarios:

• setDeviceId() is called explicitly

• By default the SDK stores device IDs in cookies, so a device ID will change if a user clears cookies, uses another device, or uses privacy mode

• On initialization, a device ID is passed in from URL param deviceId
• reset() is called

Custom device ID¶

You can assign a new device ID using setDeviceId(). When setting a custom device ID, make sure the value is sufficiently unique. Amplitude recommends using a UUID.

amplitude.setDeviceId(uuid());

Get device ID¶

You can use the helper method getDeviceId() to get the value of the current deviceId.

const deviceId = amplitude.getDeviceId();