A node wrapper for Amplitude analytics http api
npm install amplitude 
Server side implementation of Amplitude's HTTP API.
As of 2020-05-30, Amplitude reported issues with their SSL certificate, so they set up an endpoint and alternate endpoint at https://api2.amplitude.com. Read about it on Amplitude's Status Page and affected devices here.
As of v5.1.0+, you can use the alternative endpoint by setting the environment variable:
``bash`
AMPLITUDE_TOKEN_ENDPOINT = 'https://api2.amplitude.com'
Or in the constructor:
`javascript`
const amplitude = new Amplitude('api-token', {
tokenEndpoint: 'https://api2.amplitude.com'
})
For amplitude@5+, it uses Amplitude's V2 HTTP API, which replaces the deprecated V1 HTTP API. This only affects the .track method. The only potential breaking change is by default user_id and device_id require a minimum of 5 characters.
`bash`
npm install amplitude --save
`javascript`
const Amplitude = require('amplitude')
// The only required field is the api token
const amplitude = new Amplitude('api-token')
See the examples/ directory for further usage.
Pass in any keys listed on the Amplitude V2 HTTP API. The only required keys are event_type and either user_id or device_id. If you initialized the Amplitude object with a user/device id, they can be ignored when calling the track method. Note: the user_id and device_id must be 5 or more characters if passed.
`javascript`
const data = {
event_type: 'some value', // required
user_id: 'some-user-id', // only required if device id is not passed in
device_id: 'some-device-id', // only required if user id is not passed in
session_id: 1492789357923, // must be unix timestamp in ms, not required
event_properties: {
//...
},
user_properties: {
//...
}
}
try {
await amplitude.track(data)
} catch (err) {
console.error(err)
}
You can also pass an array of event objects:
`javascript`
const data = [
{
event_type: 'some value', // required
user_id: 'some id', // only required if device id is not passed in
device_id: 'some id', // only required if user id is not passed in
event_properties: {
//...
},
user_properties: {
//...
}
},
{
event_type: 'another value', // required
user_id: 'some id', // only required if device id is not passed in
device_id: 'some id', // only required if user id is not passed in
event_properties: {
//...
},
user_properties: {
//...
}
}
]
amplitude.track(data).then(res => {
console.log('Amplitude response', res)
})
The identify method allows you to make changes to a user without sending an analytics event.
`javascript`
const data = {
user_id: 'some id', // only required if device id is not passed in
device_id: 'some id', // only required if user id is not passed in
event_properties: {
//...
},
user_properties: {
//...
}
}
amplitude.identify(data).then(res => {
console.log('Amplitude response', res)
})
You can also pass an array of identify objects:
`javascript`
const data = [
{
user_id: 'some id', // only required if device id is not passed in
device_id: 'some id', // only required if user id is not passed in
event_properties: {
//...
},
user_properties: {
//...
}
},
{
user_id: 'some id', // only required if device id is not passed in
device_id: 'some id', // only required if user id is not passed in
event_properties: {
//...
},
user_properties: {
//...
}
}
]
amplitude.identify(data).then(res => {
console.log('Amplitude response', res)
})
With this method, you can also modify user properties using property operations.
`javascript`
const data = {
user_id: 'some id', // only required if device id is not passed in
device_id: 'some id', // only required if user id is not passed in
user_properties: {
$set: {
//...
},
$add: {
//...
},
$append: {
//...
}
}
}
amplitude.identify(data).then(res => {
console.log('Amplitude response', res)
})
Note the limitation of mixing user property operations with top level properties. If you use any property operations ($add, $append, etc.), and you want to set a user property, it must be done using the $set operation.
If you prefer camelCase variables, you can pass in the camelCase version instead to the track and identify methods:
`javascript`
const data = {
eventType: 'some value', // required
userId: 'some id', // only required if device id is not passed in
deviceId: 'some id', // only required if user id is not passed in
sessionId: 1492789357923, // must be unix timestamp in ms, not required
eventProperties: {
//...
},
userProperties: {
//...
}
}
amplitude.track(data).then(res => {
console.log('Amplitude response', res)
})
This is the full list of properties that will be automatically transformed:
`
userId -> user_id
deviceId -> device_id
sessionId -> session_id
eventType -> event_type
eventProperties -> event_properties
userProperties -> user_properties
appVersion -> app_version
osName -> os_name
osVersion -> os_version
deviceBrand -> device_brand
deviceManufacturer -> device_manufacturer
deviceModel -> device_model
locationLat -> location_lat
locationLng -> location_lng
If the user/device/session id will always be the same, you can initialize the object with it. Passing a user id or device id in the track and identify methods will override the default value set at initialization.
`javascript
const amplitude = new Amplitude('api-token', { user_id: 'some-user-id' })
// or
const amplitude = new Amplitude('api-token', { device_id: 'some-device-id' })
// or
const amplitude = new Amplitude('api-token', { session_id: 1492789357923 })
try {
await amplitude.track({
event_type: 'some value'
})
} catch (err) {
console.error(err)
}
// Or...
amplitude
.track({
event_type: 'some value',
user_id: 'will-override-the-default-id'
})
.then(res => {
console.log('Amplitude response', res)
})
`
All methods return a Promise.
`javascript
amplitude
.track(data)
.then(function(result) {
//... do something
})
.catch(function(error) {
//... do something
})
// Or..
try {
const result = await amplitude.track({
event_type: 'some value'
})
//... do something with result
} catch (error) {
console.error(error)
//... do something with the error
}
`
The export method requires your secret key to be added when initializing the amplitude object. This method uses the export api and requires a start and end string in the format YYYYMMDDTHH.
The method returns a stream.
`javascript
const fs = require('fs')
const stream = fs.createWriteStream('./may-2016-export.zip')
const amplitude = new Amplitude('api-token', { secretKey: 'secret' })
amplitude
.export({
start: '20160501T20',
end: '20160601T20'
})
.pipe(stream)
`
The user search method requires your secret key to be added when initializing the amplitude object. This method uses the dashboard api.
Search for a user with a specified Amplitude ID, Device ID, User ID, or User ID prefix.
`javascript
const amplitude = new Amplitude('api-token', { secretKey: 'secret' })
amplitude.userSearch('user/device/amplitude id or user id prefix').then(res => {
const matches = res.matches // Array of matches
// How the match was made
// If exact match was made with user id or device id, type === 'match_user_or_device_id'
// If exact match was made with Amplitude ID, type === 'match_amplitude_id'
// If a partial match was made with a user id prefix, type === 'match_user_prefix'
// If no match was made, type === 'nomatch'
const type = res.type
})
`
The user activity method requires your secret key to be added when initializing the amplitude object. This method uses the dashboard api.
Get a user summary and their recent events. This method requires an Amplitude ID. You can use the user search method to find that.
`javascript
const amplitude = new Amplitude('api-token', { secretKey: 'secret' })
amplitude.userActivity('Amplitude ID').then(function(res) {
const userData = res.userData // data about the user
const events = res.events // an array of events associated with the user
})
`
If there is nothing found for the passed Amplitude ID, the Promise will still resolve. The userData object will contain empty values and the events array will be empty:
`javascript`
{
userData: {
num_sessions: 0,
purchases: 0,
revenue: 0,
merged_amplitude_ids: [],
num_events: 0,
canonical_amplitude_id: 1,
user_id: null,
last_location: null,
usage_time: 0,
last_device_id: null,
device_ids: []
},
events: []
}
If you do not know the Amplitude ID, you can use the userSearch method to find it.
`javascript
const amplitude = new Amplitude('api-token', { secretKey: 'secret' })
amplitude
.userSearch('user-id')
.then(function(res) {
// If you're using a prefix, you may get multiple matches and
// you may need to handle the case where there is not a match
const match = res.matches[0]
return amplitude.userActivity(match.amplitude_id)
})
.then(function(res) {
const userData = res.userData // data about the user
const events = res.events // an array of events associated with the user
})
`
The event segmentation method requires your secret key to be added when initializing the amplitude object. This method uses the dashboard api.
Get metrics for an event with segmentation.
`javascript
const amplitude = new Amplitude('api-token', { secretKey: 'secret' })
amplitude
.eventSegmentation({
e: {
event_type: 'event_name'
},
start: '20170104',
end: '20170117'
})
.then(res => {
const segmentationData = res.data
})
`
Example response:
`javascript``
{ series: [ [ 2, 25, 3, 1, 0, 0, 2, 3, 5, 1, 0, 0, 0, 0 ] ],
seriesLabels: [ 0 ],
xValues:
[ '2017-01-04',
'2017-01-05',
'2017-01-06',
'2017-01-07',
'2017-01-08',
'2017-01-09',
'2017-01-10',
'2017-01-11',
'2017-01-12',
'2017-01-13',
'2017-01-14',
'2017-01-15',
'2017-01-16',
'2017-01-17' ] }
If the event does not exist, Amplitude will throw a 400 error.
View the CHANGELOG for changes in each version.
+ Erki Esken
+ Matthew Keesan
+ Geoff Dutton
+ Matt Pardee
+ Chase Seibert
+ filip