Beagle v1.6 is no longer actively maintained. The documented version you are viewing may contain deprecated functionality. For up-to-date documentation, see the latest version .
Analytics is a powerful yet simple to use functionality that Beagle offers, it gives developers control over the tracking of actions and navigation of their application to use in association with any analytics service they might want.
In the next topics you will learn how to enable event tracking and configure it according to what you need.
The first thing we need to enable the Analytics functionality is to create a provider implementing the interface below
AnalyticsProvider
Property | Definition | Type |
---|---|---|
getConfig | Beagle uses this configuration to know how to handle analytics events, and so this method will be called on every triggered event, in order to access the most updated global analytics config. It must always return an AnalyticsConfig. If you are retrieving your analytics config asynchronously, It is recommended that you pass a config that blocks all the records until the remote one is fully loaded | Method |
createRecord | Beagle will call this method to provide you with a record (AnalyticsRecord ) generated for an event. If you don’t want to send one request for each analytics generated by Beagle, it is a good idea to implement a batch mechanism within this function. | Method |
Now, choose the platform you are using Beagle with to see examples of how to configure the Analytics Provider in your application
Open your Beagle service configuration file and create a function implementing the AnalyticsProvider
interface like the following:
...
import { AnalyticsProvider, AnalyticsConfig, AnalyticsRecord } from '@zup-it/beagle-web'
function analytics(): AnalyticsProvider {
function getConfig() {
return {
enableScreenAnalytics: true,
actions: {
'beagle:setContext': ['contextId', 'path', 'value']
}
}
}
function createRecord(record: AnalyticsRecord) {
console.log('Record', record)
}
return {
getConfig,
createRecord
}
}
export default createBeagleUIService<any>({
...
analyticsProvider: analytics()
})
@BeagleComponent
class AnalyticsProviderImpl : AnalyticsProvider{
override fun getConfig(): AnalyticsConfig? = object : AnalyticsConfig{
override var enableScreenAnalytics: Boolean? = true
override var actions: Map<String, List<String>>? = hashMapOf(
"beagle:setContext" to listOf("contextId", "path", "value")
)
}
override fun createRecord(record: AnalyticsRecord) {
Log.d("analytics", record.platform)
Log.d("analytics", record.type)
Log.d("analytics", record.attributes.toString())
}
}
import Beagle
class MyAnalyticsProvider: AnalyticsProvider {
func getConfig() -> AnalyticsConfig? {
return AnalyticsConfig(
enableScreenAnalytics: true,
actions: [
"beagle:setcontext": ["contextId", "path", "value"]
]
)
}
func createRecord(_ record: AnalyticsRecord) {
// here you could just send `record` to your analytics backend
print(record)
}
}
let dependencies = BeagleDependencies()
...
dependencies.analyticsProvider = MyAnalyticsProvider()
...
Beagle.dependencies = dependencies
As soon as you finish configuring the Analytics provider you are ready to start defining the events you want to track in your Beagle application, there are two ways to do so which are the ActionAnalyticsConfig
and the AnalyticsConfig
.
You can either use both configuration payloads or choose the one that better fits your solution, an important point to note here is that the ActionAnalyticsConfig
has priority over the AnalyticsConfig
which means that if you configure the same tracking event for both of them the ActionAnalyticsConfig
will be used.
see next further details on both ways of mapping the analytics
The easiest way to enable or disable tracking with Beagle is through the BFF, you can simply enable which actions you want tracked by adding to them the key analytics.
To disable the analytics we first choose the action and add the analytics property to it with a value of false, the JSON result would be something like the following :
{
"_beagleComponent_": "beagle:button",
"text": "Button with analytics",
"onPress": [
{
"_beagleAction_": "beagle:pushStack",
"analytics": false
}
]
}
Now see a snippet of how to generate this same payload:
Button(
"Button with analytics",
onPress = listOf(
Navigate.PushStack(
route = Route.Remote(url = "/screen-2"),
analytics = ActionAnalyticsConfig.Disabled()
)
)
)
The analytics property however accepts two types of values it can be a boolean that when set to false disables all the tracking for that action (see previous example) or it can be a structure that enables the analytics, see below:
When enabled, the analytics can be configured to send extra and detailed data about the component and action, to do so the JSON handed to the application should be as the next snippet
{
"_beagleComponent_": "beagle:button",
"text": "Button with analytics",
"onPress": [
{
"_beagleAction_": "beagle:pushStack",
"analytics": {
"additionalEntries": {
"extra": "Extra information"
},
"attributes": [
"route"
]
},
"route": {
"url": "/myRoute.json"
}
}
]
}
This configuration allows a better handling of each one of the actions directly from the screen payload. In the previous example we are passing inside the analytics key two new properties:
the additionalEntries
that can be anything you might need and in our case we are passing a simple text;
the attributes
property has to be one of the properties of the action in our example we are passing the key route that will send the value of the route key to create the analytics record.
Next you will learn how to generate this same payload.
The ActionAnalyticsConfig
is a sealed class that besides the disabled method we showed before, also offers an enabled method that accepts a parameter of type ActionAnalyticsProperties
detailed next
ActionAnalyticsProperties
Property | Definition | Type |
---|---|---|
attributes | List of attributes to be exposed to the analytics interface | Array <string> |
additionalEntries | Any additional data you may want to send along with the action | Map<string, any> |
Using this interface you can control individually the actions and also the action’s properties you want to be sent to the createRecord
method from the AnalyticsProvider
. The next example shows how to generate the payload you saw before
Button(
"Button with analytics",
onPress = listOf(
Navigate.PushStack(
analytics = ActionAnalyticsConfig.Enabled(
ActionAnalyticsProperties(
attributes = listOf("route"),
additionalEntries = hashMapOf("extra" to "Extra information")
)
),
route = Route.Remote(url = "/myRoute.json")
)
)
)
Another way to use the Analytics functionality is with a configuration payload which contains the actions or navigation events to be tracked, this configuration will usually be requested and returned within the getConfig
method of the AnalyticsProvider interface.
The library offers an API interface to guide us through the configuration, see below.
AnalyticsConfig
Property | Definition | Type |
---|---|---|
enableScreenAnalytics | Default is true , when false no analytics will be generated by this system when a screen is loaded | boolean |
actions | A map of actions allowed to create analytics records. By default no action creates records. In this map, each key is a beagleAction, while the values are the array of strings. The value indicates which properties of the given action will be tracked | Map<BeagleAction, Array |
See below an example of an expected payload format
{
enableScreenAnalytics: true,
actions: {'beagle:pushView': ['route.screen'], 'beagle:alert': ['']}
}
Note in the previous snippet that we enabled the analytics for screen events, which means that every time a navigation action occurs the tracking method will be called to create a record for the current route with its data and identifier. The second attribute is a map structure of Beagle actions and for each action an Array of strings, we can then control the actions we want to be tracked and what attributes of that action should be passed along to create its records.
The getConfig
method always expects that you return an AnalyticsConfig
, but sometimes this method can take a little bit longer if you are retrieving your payload from an external server. In this case we recommend that you disable all the analytics records until a valid and more trustworthy configuration is loaded, see next how to disable all the analytics
{
enableScreenAnalytics: false,
actions: {}
}
After you have configured your analytics provider, every time an analytics event occurs within Beagle applications the createRecord
method is called and it gives access to a parameter of type analyticsRecord.
There are two types of AnalyticsRecord, ScreenAnalyticsRecord for navigation events and ActionAnalyticsRecord for action triggered events
ActionAnalyticsRecord
Property | Definition | Type |
---|---|---|
type | The type of the analytics record ‘action’ | string |
platform | The platform from which the event was triggered, e.g: WEB Angular, Android, iOS | string |
beagleAction | The Beagle Action which triggered the record | string |
component | The Beagle Component which triggered the record | Object |
event | The name of event which triggered the record e.g: onPress | string |
screen | The screen that the component belongs to | string |
timestamp | The unix representation of the time when the record was created | unix time |
ScreenAnalyticsRecord
Property | Definition | Type |
---|---|---|
type | The type of the analytics record ‘screen’ | string |
platform | The platform from which the event was triggered, e.g: WEB Angular, Android, iOS | string |
route | The route or screen identifier | string |
timestamp | The unix representation of the time when the record was created | unix time |
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.