JavaScript SDK Reference

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.

Table of Contents

• Class: Amplitude
• Type Definitions
• Class: AmplitudeClient
• AmplitudeClient
• Members
• Methods
• Class: Identify
• Identify
• Methods
• Class: Revenue
• Revenue
• Methods

---

 

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
responseCode	number	The server response code for the event/identify upload request.
responseBody	string	The server response body for the event/identify upload request.

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
responseCode	number	The server response code for the event/identify upload request.
responseBody	string	The server response body for the event/identify upload request.

Source: amplitude-client.js

Back to top

---

 

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.

 

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
identify_obj (required)	Identify	The Identify object containing the user property operations to send.
opt_callback (optional)	Amplitude~eventCallback	Callback function to run when the identify event has been sent. Note: The server response code and response body from the identify event upload are passed to the callback function.

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
apiKey (required)	string	The API Key for your project.
opt_userId (optional)	string	An identifier for this user.
opt_config (optional)	object	Configuration options. See the JavaScript SDK documentation for a list of options and the default values.
opt_callback (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
callback (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
eventType (required)	string	The name of the event.
eventProperties (optional)	object	An object with string keys and values for the event properties.
opt_callback (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
eventType (required)	string	The name of the event.
eventProperties (optional)	object	An object with string keys and values for the event properties.
timestamp (optional)	number	The custom timestamp as milliseconds since epoch.
opt_callback (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_obj	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. 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. 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
deviceId	string	Custom deviceId for the current user.

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
domain	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). 

Parameters:

Name	Type	Description
groupType	string	The group type (e.g. 'orgId).
groupName	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
enable	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
userId	string	The identifier to set. This can be null.

Source: amplitude-client.js

Example:

amplitudeClient.setUserId('joe@gmail.com');

 

16. setUserProperties(userProperties)

Sets user properties for the current user.

Parameters:

Name	Type	Description
userProperties	object	The identifier to set. This can be null.
opt_replace (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
versionName	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. 

 

Parameters:

Name	Type	Description
sessionId	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);

Back to top

---

 

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. 

 

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
property	string	The user property key.
value	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
property	string	The user property key.
value	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
property	string	The user property key.
value	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
property	string	The user property key.
value	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
property	string	The user property key.
value	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
property	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

Back to top

---

 

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.

Source: revenue.js

Example:

var revenue = new amplitude.Revenue();

 

Methods

1. setEventProperties(eventProperties)

Set event properties for the revenue event. 

Parameters:

Name	Type	Description
eventProperties	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
price	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
productId	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. 

 

Parameters:

Name	Type	Description
quantity	number	The integer value for the quantity. If this is not set, it will default to 1.

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
revenueType	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);

Back to top