@amplitude/analytics-browser

What is @amplitude/analytics-browser?

@amplitude/analytics-browser is an npm package that allows you to integrate Amplitude's analytics capabilities into your web applications. It provides tools for tracking user events, managing user identities, and setting up custom properties to gain insights into user behavior.

What are @amplitude/analytics-browser's main functionalities?

Initialize Amplitude

This feature allows you to initialize the Amplitude analytics instance with your API key, which is necessary to start tracking events.

const amplitude = require('@amplitude/analytics-browser');
amplitude.init('YOUR_API_KEY');

Track Events

This feature allows you to track specific events within your application. In this example, a 'Button Clicked' event is tracked with an additional property 'buttonName'.

amplitude.track('Button Clicked', { buttonName: 'Sign Up' });

Identify Users

This feature allows you to identify users and set user properties. In this example, a user with ID 'user123' is identified and a custom property 'plan' is set to 'premium'.

amplitude.identify({ userId: 'user123', userProperties: { plan: 'premium' } });

Set User Properties

This feature allows you to set custom properties for a user. In this example, the user's age and gender are set.

amplitude.setUserProperties({ age: 30, gender: 'female' });

Log Revenue

This feature allows you to log revenue events. In this example, a revenue event is logged with an amount of 10.99 for product 'product_123' with a quantity of 1.

amplitude.logRevenue(10.99, 'product_123', 1);

Other packages similar to @amplitude/analytics-browser

mixpanel-browser

Mixpanel is another popular analytics tool that provides similar functionalities to Amplitude. It allows you to track user interactions, manage user identities, and set custom properties. Mixpanel also offers advanced features like A/B testing and user segmentation.

google-analytics

Google Analytics is a widely-used web analytics service that tracks and reports website traffic. While it offers extensive tracking and reporting capabilities, it is more focused on web traffic analysis compared to the user-centric approach of Amplitude.

README

@amplitude/analytics-browser

Official Amplitude SDK for Web

Doc

See our Analytics SDK for Browser Reference for a list and description of all available SDK methods.

Installation and Quick Start

Please visit our :100:Developer Center for instructions on installing and using our the SDK.

Installation

To get started with using Amplitude Browser SDK, install the package to your project via NPM or script loader.

Using Node package

This package is published on NPM registry and is available to be installed using npm and yarn.

# npm
npm install @amplitude/analytics-browser@^1.0.0

# yarn
yarn add @amplitude/analytics-browser@^1.0.0

Using script loader

Alternatively, the package is also distributed through a CDN. Copy and paste the script below to your html file.

<script type="text/javascript">
!function(){"use strict";!function(e,t){var r=e.amplitude||{_q:[],_iq:{}};if(r.invoked)e.console&&console.error&&console.error("Amplitude snippet has been loaded.");else{var n=function(e,t){e.prototype[t]=function(){return this._q.push({name:t,args:Array.prototype.slice.call(arguments,0)}),this}},s=function(e,t,r){return function(n){e._q.push({name:t,args:Array.prototype.slice.call(r,0),resolve:n})}},o=function(e,t,r){e._q.push({name:t,args:Array.prototype.slice.call(r,0)})},i=function(e,t,r){e[t]=function(){if(r)return{promise:new Promise(s(e,t,Array.prototype.slice.call(arguments)))};o(e,t,Array.prototype.slice.call(arguments))}},a=function(e){for(var t=0;t<m.length;t++)i(e,m[t],!1);for(var r=0;r<g.length;r++)i(e,g[r],!0)};r.invoked=!0;var c=t.createElement("script");c.type="text/javascript",c.integrity="sha384-13liHy/amJs88O/3yvSCfGXXV3GIuXMuw20wF1HfdJajWXKlvXrc8KptSKqEnLVt",c.crossOrigin="anonymous",c.async=!0,c.src="https://cdn.amplitude.com/libs/analytics-browser-1.13.5-min.js.gz",c.onload=function(){e.amplitude.runQueuedFunctions||console.log("[Amplitude] Error: could not load SDK")};var u=t.getElementsByTagName("script")[0];u.parentNode.insertBefore(c,u);for(var l=function(){return this._q=[],this},p=["add","append","clearAll","prepend","set","setOnce","unset","preInsert","postInsert","remove","getUserProperties"],d=0;d<p.length;d++)n(l,p[d]);r.Identify=l;for(var f=function(){return this._q=[],this},v=["getEventProperties","setProductId","setQuantity","setPrice","setRevenue","setRevenueType","setEventProperties"],y=0;y<v.length;y++)n(f,v[y]);r.Revenue=f;var m=["getDeviceId","setDeviceId","getSessionId","setSessionId","getUserId","setUserId","setOptOut","setTransport","reset"],g=["init","add","remove","track","logEvent","identify","groupIdentify","setGroup","revenue","flush"];a(r),r.createInstance=function(e){return r._iq[e]={_q:[]},a(r._iq[e]),r._iq[e]},e.amplitude=r}}(window,document)}();

amplitude.init("YOUR_API_KEY_HERE");
</script>

Usage

Initializing SDK

Initialization is necessary before any instrumentation is done. The API key for your Amplitude project is required.

amplitude.init(API_KEY);

Tracking an Event

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

import { track } from '@amplitude/analytics-browser';

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

// Track events with additional properties
const eventProperties = {
  selectedColors: ['red', 'blue'],
};
track('Button Clicked', eventProperties);

User Properties

User properties help you understand your users at the time they performed some action within your app such as their device details, their preferences, or language.

import { Identify, identify } from '@amplitude/analytics-browser';

const event = new Identify();

// sets the value of a user property
event.set('key1', 'value1');

// sets the value of a user property only once
event.setOnce('key1', 'value1');

// increments a user property by some numerical value.
event.add('value1', 10);

// pre inserts a value or values to a user property
event.preInsert('ab-tests', 'new-user-test');

// post inserts a value or values to a user property
event.postInsert('ab-tests', 'new-user-test');

// removes a value or values to a user property
event.remove('ab-tests', 'new-user-test')

// sends identify event
identify(event);

prepend/append

• append will append a value or values to a user property array.
• prepend will prepend a value or values to a user property.

User Groups

import { setGroup } from '@amplitude/analytics-browser';

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

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

Group Identify

This feature is only available to Growth and Enterprise customers who have purchased the Accounts add-on.

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

import { Identify, groupIdentify } from '@amplitude/analytics-browser';

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

groupIdentify(groupType, groupName, identity);

Track Revenue

Revenue instances will store each revenue transaction and allow you to define several special revenue properties (such as 'revenueType', 'productIdentifier', etc.) 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 allows us to automatically display data relevant to revenue in the platform. You can use this to track both in-app and non-in-app purchases.

import { Revenue, revenue } from '@amplitude/analytics-browser';

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

revenue(event);

Callback

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

// Using async/await
const results = await 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)

// Using promises
track('Button Clicked').promise.then((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)
});

User Log out

This updates user ID and device ID. After calling reset() the succeeding events now belong to a new user identity.

import { reset } from '@amplitude/analytics-browser';

reset();