Vain: A Tangible Google Analytics Display

Vain is a Photon (a $20 web enabled micro-controller that is similar to an Arduino) based project that displays real-time Google Analytics data on a real-world display. Since the device does not have any physical user input mechanisms, it relies on Google’s OAuth 2.0 for Limited-Input Device protocol for authenticating the appropriate Google Analytics account. Webhooks via Particle.io’s free service are used to authenticate the device and then repeatedly request the current amount of real-time active users on a given website. This data is then displayed on an external display.

Required Hardware

• Particle Photon (~$19.00 USD)
• Display (Many display options can work but a Liquid Crystal Display is likely the cheapest and easiest option) (~$15.00 USD)
• Breadboard (~$6.00)
• Jumper Cables (~$6.00)

Getting Access to Google’s APIs and Collecting Your Credentials

Step 1. Create a new project with Google API Manager:

To create a new project within the Google API manager, go to https://https://console.developers.google.com. Once at that URL, click the small downward facing triangle in the main navigation and then click the plus symbol "+" to create a new project.

If you get stuck or the interface has changed, see this URL (https://support.google.com/cloud/answer/6251787) for more detailed information and up-to-date instructions on creating a new project within the Google API manager.

Step 2. Enable the Google Analytics API for your project:

While within your newly created project and while on the Dashboard tab, click “+Enable API” link and search for “Analytics API”.

Step 3. Create credentials for your newly enabled API access:

Now you have created a new project, you need to create credentials in order to access it. Click the “Credentials” menu item on the subnavigation and then click “Create credentials”. Next choose the “OAuth client ID” form of credentials. If required, give your product a name to be shown to users. (If Google requires this step for your project, it will prompt you for this information). When asked to specify your Application type, select “Other”, give the set of credentials a name (example, Vain Photon) and click “Create”. Store the resulting “Client ID” and “Client Secret“ in a secure location. You are going to need this information shortly.

Step 4. Request access to the Google Analytics Real Time Beta API.

At the time of creating this project, the Google Analytics Real Time Reporting API was in limited beta. This meant you needed to sign up for access in addition to enabling the API on your API manager. To do this, visit this URL https://developers.google.com/analytics/devguides/reporting/realtime/v3/ and fill out the accompanying form. Depending on the Google’s policies and the current status of the Real Time Analytics API, you may or may not be required to this step. Note: The “project number” that is required on the form is located within your project “Settings” menu within your API Manager.

A Note on Authenticating on a Limited-input Device

Normally when authenticating with OAuth you simply input your credentials into the device that needs access. For better or for worse, your Vain device does not have any inputs which means that the normal method of authenticating with OAuth is not possible. As such we must use a protocol called "OAuth 2.0 For Limited-input Device". The full documentation for OAuth2ForDevices is here. This codebase follows this protocol and each of the required steps and the corresponding code is documented within comments within the codebase. To keep things clear though, the steps for this protocol are included below:

1. Your application sends a request to Google's authorization server that identifies the scopes that your application will request permission to access.
2. The server responds with several pieces of information used in subsequent steps, such as a device code and a user code.
3. You display information that the user can enter on a separate device to authorize your app.
4. Your application starts polling Google's authorization server to determine whether the user has authorized your app.
5. The user switches to a device with richer input capabilities, launches a web browser, navigates to the URL displayed in step 3 and enters a code that is also displayed in step 3. The user can then grant (or deny) access to your application.
6. The next response to your polling request contains the tokens your app needs to authorize requests on the user's behalf. (If the user refused access to your application, the response does not contain tokens.)

The image below illustrates this process:

(Image credit: OAuth2ForDevices)

The scope that we will be using with this project is "https://www.googleapis.com/auth/analytics.readonly".

Creating Your Webhooks

Webhooks are a mechanism for querying information from the web. You could certainly make the applicable HTTP requests from the the device itself but using webhooks decreases bandwidth usage and perhaps more importantly gives you better logging and debugging capabilities than manual HTTP requests.

Creating a webhook on Particle.io in order to query Real Time Active Users

This section is still being developed. Description. Explain JSON.

Authenticating your device with Google's API requires three separate webhooks:

1. WEBHOOKNAME

This section is still being developed.

2. WEBHOOKNAME

This section is still being developed.

3. WEBHOOKNAME

This section is still being developed.

A note on Mustaches

The Photon's firmware (which is written in C++) can't natively parse JSON. While we could include a JSON parsing library in our code, we are going to use a simpler method in order to maintain a small file size on the micro-controller program.

To do this, we format the webhook responses using a format called Mustache. You can read the Mustache format documentation here but general idea is we are going to specify the keys of the JSON data that we want and then separate these pieces of datum with tildes ~ so that we can then split them in our code (this is an easy way to return multiple pieces of data from our webhooks)

Flashing Your Photon with the Vain Firmware

Now that the webhooks are created, we need to load firmware onto the Photon that calls and processes these webhooks. The firmware that you need is the very same firmware that is in this repo. To use it, all you need to do is download it and then upload it to your Photon.

Download the code from Github

In order to upload the firmware to your Photon, you first need to download it to your computer. To do this, simply follow these instructions on how to clone or download a repo from Github.

Upload/flash the firmware to your Photon

Once the codebase is on your computer, you can use either the Particle Web IDE, which is called Build or the downloadable IDE, which is called Dev to send the code to your device. Instructions for sending code (called flashing) to your Particle device is here.

Wiring Your Device

Now that your accounts are configured, the appropriate webhooks are set up and the firmware is loaded onto your device, your last remaining step is to wire up your micro-controller and physical display.

Breadboard Diagram of a Simple LCD Display Setup

Common LCD pin mappings are shown below but don't blindly trust these, check them against your device's official documentation:

That's it!

You now have your very own tangible Google Analytics display. Your vanity can now be known to all :-p

If you have an issues or code recommendation, feel free to submit pull requests or issues via Github.

Known Issues:

• The below issues should be moved to Github issues.
• Fix bug that creates 1 cycle lag between getting the user count and displaying the count
• Fix bug of when number of users gets stuck at last value when value switches to 0
• Fix bug that appears to be preventing code from executing after line 176
• Extract client_id and store as part of customer data? I don't want it stored in the generic webhook
• Implement more robust error handling, what happens if Google API requests don't return expected results?