Tracking

The Tracking API is a collection of APIs and Configuration that can be used to display statistics about your plugin usage.
At Livestorm we use it to show detail about the Emoji Reaction plugin usage such as the number of reaction sent per user and which reaction has been sent.

Tracking.Event.track()

👍

Prior to sending events from your plugin's code, you need to configure how your events will be displayed in the dashboard.
Read the Configuration section below to know more

Track an event to make it visible in the dashboard.

988988

use cases : Displaying usage statistics, provide insights to your team members

usage :

Tracking.Event.track({
   key: 'emoji-reactions',
   value: 'joy'
})
ParamTypeDescription
keyStringThe key defined in your livestorm.config.js
valueStringThe value to be tracked, it can be omitted if your aggregation is increment (making it a simple counter)

Configuration

This step is mandatory to have your events displayed in the dashboard. You will need to update your livestorm.config.js file to leverage the new tracking syntax.

Basically you need to add a tracking object, which contains an events array, just like below:

"tracking": {
    "events": [
      {
        "name": {
          "en": "Handouts downloads",
          "fr": "Nombre de téléchargements",
        },
        "key": "handouts", 
        "aggregations": ["group_array", "array", "increment"], 
      }
    ]
  },

Here is a list of parameters your can pass to each event object

ParamTypeDescription
nameObjectAn object of translations that will be used to display the column name in the dashboard
keyStringThe key to be used with the Tracking.Event.track API
aggregationsArray<"group_array", "array", "increment", "average", "string">The type of aggregation to be displayed
delete_existing_eventsbooleanIf your plugin is published with this param, it will automatically reset the event list upon publish
value_typeboolean, image, url, string, numberProviding this will affect the way the value is displayed in the dashboard and will also add validations to the input value

A note about the aggregations

Aggregations will affect the way the data is computed on the dashboard.

📘

Despite being a list, as of today only the first element of the aggregation array will be used in the dashboard. In the future team members will be able to use any of the provided aggregation.

increment

This is the simplest aggregation possible, it will simply act as a counter of events.
For instance, the following code

Tracking.Event.track({ key: 'test' })
Tracking.Event.track({ key: 'test' })

Will simply show "2" in the created column in the dashboard.

array

The array aggregation will act as a simple listing of the values sent using the tracking API.

Tracking.Event.track({ key: 'test', value: 'apples' })
Tracking.Event.track({ key: 'test', value: 'oranges' })

Will simply display apples, oranges in the column for the given user.
The mechanism simply takes all values an apply a join(', ') on the array.

average

The average aggregation requires a number to be given as value. Then it will simply compute an average of the given values.

Tracking.Event.track({ key: 'test', value: 10 })
Tracking.Event.track({ key: 'test', value: 5 })

Will show 7.5 in the dashboard column.

string

This isn't technically an aggregation, what this does is simply take the latest event for the given user.

Tracking.Event.track({ key: 'name', value: 'Michael' })
Tracking.Event.track({ key: 'name', value: 'John'  })

It will simply display John in the dashboard. This is useful if you want to display the result of something the user can update over time, like a field value.

group_array

This is currently the most powerful aggregation. It allows users to know the total of events for an event, but also to see the detail of every sent values

988988

To get the same result as the above image, you'd need to send:

for (let i = 0; i < 7; i++) {
  Tracking.Event.track({ key: 'test', value: '😍' })
}

Tracking.Event.track({ key: 'test', value: '😱'  })
Tracking.Event.track({ key: 'test', value: '😱'  })