This article describes all the available SDK methods for Amplitude's JavaScript SDK. The variables and values in red are what you will need to replace with your own. Please see the JavaScript SDK Installation documentation for instructions on how to install the SDK.
For additional information regarding the Amplitude JavaScript SDK, please feel free to check out our Developers Centre here.
Table of Contents
Class: Amplitude
Most of the methods in this class have been deprecated, and this class is just a wrapper that manages multiple amplitude-client instances for you. SDK methods are called by first fetching an instance and then calling the appropriate amplitude-client method (e.g. amplitude.getInstance().logEvent("EVENT_TYPE");). More information about instances and logging events to multiple Amplitude API keys can be found here. More information about this class can be found here.
Type Definitions
eventCallback(responseCode, responseBody)
This is the callback for logEvent and identify calls. It gets called after the event/identify call is uploaded, and the server response code and response body from the upload request are passed to the callback function.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
number | The server response code for the event/identify upload request. |
|
|
string |
The server response body for the event/ |
Source: amplitude.js
eventCallback(responseCode, responseBody)
This is the callback for logEvent and identify calls. It gets called after the event/identify call is uploaded, and the server response code and response body from the upload request are passed to the callback function.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
number | The server response code for the event/identify upload request. |
|
|
string |
The server response body for the event/ |
Source: amplitude-client.js
Class: AmplitudeClient
AmplitudeClient
AmplitudeClient SDK API - instance constructor. The Amplitude class handles creation of client instances. All you need to do is call amplitude.getInstance().
Source: amplitude-client.js
Example:
var amplitudeClient = new AmplitudeClient();
Members
The example shows how to get the current version of Amplitude's JavaScript SDK.
Source: amplitude-client.js
Example:
var amplitudeVersion = amplitude.__VERSION__;
Methods
1. clearUserProperties()
Clear all of the user properties for the current user. This will wipe all of the user's user properties and reset them. Note: Clearing user properties is irreversible! Amplitude will not be able to sync the user's user property values before the wipe to any future events that the user triggers as they will have been reset.
Source: amplitude-client.js
Example:
amplitudeClient.clearUserProperties();
2. getSessionId()
Returns the ID of the current session.
Source: amplitude-client.js
Returns: ID of the current session of type number.
3. identify(identify_obj, opt_callback)
Send an identify call containing user property operations to Amplitude servers. See the JavaScript SDK Installation documentation for more information.
Parameters:
| Name | Type | Description |
|---|---|---|
|
(required) |
Identify | The Identify object containing the user property operations to send. |
|
(optional) |
Amplitude~eventCallback |
Callback function to run when the |
Source: amplitude-client.js
Example:
var identify = new amplitude.Identify().set('colors', ['rose', 'gold']).add('karma', 1).setOnce('sign_up_date', '2016-03-31');
amplitude.identify(identify);
4. init(apiKey, opt_userId, opt_config, opt_callback)
Initializes the Amplitude JavaScript SDK with your apiKey and any optional configurations. This is required before any other methods can be called.
Parameters:
| Name | Type | Description |
|---|---|---|
|
(required) |
string | The API Key for your project. |
|
(optional) |
string |
An identifier for this user. |
|
(optional) |
object |
Configuration options. See the JavaScript SDK documentation for a list of options and the default values. |
|
(optional) |
function |
Provide a callback function to run after initialization is complete. |
Source: amplitude-client.js
Example:
amplitudeClient.init('API_KEY', 'USER_ID', {includeReferrer: true, includeUtm: true}, function() { alert('init complete');});
5. onInit(callback)
Allows for a callback to be called immediately after init before any queued up events are logged. This is useful for sending identify calls from integrations before any events that your application logs.
Parameters:
| Name | Type | Description |
|---|---|---|
|
(required) |
function | The callback to be invoked after init. |
6. isNewSession()
Returns true if a new session was created during initialization, otherwise false.
Source: amplitude-client.js
Returns: Whether a new session was created during initialization as type boolean.
7. logEvent(eventType, eventProperties, opt_callback)
Log an event with eventType and eventProperties.
Parameters:
| Name | Type | Description |
|---|---|---|
|
(required) |
string | The name of the event. |
|
(optional) |
object |
An object with string keys and values for the event properties. |
|
(optional) |
Amplitude~eventCallback |
A callback function to run after the event is logged. Note: The server response code and response body from the event upload are passed to the callback function. |
Source: amplitude-client.js
Example:
amplitudeClient.logEvent('Clicked Homepage Button', {'finished_flow': false, 'clicks': 15});
8. logEventWithTimestamp(eventType, eventProperties, timestamp, opt_callback)
Log an event with eventType, eventProperties, and a custom timestamp.
Parameters:
| Name | Type | Description |
|---|---|---|
|
(required) |
string | The name of the event. |
|
(optional) |
object |
An object with string keys and values for the event properties. |
|
(optional) |
number |
The custom timestamp as milliseconds since epoch. |
|
(optional) |
Amplitude~eventCallback |
A callback function to run after the event is logged. Note: The server response code and response body from the event upload are passed to the callback function. |
Source: amplitude-client.js
Example:
amplitudeClient.logEventWithTimestamp('Clicked Homepage Button', {'finished_flow': false, 'clicks': 15}, 1545041372000);
9. logRevenueV2(revenue_obj)
Log revenue with the revenue interface. The new revenue interface allows for more revenue fields like 'revenueType' and event properties. See the SDK documentation for more information on the Revenue interface and logging revenue.
| Name | Type | Description |
|---|---|---|
|
|
Revenue | The revenue object containing the revenue data being logged. |
Source: amplitude-client.js
Example:
var revenue = new amplitude.Revenue().setProductId('productIdentifier').setPrice(10.99);
amplitude.logRevenueV2(revenue);
10. regenerateDeviceId()
Regenerates a new random deviceId for the current user. Note: This is not recommended unless you know what you are doing. This can be used in conjunction with setUserId(null) to anonymize users after they log out. The current user would appear as a brand new user in Amplitude if they have a null userId and a completely new deviceId. This uses src/uuid.js to regenerate the deviceId.
Source: amplitude-client.js
11. setDeviceId(deviceId)
Sets a custom deviceId for the current user. Note: This is not recommended unless you know what you are doing (e.g. you have your own system for managing deviceIds). Make sure the deviceId you set is sufficiently unique (we recommend something like a UUID - see src/uuid.js for an example of how to generate) to prevent conflicts with other devices in our system.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
Custom |
Source: amplitude-client.js
Example:
amplitudeClient.setDeviceId('45f0954f-eb79-4463-ac8a-233a6f45a8f0');
12. setDomain(domain)
Sets a custom domain for the Amplitude cookie. This is useful if you want to support cross-subdomain tracking.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The custom domain to set. |
Source: amplitude-client.js
Example:
amplitudeClient.setDomain('.amplitude.com');
13. setGroup(groupType, groupName)
Add a user to a group or groups. You will need to specify a groupType and groupName(s). For example, you can group people by their organization, in which case their groupType could be 'orgId' and their groupName would be the actual ID(s). groupName can be a string or an array of strings to indicate that a user is in multiple groups. You can also call setGroup multiple times with different groupTypes to track multiple types of groups (up to five per app). Note: This will also set 'groupType:groupName' as a user property. See the SDK installation documentation for more information.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The group type (e.g. 'orgId). |
|
|
string or list |
The name of the group (e.g. '15') or a list of names of the groups. |
Source: amplitude-client.js
Example:
amplitudeClient.setGroup('orgId', 15); // This adds the current user to 'orgId' 15
14. setOptOut(enable)
Sets whether to opt current user out of tracking.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
boolean |
If true, then no events will be logged or sent. |
Source: amplitude-client.js
15. setUserId(userId)
Sets an identifier for the current user.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The identifier to set. This can be |
Source: amplitude-client.js
Example:
amplitudeClient.setUserId('joe@gmail.com');
16. setUserProperties(userProperties)
Sets user properties for the current user.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
object |
The identifier to set. This can be |
|
(deprecated) |
boolean | In earlier versions of the JavaScript SDK the user properties object was kept in memory and setting this to true would replace the object in memory. Now, the properties are no longer stored in memory so this parameter has been deprecated. |
Source: amplitude-client.js
Example:
amplitudeClient.setUserProperties({'gender': 'female', 'sign_up_complete': true})
17. setVersionName(versionName)
Set a versionName for your application.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The version to set for your application. |
Source: amplitude-client.js
Example:
amplitudeClient.setVersionName('1.12.3');
18. setSessionId(sessionId)
Set a custom Session ID for the current session. Note: This is not recommended unless you know what you are doing because the Session ID of a session is utilized for all session metrics in Amplitude.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
int |
The Session ID to set for the current session. IMPORTANT NOTE: This must be in milliseconds since epoch (Unix Timestamp). |
Source: amplitude-client.js
Example:
amplitudeClient.setSessionId(1505430378000);
Class: Identify
Identify
new Identify()
Identify API - instance constructor. Identify objects are a wrapper for user property operations. Each method adds a user property operation to the Identify object and returns the same Identify object, allowing you to chain multiple method calls together. Note: If the same user property is used in multiple operations on a single Identify object, only the first operation on that property will be saved and the rest will be ignored. See the JavaScript SDK Installation documentation for more information on the Identify API and user property operations.
Source: identify.js
Example:
var identify = new amplitude.Identify();
Methods
1. add(property, value)
Increment a user property by a given value. To decrement, pass in a negative value. If the user property does not have a value set yet, it will be initialized to zero before being incremented.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The user property key. |
|
|
number | string | The amount by which to increment the user property. Allows numbers as strings (e.g. '123'). |
Source: identify.js
Returns: Returns the same Identify object of type Identify, allowing you to chain multiple method calls together.
Example:
var identify = new amplitude.Identify().add('karma', 1).add('friends', 1); amplitude.identify(identify); // Send the Identify call
2. append(property, value)
Append a value or values to a user property. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are appended. If the user property has an existing value and it is not a list, the existing value will be converted into a list with the new values appended.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The user property key. |
|
|
number | string | list | object | A value or values to append. Values can be numbers, strings, lists, or objects. Key + value dictionaries will be flattened. |
Source: identify.js
Returns: Returns the same Identify object of type Identify, allowing you to chain multiple method calls together.
Example:
var identify = new amplitude.Identify().append('ab-tests', 'new-user-tests'); identify.append('some_list', [1, 2, 3, 4, 'values']); amplitude.identify(identify); // Send the Identify call
3. prepend(property, value)
Prepend a value or values to a user property. Prepend means inserting the value or values at the front of a list. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are prepended. If the user property has an existing value and it is not a list, the existing value will be converted into a list with the new values prepended.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The user property key. |
|
|
number | string | list | object | A value or values to prepend. Values can be numbers, strings, lists, or objects. Key + value dictionaries will be flattened. |
Source: identify.js
Returns: Returns the same Identify object of type Identify, allowing you to chain multiple method calls together.
Example:
var identify = new amplitude.Identify().prepend('ab-tests', 'new-user-tests'); identify.prepend('some_list', [1, 2, 3, 4, 'values']); amplitude.identify(identify); // Send the Identify call
4. set(property, value)
Sets the value of a given user property. If a value already exists, it will be overwritten with the new value.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The user property key. |
|
|
number | string | list | object | A value or values to set. Values can be numbers, strings, lists, or objects. Key + value dictionaries will be flattened. |
Source: identify.js
Returns: Returns the same Identify object of type Identify, allowing you to chain multiple method calls together.
Example:
var identify = new amplitude.Identify().set('user_type', 'beta'); identify.set('name', {'first': 'John', 'last': 'Doe'}); // dictionary is flattened and becomes name.first: John, name.last: Doe amplitude.identify(identify); // Send the Identify call
5. setOnce(property, value)
Sets the value of a given user property only once. Subsequent setOnce operations on that user property will be ignored. However, that user property can still be modified through any of the other operations. This is useful for capturing user properties such as 'initial_signup_date' and 'initial_referrer'.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The user property key. |
|
|
number, string, list, object | A value or values to set. Values can be numbers, strings, lists, or objects. Key + value dictionaries will be flattened. |
Source: identify.js
Returns: Returns the same Identify object of type Identify, allowing you to chain multiple method calls together.
Example:
var identify = new amplitude.Identify().setOnce('sign_up_date', '2016-04-01'); amplitude.identify(identify); // send the Identify call
6. unset(property)
Unsets, and removes a user property value. The user property will be null in the user's profile.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The user property key. |
Source: identify.js
Returns: Returns the same Identify object of type Identify, allowing you to chain multiple method calls together.
Example:
var identify = new amplitude.Identify().unset('user_type').unset('age'); amplitude.identify(identify); // Send the Identify call
Class: Revenue
Revenue
new Revenue()
Revenue API - instance constructor. Revenue objects are a wrapper for revenue data. Each method updates a revenue property in the Revenue object and returns the same Revenue object, allowing you to chain multiple method calls together. Note: Price is a required field to log revenue events. If the quantity is not specified, then this will default to 1. See the JavaScript SDK Installation for more information about logging revenue.
Source: revenue.js
Example:
var revenue = new amplitude.Revenue();
Methods
1. setEventProperties(eventProperties)
Set event properties for the revenue event.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
object |
Revenue event properties to set. |
Source: revenue.js
Returns: Returns the same Revenue object of type Revenue, allowing you to chain multiple method calls together.
Example:
var event_properties = {'city': 'San Francisco'}; var revenue = new amplitude.Revenue().setProductId('productIdentifier').setPrice(10.99).setEventProperties(event_properties); amplitude.logRevenueV2(revenue);
2. setPrice(price)
Set a value for the price. This field is required for all revenue events being logged. Note: The revenue amount is calculated as price * quantity.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
number |
Double value for the quantity. |
Source: revenue.js
Returns: Returns the same Revenue object of type Revenue, allowing you to chain multiple method calls together.
Example:
var revenue = new amplitude.Revenue().setProductId('productIdentifier').setPrice(10.99); amplitude.logRevenueV2(revenue);
3. setProductId(productId)
Set a value for the product identifier.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The value for the product identifier. Empty and invalid strings are ignored. |
Source: revenue.js
Returns: Returns the same Revenue object of type Revenue, allowing you to chain multiple method calls together.
Example:
var revenue = new amplitude.Revenue().setProductId('productIdentifier').setPrice(10.99); amplitude.logRevenueV2(revenue);
4. setQuantity(quantity)
Set a value for the quantity. Note: The Revenue amount is calculated as price * quantity.
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
number |
The integer value for the quantity. If this is not set, it will default to |
Source: revenue.js
Returns: Returns the same Revenue object of type Revenue, allowing you to chain multiple method calls together.
Example:
var revenue = new amplitude.Revenue().setProductId('productIdentifier').setPrice(10.99).setQuantity(5); amplitude.logRevenueV2(revenue);
5. setRevenueType(revenueType)
Set a value for the type of revenue (e.g. purchase, cost, tax, refund, etc.).
Parameters:
| Name | Type | Description |
|---|---|---|
|
|
string |
The type of revenue to designate. |
Source: revenue.js
Returns: Returns the same Revenue object of type Revenue, allowing you to chain multiple method calls together.
Example:
var revenue = new amplitude.Revenue().setProductId('productIdentifier').setPrice(10.99).setRevenueType('purchase'); amplitude.logRevenueV2(revenue);