You can add the Umbraco Engage Analytics JavaScript file to your website by placing this code before the closing </body> tag of your website.

<script src="/Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.js"></script>

When this file is included, Umbraco Engage sends the following data to the server before the visitor navigates to another page:

• Scroll Depth: Tracks the maximum scroll depth in both pixels and percentage of the page. For example, a user might scroll to 93% of the page height, which could equal 967 pixels.

• Total Time on Page: The total time on page is measured in milliseconds. It is defined as the time difference between the page load and the moment the user leaves the page.

• Engaged Time on Page: This measures the time the user is active on the page and in our opinion is more accurate than the total time on page. This script measures only the time when you are scrolling or clicking on the page in the active tab. It excludes idle time, such as when you are getting coffee or working in another tab. A 5-second grace period is used to define engagement. For more information, see this blogpost.

• Clicks Tracked: All clicks to the following URLs are measured:

  • External domains

  • .pdf, .doc, or .docx document

  • An internal onpage link which is defined by an anchor link (#intro)

  • mailto: and tel: links

When a visitor runs an Adblocker or cookieblocker the visitor is likely not tracked in Google Analytics. With Umbraco Engage you can still track this visitor.

This is made possible by a JavaScript file that you can include before the closing body-tag in your HTML:

<script src="/Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.blockerdetection.js"></script>

If you include the script one of the following events is sent:

• If Google Analytics is blocked in the browser of the visitor: umbEngage("send", "event", "Tracking", "Blocked", "Google Analytics");

• Otherwise, the following event is sent: umbEngage("send", "event", "Tracking", "Allowed", "Google Analytics");

To see the statistics of this event go to the Analytics section of Umbraco Engage and open the 'Events' report. Look for the category with the name 'Tracking'.

We have included a bridging JavaScript file to "catch" all Google Analytics event calls and send them to Umbraco Engage. If you have a website with Google Analytics events defined you do not have to change the code to send them to Umbraco Engage. The only thing you need to do is include our JavaScript bridge.

Google Analytics 4 (GA4)

Add a reference to umbracoEngage.analytics.ga4-bridge.min.js:

<script src="~/Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.ga4-bridge.min.js"></script>

Excluded events

The following built-in GA4 events are excluded by the GA4 bridge:

• click

• file\download

• form\start

• form\submit

• page\view

• scroll

• video\complete

• video\progress

• video\start

• view\search\results

This is based on official Google Analytics documentation - all events tagged (web).

Customize which events are sent

If there are specific events you want to exclude from being sent to Umbraco Engage you can customize the behavior.

Say you want to exclude all events that have category "X" and action "Y". To do that, add the following JavaScript to your website. Make sure umbracoEngage.analytics.js has been loaded when the code executes.

<script>
if(typeof window.umbEngage === "function" && typeof window.umbEngage.onSendEvent === "function")
{
    window.umbEngage.onSendEvent(function(evt) 
    {
        if(evt.fields.category == "X" && evt.fields.action == "Y")
        {
            // Do not send events with category "X" and action "Y" to Umbraco Engage
            evt.cancel();
        }
    });
}
</script>

It is also possible to change the category/action/label/value properties of evt.fields to modify the values we send to Umbraco Engage.

When using Google Tag Manager you can collect all events in Umbraco Engage. This is set up in the same way as classic Google Analytics.

To include the file add the following code before the closing body tag in your HTML:

<script src="~/Assets/Umbraco.Engage/Scripts/umbracoEngage.analytics.ga-bridge.js"></script>

Umbraco Engage helps you with some additional scripts and views.

They are all stored in the /Assets/Umbraco.Engage/Scripts/ and the /Views/Partials/Umbraco.Engage/ folders.

Find more information about the scripts:

• Bridging Library for Google Analytics

• Bridging Library for Google Tag Manager

• Google Analytics blocker detection

You can also learn how to create your custom events.

You can send custom client-side events to Umbraco Engage. An example could be if somebody pushes a button.

This is done by executing JavaScript using the following format:

The following example sends an event that tracks the category "Tracking", the action "Blocked" and the label "Google Analytics":

You can track all these events in the Events report of the Analytics section.