Custom Event & Custom Props

Metricalp defaultly collect screen_view events to track sessions, page hits etc. But you can disable this auto collection (check API Reference) or you may want to collect some other custom events while even it is active. To achieve manual collection of 'screen_view' or any custom event, there are two ways to do it. These are via JavaScript API or via HTML data attributes. Also, you can send custom props with these events. We will describe these two ways and custom props in this page.

Custom Events

First things first, screen_view is a 'system event'. We are calling any other events are 'custom events.' Custom events need to be triggered manually by your system. We will show how can you trigger in below. You can also manually trigger screen_view events with below methods addition to custom events. But there is another important point which that you can allow any custom event in your system or you can allow only specific events. It is totally up to you and configurable. You can configure this in Tracker Settings. For example you can allow only click_save, click_buy custom events (screen_view is always allowed by system also) and any other event type will be ignored. Or just allow all custom events. Again, it is up to you.

We will show two ways of custom event collection:

1. Via JavaScript API

If you integrated Metricalp properly, it will attach an object named metricalp to global window object. object. This object has an event method and you can use it to send custom events. This method takes one argument which is an object. This object must have type field which is the name of event. You can attach other custom props to this object. For custom props please check below in this page. Example custom event via JS API:

window.metricalp.event({
  type: 'click_buy',
  color: 'red'
});

Also, like React and NextJS frameworks, we have custom integration libraries and their custom event produce APIs are different than this pure logic. Please check their documentations.

2. Via HTML data attributes

Metricalp, defaultly will check your document about is there any element with data-metricalp-event attribute.

If there is an element with this data attribute, then if it is a form element it will listen submit event otherwise it will listen click events for that element. When event is triggered, it will produce an event with the name of value of this data attribute. Also, it will attach all data attributes of this element which starts with data-metricalp- to event as custom props. For example:

<button data-metricalp-event="click_buy" data-metricalp-color="red">Buy</button>

When a visitor clicks this button it will produce same event with the via JS example above.

Custom Props

Custom events are very powerful to track meaningful data based on your needs. Every event will have basic data like browser, country, device etc. But, you may want to attach additional data to these custom events (or screen_view event). We are calling this extra additional data as custom props. You can attach custom props to custom events via JavaScript API or HTML data attributes. We will show how can you attach custom props below.

Defaultly, you can attach custom props with custom_prop1, custom_prop2, custom_prop3, custom_prop4, custom_prop5 keys. We are allowing 5 custom props per event at the moment but we are planning to increase this number in future. But for example

window.metricalp.event({
  type: "screen_view",
  custom_prop1: "red"
});

this can be hard to remember which custom prop keeps which data. To prevent this confusion, you can set aliases to per custom prop per event type. For example, if you set `color` as alias for custom prop 1 in Tracker Settings for screen_view events then you will view that custom prop as color in your dashboard on screen_view events. Now you can create events like:

window.metricalp.event({
  type: "screen_view",
  color: "red"
});

Much more readable right? But for example you can set `username` as alias for custom prop 1 in Tracker Settings for click_save events then you will view that custom prop as username in your dashboard on click_save events.

window.metricalp.event({
  type: "click_save",
  username: "John"
});

You can still continue to use custom_prop1 syntax, too even you have defined an alias for that custom prop. The beauty of this is, these aliases specific for each event type. This helps you to collect meaningful data and view them easily. In the above custom events section example we also showed how can you attach custom props via HTML data attributes: data-metricalp-color="red". Also custom_prop1 syntax is valid for HTML data attributes, too: data-metricalp-custom_prop1="red" while in HTML data attribute names can include underscores.

As we said above you will find this alias configuration in Tracker Settings screen. To learn custom prop aliases please check Configure Trackers documentation page.

Lastly, if you want to attach some custom props for some event types automatically, you can define 'sharedCustomProps' like:

<script>
        window.metricalp = window.metricalp || {
          queue: [],
          sharedCustomProps: {
            _global: { custom_prop3: "v1.0" },
            screen_view: {
              color: "red",
              custom_prop2: "Test",
            }
          },
          event: function (e) {
            this.queue.push(e);
          },
        };
</script>

'_global' key is a special key in here. It is a generic holder and not an event type. When you put some custom props in '_global' they will be attached to ALL event types. In the above example, custom_prop3 will be attached to all event types. But custom_prop2 and color will be attached to only screen_view events. If you define a custom prop in a specific event type and also in _global, event specific one will override the same custom prop in _global. In the above example color is a custom prop alias. When you use custom prop alias syntax instead of custom_prop1 like syntax in sharedCustomProps, you must have that alias defined on that event type in Tracker Settings otherwise it will be ignored for not defined event types. You should put above script tag before the Metricalp script tag which it can attach sharedCustomProps to the automated screen_view events. If you are using React library then you can define sharedCustomProps as prop:

<MetricalpReactProvider
  tid="mam123456"
  initialSharedCustomProps={{
    _global: { custom_prop3: "v1.0" },
    screen_view: { color: 'red', custom_prop2: 'Test' } 
}}>

You can find more information about sharedCustomProps with React library in the React and NextJS documentations.

Now you learned custom events and custom props, for example you can create 'error' events when your system has an error and you can attach error logs as props (addition to browser, device info etc default props which automatically collected). Or you can use custom props for A/B tests. Use case scenarios are unlimited based on your imagination and needs.

With custom events and custom props, you can get more deep analytics about your visitors. This is the beauty of Metricalp 💜