Tracking API

Welcome to the Tracking API. 
This API should be used when there is no module available for your language or they doesn't satisfy your needs.
We strive to keep it as simple as possible.
Is something missing from the API? Let us know [email protected]​
Event Types
Type
Description
Requires extra data
init
First event to send when starting the app
yes
event
Default type, for reporting actions or anything else
no
error
Submit an error, name should contain the error type
yes
userid
Set a new user ID for this user
no
props
Set propserties for this user ID based on the data field.
no
heartbeat
Websockets only: send every minute to keep the connection on. This only require to pass the machineIdfield alongside
no
The first thing you need to send when the user opens the app is an init event upon which most of the analytics relies on. 
If you don't send it first, no data will appear in your dashboard.
Events Data
Nucleus expect to receive the analytics data as a JSON object, containing a data array property.
This array should contain one or multiple events you want to report.
Basic events data
Parameter
Type
Optional
Description
type
String
optional
Event type, see below for all the possible values (default: "event")
name
String
required if type is event or error
Name of the event
sessionId
Integer
required
4-digits number that identifies the current session
date
String
optional
Date/time of the event (ISO 8601 or milleseconds since 1970). If not provided we'll use the time the server receives the event.
id
String
optional
Short ID that will be returned in confirmation
userId
String
optional
Identify the user with user-facing ID like email, username.. 
anonId
String
optional
Unique user identifier. Ideally should be a nanoid of 12 chars. More reliable than userId and can be used to track anonymous users.
deviceId
String
required
Hashed identifier of the machine (ie mac adress)
payload
Object
optional
Aditionnal data attached to the event
Extra events data
If you are reporting either an error or the first init event, you can attach those extra data:
Parameter
Type
Optional
Example
Description
platform
String
required
darwin
Usually 'win32', 'windows', 'mac', 'darwin' or 'linux'
osVersion
String
required
18.2.0
Current installed version of the OS
totalRam
Integer
required
8
Total RAM available on the user device
version
String
required
0.1.0
Version of the app installed
language
String
required
en-US
Locale of the user
They are not required with regular events to save bandwidth.
Example:
{    
    "data": [{       
     "event": String, // Name of the event        
     "id": String, // OPTIONAL A random id for the event that will be returned when the query succeeds, can be used to make sure no events are reported two times.        
     "userId": String, // A string to identify the user      
     "anonId": String, // 12 chars nanoid identifying the user          
     "deviceId": String, // A hashed identifier of the machine        
     "sessionId": Int, // A random 4-digits number that identifies the current session
     "platform": String, //        
     "osVersion": String, // The version of the OS        
     "totalRam": Int, // The total number of RAM available, in GB        
     "version": String, // Installed version of the app        
     "language": String, // Locale of the user (i.e. 'en-US')        
     "payload": {} // Any additionnal data that you want to report along the event    }]
  }
Track via WebSockets
This is the recommended protocol to submit data. 
It is the most efficient in terms of bandwidth and battery. This is what the modules use behind the scenes.
Latency will be vastly better compared to normal HTTP requests.
Endpoint: wss://app.nucleus.sh/:appId/
Send your data as a JSON serialized string message.
To prevent data lost due to network errors, when Nucleus receives an event it will send your client a message containing an array reportedIds of the previously reported events so you can safely assume they were handled by the server.
Track via HTTP
​
post
https://app.nucleus.sh/app/:appId/track
​
Compliance
Next - Reference
Data API V1
Last modified 1mo ago
Copy link
Outline