Analytics 2.0

Here, you will find more about Analytics' functionalities.

Introduction

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.

Analytics provider

The first thing we need to enable the Analytics functionality is to create a provider implementing the interface below

AnalyticsProvider

PropertyDefinitionType
getConfigBeagle 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 loadedMethod
createRecordBeagle 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())
    }
    
}
  1. Declare your AnalyticsProvider implementation in your project:
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)
    }

}
  1. Set the declared provider as a Beagle dependency. You probably will set all Beagle dependencies in the same file, so your code should look something like this:
let dependencies = BeagleDependencies()
...

dependencies.analyticsProvider = MyAnalyticsProvider()

...

Beagle.dependencies = dependencies

How does it work ?

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

Action configuration

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.

Disabling the 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:

Enabling the analytics

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.

ActionAnalyticsConfig and ActionAnalyticsProperties

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

PropertyDefinitionType
attributesList of attributes to be exposed to the analytics interfaceArray <string>
additionalEntriesAny additional data you may want to send along with the actionMap<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")
        )
    )
)

Analytics configuration payload

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

PropertyDefinitionType
enableScreenAnalyticsDefault is true, when false no analytics will be generated by this system when a screen is loadedboolean
actionsA 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 trackedMap<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.

Disabling the analytics from the configuration payload

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: {}
}

Analytics Record

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

PropertyDefinitionType
typeThe type of the analytics record ‘action’string
platformThe platform from which the event was triggered, e.g: WEB Angular, Android, iOSstring
beagleActionThe Beagle Action which triggered the recordstring
componentThe Beagle Component which triggered the recordObject
eventThe name of event which triggered the record e.g: onPressstring
screenThe screen that the component belongs tostring
timestampThe unix representation of the time when the record was createdunix time


ScreenAnalyticsRecord

PropertyDefinitionType
typeThe type of the analytics record ‘screen’string
platformThe platform from which the event was triggered, e.g: WEB Angular, Android, iOSstring
routeThe route or screen identifierstring
timestampThe unix representation of the time when the record was createdunix time