View source for Connected Devices/Projects/Metrics/Integration

== Project Overview ==

The Metrics Project uses Google Analytics capabilities as a collection point for the various trains/projects.  The [https://developers.google.com/analytics/devguides/collection/protocol/v1/ 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".
*[https://sql.telemetry.mozilla.org Re:Dash] - a 3rd party tool that can be used to formulate SQL queries against the BigQuery Database.
*[https://www.google.com/analytics/360-suite/data-studio/ Google Analytics Data Studio]

== Steps to adding Metrics to your project ==
# 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.
# Review the section below on Instrumenting your Project with Metrics and choose an integration method.
# Use the Google Analytics console to quickly validate that your data is formatted correctly and arriving.  The Metrics team can help you with this.
# 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)
* Javascript wrapper
* Formulate a POST request with your own tools.

=== Rust Library ===
The Rust library crate is located [https://crates.io/crates/metrics-controller here].  The GitHub account for the project is [https://github.com/tamarahills/metrics_controller here].  The Readme on the GitHub account has full instructions for building as well as sample code for integrating with the following:
*[https://github.com/tamarahills/metrics_controller/blob/master/examples/JavaMetrics.java Java]
*[https://github.com/tamarahills/metrics_controller/blob/master/examples/ffi_test.c C]
*[https://github.com/tamarahills/metrics_controller/blob/master/examples/main.rs Rust]

=== Javascript Wrapper ===
A [https://github.com/tamarahills/metrics_controller/tree/master/js Javascript wrapper] to make it easier for projects that can more easily leverage Javascript.

=== 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.

{| class="wikitable"
|-
! 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 || 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.  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"
|}