Using Google Analytics with your Project

Now that your devices have been shipped and deployed, you may wonder how they are doing. You may want to know how many installations are active, what the devices are doing, how often they are operated with, etc. Obviously you can collect all these data by running a custom server and linking it up with your MODE project via webhooks. But you can also take care of this rather easily by integrating your project with Google Analtyics.

Google Analytics is a popular tool for collecting and analyzing website traffic data. It is free to use and powerful enough for most scenarios. Although it was not originally designed for IoT, some of its features can be adapted to provide insights to device and user activities. That’s why MODE has created the Google Analytics Smart Module to make the integration as seamless and simple as possible.

Preparation

If you are not yet familiar with Google Analytics, start by following these instructions to set up your first “property”. Note that you will be asked whether your property is a website or mobile app. While our use case doesn’t fit into either, selecting “mobile app” should be fine. Your property will be assigned a Tracking ID. You will need it to set up the Google Analytics Smart Module.

You may also want to enable the User ID feature in Google Analytics. You can find out more here.

Setting up Smart Module

Enter your MODE project on the Developer Console and select Smart Modules in the left navigation menu. Click NEW to see the catalog of modules you can add to your project.

Screenshot - Smart Modules Catalog

Locate the Google Analytics module and click ADD. You will be shown a setup form.

Screenshot - Setup Form

As in setting up any Smart Modules, enter a unique ID and description for your new module. Then enter the Tracking ID you obtained from Google Analytics earlier. Click SAVE to create the Smart Module.

Checking the Setup

To see if your Smart Module is working, open Google Analytics on a browser window and select the property you created, and go to the Reporting tab. Then under the Real-Time section in the left navigation menu, select Events. If the Smart Module was set up correctly, you will start seeing device events being shown on the dashboard.

Screenshot - Google Analytics Real-Time Events

If you don’t have any active devices deployed in the field yet, you can use the Device Simulator of the MODE Developer Console to trigger some events.

How Events are Represented

As you can see above, the device events are also presented in Google Analytics as “events”. In Google Analytics, you can expect the event to have the following attributes:

Event Category
This will be in the format `device:XXXX` where `XXXX` is the Device Class of the device that emits the event.
Event Action
This will be the `eventType` field of the event emitted by the device.
Unique User
The "home" concept of MODE is represented as a "user" in Google Analtyics. This attribute will be in the format `home:XXXX` where `XXXX` is the home ID.

See this doc for a full definition of events in Google Analytics.

Advanced Use

In Google Analytics, an event also comes with two optional attributes: Event Label and Event Value. You can tell your Smart Module how you want to map your devices’ event data to these two attributes. For example, if your devices generate sensor-update events, like this one:

{
    "eventType": "sensor-update",
    "eventData": {
        "category": "humidity",
        "measurement": 123
    }
}

And say, you want the value of category to be the event label and the value of measurement to be the event value. You can go to your Smart Module on the MODE Developer Console and click the “gear” icon to edit its settings:

Screeshot - Edit Settings

Under the Event Data Mapping section, enter sensor-update as the Event Type ID, category as Event Label Field, and measurement as Event Value Field.

Screeshot - Event Data Mapping

Now, all sensor-update events coming from your devices will be represented in Google Analytics with the desired event labels and event values. You can define data mapping for up to 5 types of events.

Limitations

Google Analytics only processes up to 500 events in a session. A session is tied to a “unique user”, which means a “home” in MODE. A session ends if no devices in a home trigger any events after a certain amount of time. However, if devices in a home trigger events too frequently (e.g. every 10 seconds), the session will stay alive forever, the 500-event limit will be reached eventually.

By default, a session terminates after 30 minutes of inactivity. If you want to avoid reaching the 500-event limit, you can shorten the length of this session timeout by following the instructions here.