Skip to main content

buildfire.analytics

BuildFire provides a way for developers to track plugin views and user actions with minimal setup so they can retrieve all these analytical data later. These events will be sent to our analytics server and then forwarded to the developer segment.io account which will be set by the developer. Our Intergration with segment.io, will allow developers to receive events at any of the endpoints supported by segment.io.

important

Events will be also accessible to BuildFire, White Label owners and the app owner so it is very important NOT to use it to send sensitive information such as user passwords or anything that may violate users privacy.

Methods

trackView()

buildfire.analytics.trackView(eventName, metaData)

Tracks the view in analytics

buildfire.analytics.trackView("home");

arguments

The name of the view you wish to track

NameTypeRequiredDescriptionDefault
eventNamestringyesThe name of the view you wish to track
metaDataobjectnoAny extra information you would like to add to the user event
note

To have aggregation reports in Control Side, you need to pass aggregation value inside metadata obj like so:

_buildfire: {
aggregationValue: 10
}

Aggregation example

buildfire.analytics.trackView("home", {
_buildfire: { aggregationValue: 10 },
});

trackAction()

buildfire.analytics.trackAction(eventName, metaData)

User actions, such as a button click, can be tracked by using the trackAction function

buildfire.analytics.trackAction("sheet-entry", { totalEntries: 5 });

arguments

NameTypeRequiredDescriptionDefault
eventNamestringyesThe name of the action you wish to track
metaDataobjectnoAny extra information you would like to add to the user event
note

To have aggregation reports in Control Side, you need to pass aggregation value inside metadata obj like so:

_buildfire: {
aggregationValue: 10
}

Aggregation example

buildfire.analytics.trackAction("home",  {
totalEntries: 5
_buildfire: { aggregationValue: 5 },
});

registerEvent()

buildfire.analytics.registerEvent(event, options, callback)

This function used to register an event for your plugin.

buildfire.analytics.registerEvent(
{
title: "custom-event",
key: "customEvent",
description: "Custom event description",
},
{ silentNotification: true }
);

event

Event object

NameTypeRequiredDescriptionDefault
titlestringyesEvent title
keystringyesEvent unique key
descriptionstringnoEvent description

options

NameTypeRequiredDescriptionDefault
silentNotificationbooleannoDetermine wether you want to display a notification to the customer, with the new registered event.false

callback(err, result)

Optional callback function after registering event

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectResult from saving your event in database

How to create Custom Event for your plugin

Plugin events are useful to give the customer detailed analytics of the user's behavior in your plugin. You can do that by registering your plugin events in the control side of your plugin. Once you register your custom events, you can track them using the above examples using trackAction.

The Analytics tab in the Control side, will have three reports:

  1. Daily Report: Will show the total count of the selected event.

    Daily report without Aggregation value:

    Daily Report

    Daily report with Aggregation value:

    Daily Report Aggregation

  2. Top Users Report: Will show the top users for the selected event.

Top Users

  1. Details Report: will show detail info about each user.

Details Report

These three reports will recalculate the data depending on the selected event from the list on the left top corner, or when changing the selected days period on the right top corner.

Registered Events

Once you register your plugins in the control side, the customers will see a notification in the Analytics tab, to inform them that there is a new event registered to the plugin, so they can check the reports related to the new event. This notification is controled by silentNotification

Notification


bulkRegisterEvents()

buildfire.analytics.bulkRegisterEvents(obj, options, callback)

This function allows you to register multiple events simultaneously for your plugin. For further information on register events see registerEvent()

buildfire.analytics.bulkRegisterEvents(
[
{
title: "Item Added to Cart",
key: "cartItemAdded",
description: "the user added an item to the cart",
},
{
title: "Purchase Completed",
key: "purchaseCompleted",
description: "the user completed a purchase",
}
],
{ silentNotification: true }, (err ,result) => {
if (err) return console.log("there was a problem registering your events");
console.log("events registered");
}
);

obj

NameTypeRequiredDescriptionDefault
obj[object]yesArray of event objects to be registered

options

NameTypeRequiredDescriptionDefault
silentNotificationbooleannoDetermine wether you want to display a notification to the customer, with the new registered events.false

callback(err, result)

Optional callback function after registering events

NameTypeDescription
errstringerror string, null when operation is successful
result[object]Array containing Added event objects

unregisterEvent()

buildfire.analytics.unregisterEvent(key, callback)

This function is used to unregister an event for your plugin.

buildfire.analytics.unregisterEvent("customEvent");

key

Event key

NameTypeRequiredDescriptionDefault
keystringyesEvent key

callback(err, result)

Optional callback function after unregistering event

NameTypeDescription
errstringerror string, null when operation is successful
resultUnregister resultUsually {status: "deleted"}

bulkUnregisterEvents()

buildfire.analytics.bulkUnregisterEvents(obj, callback)

This function allows you to unregister multiple events simultaneously for your plugin.

buildfire.analytics.bulkUnregisterEvents(
[
"cartItemAdded",
"purchaseCompleted"
], (err, result) => {
if (err) return console.log("there was a problem unregistering your events");
console.log("events unregistered");
});

obj

NameTypeRequiredDescriptionDefault
obj[string]yesArray of event keys to be unregistered

callback(err, result)

Optional callback function after unregistering events

NameTypeDescription
errstringerror string, null when operation is successful
result[object]Array containing deleted event objects

showReports()

buildfire.analytics.showReports(options, callback)

This function is used to show the analytic reports modal for specific event.

buildfire.analytics.showReports({ eventKey: "customEvent" });

options

NameTypeRequiredDescriptionDefault
eventKeystringyesEvent key for which to display reports

callback(err, result)

Optional callback after modal is shown

NameTypeDescription
errstringerror string, null when operation is successful
resultbooleantrue when dialog is displayed