Natero Javascript Event API

This library provides a mechanism by which user interactions (clicks) can be tracked and logged to a Natero server. At the heart of the event tracking is the na object. At its core, the object provides methods for setting the feature, module, account Id, and user Id to be transmitted with each interaction event.

Module and feature Ids must be specified via API calls on the na object

To use the api, events should be sent via the sendFeatureEvent() api call. The module ID can be set separately via the setModuleId() call as shown in the quickstart guide. A module ID stays set until changed or explicitly set to null. An optional product ID can also be associated with feature and module events. The productId is set similarly to the moduleId, via the setProductId() call. As well, it stays set until changed or set to null.

An idle timer is used to track idle time. The timer is reset on any click, mousemove or keyboard event. When idle time is detected, a sessionIdle event is generated. As well a moduleEnd event is generated that contains the amount of time within the current module (if the current module is set). When the user resumes activity module and session time tracking continues.

Two cookies are generated to track user sessions. One cookie is a short-lived session cookie (with a default timeout of 30 minutes). The other is a longer more persistent cookie used to associate sessions over a longer time period. By default, the library attempts to track page unloading. This is difficult to do and somewhat browser dependent. At page unload time a pageViewEnd event is generated along with a moduleEnd event (if a current module is set and the user is not idle).

NOTE: data sent via the event API is batch processed and is not immediately visible via the Natero UI. Data is aggregated every hour and is then viewable via the Natero Data Explorer. Data is then further aggregated every day and updates to some of the internal dashboards are only visible after the daily aggregation has occured. Once the library has been integrated into your product please let us know as we need to setup the workflows to run and process your data. This needs to be completed prior to data becoming visible within the UI.

See the Quickstart Guide for more details on instrumenting your application with this API.

 
API Calls
 
na(apiKey, authKey, options)
Constructor: Create a new Natero Analytics Data Collector object
Parameters
NameTypeRequiredDescription
apiKeystring
yeskey to determine organization and source
authKeystring
yesauthentication key
optionsobject
nosee below for components (all optional)
options.accountIdstring(256)
Default: null
noidentity of the account if known
options.batchTimeoutnumber
Default: 15s
nonumber of secs to wait between batching of events
options.debugboolean
Default: false
noenables console logging
options.debugUrlstring
nosends event data to specified url (e.g., of a debug server);
our debug server is: http://test.natero.com/v1/[authKey]/[apiKey]
options.disableEventSendboolean
Default: false
nodisables sending events; sets debug to true [debug can be forced off by explicitly setting debug = false]
options.euEndpointboolean
Default: false
nosets the URL endpoint to the EU data collector if true
options.pageNamestring
Default: html path
nohuman readable name for page
options.sessionTimeoutminutes
Default: 30 mins
nonumber of minutes before timing out the session
options.sessionSyncIntervalseconds
Default: 15 secs
nonumber of seconds between syncing of session/module data
options.trackUnloadboolean
Default: true
noattempts to track page unloads for accurate page durations
options.unloadDelaynumber
Default: 500 ms
nonumber of msecs to wait for last event on unload
options.userIdstring(256)
Default: null
noidentity of the user if known
 
login(userId, accountId, details)
Indicates that a login event has occured. Set the userId and accountId similar to setAccountId() and setUserId(). Set the productId similar to setProductId(product) if product is a non-empty string. It also sends a login event that is tracked as a separate metric (logins). With this call one can also provide extra details about the user such as email address and name; this is used to update the set of product users and is visible within the product (to show which users are associated with each event). The accountId and userId are associated will all generated events, and stored in a cookie until logout().
Parameters
NameTypeRequiredDescription
userIdstring(256)
yesidentity of user
accountIdstring(256)
yesidentity of account
detailsobject
preferred
nooptional details that can be associated with the user. Can be used to update product user list, if user not previously seen.
details.first_namestring(80)
preferred
nofirst name of user
details.last_namestring(80)
preferred
nolast name of user
details.emailstring(512)
preferred
noemail of user
details.phonestring(80)
nophone of user
details.mobile_phonestring(80)
nomobile phone of user
details.salutationstring(80)
nosalutation of user. e.g. Mr.
details.titlestring(128)
notitle of user. e.g. Customer Success Manager
details.rolestring(128)
norole of user. e.g. CSM
details.departmentstring(128)
nodepartment of user. e.g. Customer Success Department
details.mailing_streetstring(512)
nomailing street of user. e.g. 123 Sesame St.
details.mailing_citystring(80)
nomailing city of user. e.g. New York
details.mailing_statestring(80)
nomailing state of user. e.g. NY
details.mailing_postalstring(80)
nomailing postal of user. e.g. 10001
details.mailing_countrystring(80)
nomailing country of user. e.g. USA
productIdstring(128)
noproduct Id, set as if setProductId(product) had been called
 
logout()
Logs the current user out and ends the current session. Sends logout event and removes accountId, userId, productId association. After logout, no new events will be generated until a new login() or setAccountId() call is made.
 
identifyUser(details)
An api to provide extra details about the user such as email address and name; this is used to update the set of product users and is visible within the product (to show which users are associated with each event). The accountId and userId must be set previously by either a login(), or setUserId()/setAccountId() or na() call.
Parameters
NameTypeRequiredDescription
detailsobject
yesdetails that can be associated with the user
details.first_namestring(80)
preferred
nofirst name of user
details.last_namestring(80)
preferred
nolast name of user
details.emailstring(512)
preferred
noemail of user
details.phonestring(80)
nophone of user
details.mobilestring(80)
nomobile of user
details.salutationstring(80)
nosalutation of user. e.g. Mr.
details.titlestring(128)
notitle of user. e.g. Customer Success Manager
details.rolestring(128)
norole of user. e.g. CSM
details.departmentstring(128)
nodepartment of user. e.g. Customer Success Department
details.mailing_streetstring(512)
nomailing street of user. e.g. 123 Sesame St.
details.mailing_citystring(80)
nomailing city of user. e.g. New York
details.mailing_statestring(80)
nomailing state of user. e.g. NY
details.mailing_postalstring(80)
nomailing postal of user. e.g. 10001
details.mailing_countrystring(80)
nomailing country of user. e.g. USA
 
identifyAccount(details)
An api to provide extra details about the account such as name, address, industry, etc. This is used to update the account dimensions visible within the product. The accountId must be set previously by either a login(), or setAccountId() or na() call.
Parameters
NameTypeRequiredDescription
detailsobject
yesdetails that can be associated with the account
details.namestring(256)
noname of account; required when adding new account
details.join_datenumber
epoch ms
nodate account joined your product; required when adding new account
details.lifecycle_stagestring(80)
nocurrent lifecycle stage
details.is_churnedboolean
nomark account as churned if true, mark account as active is false
details.inactive_timenumber
epoch ms
nowhen setting churned to true, set as date account churned
details.inactive_reasonvarchar(512)
nowhen setting churned to true, set as reason why
details.tierstring(80)
notier for account
details.industrystring(80)
noindustry of account
details.employeesnumber
nonumber of employees
details.websitestring(512)
noaccount's website
details.phonestring(80)
noaccount primary phone number
details.billing_streetstring(512)
nomailing street of user. e.g. 123 Sesame St.
details.billing_citystring(80)
nomailing city of user. e.g. New York
details.billing_statestring(80)
nomailing state of user. e.g. NY
details.billing_postalstring(80)
nomailing postal of user. e.g. 10001
details.billing_countrystring(80)
nomailing country of user. e.g. USA
 
setModuleId(moduleId)
Set the current module name. If new moduleId is different from old moduleId, an event is generated providing the amount of time spent in the old module (since last idle). This module stays set until reset with a 'null' moduleId.
Parameters
NameTypeRequiredDescription
moduleIdstring(128)
yesname of current module (null to reset the current module)
 
setProductId(productId)
Set the current product name. This product stays set until reset with a 'null' productId.
Parameters
NameTypeRequiredDescription
productIdstring(128)
yesname of current product (null to reset the current product)
 
setAccountId(accountId)
Set the current accountId.
Parameters
NameTypeRequiredDescription
accountIdstring(256)
yesidentity of account
 
setUserId(userId)
Set the current userId
Parameters
NameTypeRequiredDescription
userIdstring(256)
yesidentify of user
 
sendFeatureEvent(featureId, moduleId, productId)
Send an event for a specific feature and optionally a module and/or product.
Parameters
NameTypeRequiredDescription
featureIdstring(128)
yesfeature id to associate with event
moduleIdstring(128)
yesmodule id to associate with event; behaves as if setModuleId(moduleId) was called
productIdstring(128)
yesproduct id to associate with event; behaves as if setProductId(productId) was called
 
syncEvents()
Sync (transmit) any queued events