Event Tracking

Tracking events in your kiosk or other forms of interactive signage makes it possible to determine important usage metrics such as which areas of the app is generating the most user interest. Revel Digital provides methods in player scripting as well as in our REST API for tracking events. Visualization is an important aspect of event tracking, and for this we have event specific charts available in AdHawk with powerful filtering capabilities. It's also possible to export the data for use in other 3rd party tools such as Mixpanel.

Requirements

• Devices must be on a Plus service level (Professional+ or Enterprise+)
• Android app version 2.1.188 or later

Instrumentation

Instrumenting your signage for event tracking generally involves adding snippets of script to a template. In this article we will demonstrate the tracking of a button press in a sample kiosk template.

Our Android player API provides the following Controller methods:

View the Controller documentation here

The track() method is the primary event tracking method responsible logging events. If it's important to also track the time component of an event, then you can use timeEvent() to start the event timer. Calling track() will then capture the time elapsed since timeEvent() was called in the 'dwell' property of the event.

A session ID is also associated with each event which can be used to group events. Setting or generating a session ID is done with methods available on the Event class.

View the Event class documentation here

Demo Template

Our demo will consist of a media gallery along with a simple button used to start and stop the playback. We will track when the gallery was started and stopped with two unique events. We will use the timeEvent() function associated with the second event to give us a dwell time.

The three zones in the template are the Media Gallery, Shape, and Text. The shape zone is just a background shape for the button. The text sits on top of the shape and will be our click target for interactivity. Clicking the 'toggle' text will start and stop the media gallery.

The template script we are using looks like this:

/* [GENERATED] Basic scripting template for the Android platform */
import java.util.List;
import java.util.Iterator;
import android.view.*;
import android.animation.*;
import com.reveldigital.player.api.*;

/* [GENERATED] The listener interface for receiving template events */
Controller.addTemplateListener(new TemplateListener() {
 onInitialized() { /* Triggered when the template is created */
 Media_Gallery_1.setAutoStart(false);
 }
 onSuspended() { /* Triggered when the template is stopped */
 }
 onResumed() { /* Triggered when the template resumes playing */
 }
 onTerminated() { /* Triggered when the template is destroyed */
 }
 onClicked() { /* Global click handler for entire template */
 }
});

boolean playing = false;

Text_1.setOnClickListener(new View.OnClickListener() {
 onClick(View v) {
 if (playing = !playing) {
 Media_Gallery_1.start();
 Controller.track("Start Gallery", null);
 Controller.timeEvent("End Gallery");
 } else {
 Media_Gallery_1.stop();
 Controller.track("End Gallery", null);
 }
 }
});

The script is first initializing the gallery with setAutoStart(false) which will prevent it from running at startup. Then we add the click handler for the text zone which is both toggling the gallery play state, as well as calling the event tracking methods of the Controller.

The two events we are tracking are 'Start Gallery' and 'End Gallery', with 'End Gallery' having a time component associated with it. You'll notice we start the timer by calling timeEvent('End Gallery') when the gallery is started. Calling track('End Gallery') will then give us the elapse time since timeEvent() was called.

Collecting Data

With the template deployed to a device you can now click the button a few times to start generating event data. Generated events are stored on the device then forwarded to the server every 30 minutes. You can force the device to synchronize data with the server immediately by sending a 'Synchronize Now' command.

Analytics

Once the server has received the event data it will be available in AdHawk for visualization and reporting. Simply navigate to the AdHawk section of the CMS, then click the Events subsection. If the device you are working with does not appear for selection, make sure the device is on a Plus service level. To switch service levels, navigate to the device details page and find the Change Service Level button on the lower right side of the page.

You'll see both of our events are shown here along with an average dwell time for the End Gallery event.

Filtering

Advanced filtering of events is possible by clicking the Event Explorer toolbar. Filtering allows you to narrow results down to just the specific events you are after. Once your filtering criteria has been selected you may save the filter for use at a later time.

REST API Tracking

It's also possible to use our REST API for generating events. This may be necessary if you are integrating web based content within your template. An API key is required and may be generated for your account in the Account Information section of the CMS. Documentation is available in Swagger format here:

https://api.reveldigital.com/swagger/index.html#/Devices/Devices_PostEvent