Connected Devices/Projects/Metrics/Integration

From MozillaWiki
Jump to: navigation, search

Project Overview

The Metrics Project uses Google Analytics capabilities as a collection point for the various trains/projects. The Google Analytics Measurement Protocol is the API that the Metrics Project uses. It's more appropriate for IoT projects than Classic Google Analytics which is more e-Commerce related.

Once data is collected, it's stored in a Google BigQuery instance. There are several visualization options available for you to choose from:

  • Google Analytics Console - More appropriate for checking if your data arrived and simple graphs such as how many users are currently "live".
  • Re:Dash - a 3rd party tool that can be used to formulate SQL queries against the BigQuery Database.
  • Google Analytics Data Studio

Steps to adding Metrics to your project

  1. Contact the Metrics team and let us know you are adding metrics. We can request accounts for the visualization tools on your behalf and get you setup with the property ID.
  2. Review the section below on Instrumenting your Project with Metrics and choose an integration method.
  3. Use the Google Analytics console to quickly validate that your data is formatted correctly and arriving. The Metrics team can help you with this.
  4. Use the visualization tools to create graphs. The Metrics team can share some sample graphs with you once your receive logins to the tools.

Instrumenting your Project with Metrics

As a project wanting to send metrics you have the following choices:

  • Rust Library integration (for Rust, c/cpp, Java projects)
  • Node.js module
  • Formulate a POST request with your own tools.

Rust Library

The Rust library crate is located here. The GitHub account for the project is here. The Readme on the GitHub account has full instructions for building as well as sample code for integrating with the following:

Node.js module

This Node.js module is a Javascript wrapper around the Google Analytics Measurement Protocol.

Formulating a POST request with your own tools

Some projects may have capabilities to build their own requests with tools. The following is the format for any POST request:

The URL of the POST is: https://www.google-analytics.com/collect

The body of the POST should be in the following format: v=1&t=event&tid=UA-XXXXXXXX-1&cid=add2b5bb-4f86-4dc2-bbdf-fd42cd7a75ed&ec=event_category&ea=event_action&el=event_label&ev=100&an=smart_home&av=1.0&ul=en-us&cd1=linux&cd2=1.2&cd3=raspberrypi&cd4=arm&cd5=rust&cd6=20160525000000

You can put multiple of these event key/value pairs in one POST if you need to. Just need to separate them with a newline. Each line is considered an "event" in Google Analytics Terms. Use /collect for one event and /batch for multiple events in the same POST.

Parameter Description
v Version of the Measurement Protocol. Leave this as 1
t This is the hit type in the Measurement Protocol. Set this to "event"
tid Tracking Id. Contact Metrics team for this number. It is a String in the format UA-XXXXXXXX-X. It is the property ID for all Connected Devices projeccts. This will be the same for all requests.
cid Your device ID should go in here. It should be a unique string (a uuid is nice).
ec event category. As an example of a user playing a video this could be something like "video"
ea event action. In the above example, this could be "play"
el event label. In the above example, this could be "myvideo.mov"
ev event value. This is an integer only field. In the above example, the value is 1 as the user played the video once.
an app name. This is the name of your project/app. It is a string and should be unique so you can easily filter your data from the rest of the CD projects. Example: "myiotapp"
av App version. the version of your app. Example: "1.0"
ul User Language (locale). Example: "en-us"
cd1 Operating system. Example: "linux"
cd2 OS version. Example: "1.2"
cd3 Device name. Example: "raspberrypi"
cd4 Device Architecture. Example: "arm"
cd5 App Platform. Example: "rust"
cd6 App Build ID. Example "20160525000000"
cd7 Timestamp. Example "2016-05-25 22:36:57"