AmplitudeClient
AmplitudeClient()
AmplitudeClient SDK API - instance constructor. The Amplitude class handles creation of client instances, all you need to do is call amplitude.getInstance()
AmplitudeClient#init
Initializes the Amplitude Javascript SDK with your apiKey and any optional configurations. This is required before any other methods can be called.
Parameters
apiKey
(string
) The API key for your app.opt_userId
(string
) (optional) An identifier for this user.opt_config
(object
) (optional) Configuration options. See options.js for a list of options and default values.opt_callback
(function
) (optional) Provide a callback function to run after initialization is complete.
AmplitudeClient#isNewSession
Returns true if a new session was created during initialization, otherwise false.
Return Value
- (
boolean
) Whether a new session was created during initialization.
AmplitudeClient#onInit
Add callbacks to call after init. Useful for users who load Amplitude through a snippet.
AmplitudeClient#onNewSessionStart
Add callbacks to call after new session start.
AmplitudeClient#getSessionId
Returns the id of the current session.
Return Value
- (
number
) Id of the current session.
AmplitudeClient#clearStorage
Clears any stored events and metadata. Storage is then re-created on next event sending.
Return Value
- (
boolean
) True if metadata was cleared, false if none existed
AmplitudeClient#setDomain
Sets a customer domain for the amplitude cookie. Useful if you want to support cross-subdomain tracking.
Parameters
domain
(string
) to set.
AmplitudeClient#setUserId
Sets an identifier for the current user.
Parameters
userId
(string
) identifier to set. Can be null.startNewSession
(boolean
) (optional) if start a new session or not
AmplitudeClient#setGroup
Add user to a group or groups. You need to specify a groupType and groupName(s).
For example you can group people by their organization. In that case, groupType is "orgId" and groupName would be the actual ID(s). groupName can be a string or an array of strings to indicate a user in multiple gruups. You can also call setGroup multiple times with different groupTypes to track multiple types of groups (up to 5 per app).
Note: this will also set groupType: groupName as a user property. See the advanced topics article for more information.
Parameters
groupType
(string
) the group type (ex: orgId)groupName
(string|list
) the name of the group (ex: 15), or a list of names of the groups
AmplitudeClient#setOptOut
Sets whether to opt current user out of tracking.
Parameters
enable
(boolean
) if true then no events will be logged or sent.
AmplitudeClient#setSessionId
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. The Session ID to set for the current session must be in milliseconds since epoch (Unix Timestamp).
Parameters
sessionId
(int
) to set.
AmplitudeClient#resetSessionId
Sets the current Unix timestamp as the new Session ID for the instance.
AmplitudeClient#regenerateDeviceId
Regenerates a new random deviceId for 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.
With a null userId and a completely new deviceId, the current user would appear as a brand new user in dashboard.
This uses src/uuid.js to regenerate the deviceId.
AmplitudeClient#setDeviceId
Sets a custom deviceId for current user. Values may not have .
inside them
Note: this is not recommended unless you know what you are doing (like if 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
deviceId
(string
) custom deviceId for current user.
AmplitudeClient#setTransport
Sets the network transport type for events. Typically used to set to 'beacon'
on an end-of-lifecycle event handler such as onpagehide
or onvisibilitychange
Parameters
transport
(string
) transport mechanism to use for events. Must be one ofhttp
orbeacon
.
AmplitudeClient#setUserProperties
Sets user properties for the current user.
Parameters
userProperties
(object
) object with string keys and values for the user properties to set.`
(
boolean`) DEPRECATED opt_replace: in earlier versions of the JS SDK the user properties object was kept in memory and replace = true would replace the object in memory. Now the properties are no longer stored in memory, so replace is deprecated.
AmplitudeClient#clearUserProperties
Clear all of the user properties for the current user. Note: clearing user properties is irreversible!
AmplitudeClient#setVersionName
Set a versionName for your application.
Parameters
versionName
(string
) The version to set for your application.
AmplitudeClient#logEvent
Log an event with eventType and eventProperties
Parameters
eventType
(string
) name of eventeventProperties
(object
) (optional) an object with string keys and values for the event properties.opt_callback
(Amplitude~eventCallback
) (optional) 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.opt_error_callback
(Amplitude~eventCallback
) (optional) a callback function to run after the event logging fails. The failure can be from the request being malformed or from a network failure Note: the server response code and response body from the event upload are passed to the callback function.outOfSession
(boolean
) (optional) if this event is out of session or not
AmplitudeClient#logEventWithTimestamp
Log an event with eventType and eventProperties and a custom timestamp
Parameters
eventType
(string
) name of eventeventProperties
(object
) (optional) an object with string keys and values for the event properties.timestamp
(number
) (optional) the custom timestamp as milliseconds since epoch.opt_callback
(Amplitude~eventCallback
) (optional) 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.opt_error_callback
(Amplitude~eventCallback
) (optional) a callback function to run after the event logging fails. The failure can be from the request being malformed or from a network failure Note: the server response code and response body from the event upload are passed to the callback function.outOfSession
(boolean
) (optional) if out of the sessioin or not
AmplitudeClient#logEventWithGroups
Log an event with eventType, eventProperties, and groups. Use this to set event-level groups. Note: the group(s) set only apply for the specific event type being logged and does not persist on the user (unless you explicitly set it with setGroup).
See the advanced topics article for more information about groups and Count by Distinct on the Amplitude platform.
Parameters
eventType
(string
) name of eventeventProperties
(object
) (optional) an object with string keys and values for the event properties.groups
(object
) (optional) an object with string groupType: groupName values for the event being logged. groupName can be a string or an array of strings.opt_callback
(Amplitude~eventCallback
) (optional) 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.opt_error_callback
(Amplitude~eventCallback
) (optional) a callback function to run after the event logging fails. The failure can be from the request being malformed or from a network failure Note: the server response code and response body from the event upload are passed to the callback function.
AmplitudeClient#logRevenueV2
Log revenue with Revenue interface. The new revenue interface allows for more revenue fields like revenueType and event properties.
See the Revenue reference page for more information on the Revenue interface and logging revenue.
Parameters
revenue_obj
(Revenue
) the revenue object containing the revenue data being logged.
AmplitudeClient#logRevenue
AmplitudeClient#logRevenue
Log revenue event with a price, quantity, and product identifier. DEPRECATED - use logRevenueV2
Deprecated
true
Parameters
price
(number
) price of revenue eventquantity
(number
) (optional) quantity of products in revenue event. If no quantity specified default to 1.product
(string
) (optional) product identifier
AmplitudeClient#setGlobalUserProperties
AmplitudeClient#setGlobalUserProperties
Set global user properties. Note this is deprecated, and we recommend using setUserProperties
Deprecated
true
AmplitudeClient#__VERSION__
Get the current version of Amplitude's Javascript SDK.
Return Value
- (
number
) version number
AmplitudeClient#setLibrary
Sets the library name and version. Default is amplitude-js
and the version defined in package.json. Used if you're building another library on top of amplitude-js and want a custom data source value
Parameters
name
(string
) Custom library nameversion
(string
) Custom library version
AmplitudeClient#enableTracking
Enable tracking via logging events and dropping a cookie Intended to be used with the deferInitialization configuration flag This will drop a cookie and reset initialization deferred
AmplitudeClient#getDeviceId
Returns the deviceId value.
Return Value
- (
string
) Id of current device.
AmplitudeClient#getUserId
Returns the userId.
Return Value
- (
string
) Id of current user.
AmplitudeClient#setMinTimeBetweenSessionsMillis
Set a custom session expiration time.
Parameters
timeInMillis
(number
) session expireation time in milliseconds.
AmplitudeClient#setEventUploadThreshold
Sets minimum number of events to batch together per request if batchEvents is true.
Parameters
eventUploadThreshold
(number
) The number of the event upload threshold. Default value is 30.
AmplitudeClient#setUseDynamicConfig
Dynamically adjust server URL
Parameters
useDynamicConfig
(bool
) if enable dynamic config or not.
AmplitudeClient#setServerZone
Sets the server zone, used for server api endpoint and dynamic configuration.
Parameters
serverZone
(string
) the server zone value. AmplitudeServerZone.US or AmplitudeServerZone.EU.serverZoneBasedApi
(bool
) (optional) update api endpoint with serverZone change or not. For data residency, recommend to enable it unless using own proxy server.
AmplitudeClient#setServerUrl
Sets the server URL for the request.
Parameters
serverUrl
(string
) The value of the server URL.