# Looker Studio

> Your Nvivio numbers in Looker Studio reports, next to your other data, by date, page, source, country and device, with a read-only API key.

The Nvivio connector for [Looker Studio](https://lookerstudio.google.com) puts your numbers in Looker Studio reports and dashboards, next to your other sources. It reads them from the [REST API](https://nvivio.com/docs/api) with a read-only key: nothing in Nvivio can be changed through it.

- **What you need:** a plan with the API ([Plans and limits](https://nvivio.com/docs/plans#the-api)) and an API key with the scope `read`.
- **One site per data source.** Add a data source for each site you want in a report.
- **The same numbers as the dashboard,** from the same API, in the site's time zone.

## Connect

1. Make a read key in the user menu › **API and AI assistants** (`/app/api`), as owner or admin. Copy it: you see it once.
2. Add the connector to Looker Studio. Until it is listed in Looker Studio's gallery, you set it up from our files in two minutes: see [Add the connector](#add-the-connector).
3. Authorize the connector, paste the key and choose **Submit**.
4. Pick the site, optionally add filters, and choose **Connect**. Looker Studio shows the fields; choose **Create report**.

The key stays in your Google account's settings for this connector and is sent only to `nvivio.com`. **Revoke** it in Nvivio at any time; the data source then stops reading and asks for a new one.

## Fields

**Dimensions**

| Field | What it is |
|---|---|
| Date | The day, in the site's time zone. |
| Channel | Where visits came from, grouped: search, social, AI, email, paid, direct… |
| Source | The referring website. |
| UTM source, UTM medium, UTM campaign | The campaign tags of the visit. |
| Entry page, Page, Exit page | The first page of a visit, every page viewed, the last page. |
| Event | [Custom events](https://nvivio.com/docs/events) and automatic ones (outbound links, downloads). |
| Country, Region, City | Where visitors were. Country is a country code, so maps work. |
| Language, Device, Browser, Operating system, Hostname | The visitor's browser and the address of your site. |

**Metrics**

| Field | What it is |
|---|---|
| Visitors | Unique visitors. A visitor on two days counts on each day, so a sum over days is more than the visitors of the whole period. |
| Visits | Visits (sessions). |
| Pageviews | Pages viewed. With **Page**, how often each page was viewed. |
| Events | With **Event**, how often each event happened. |
| Views per visit, Bounce rate, Visit duration | As in the dashboard; visit duration is an average in seconds. |

With **Page**, only Visitors and Pageviews have a value; with **Event**, Visitors and Events. The other dimensions have every metric.

## Dimensions and dates

Nvivio splits by one dimension at a time, as the dashboard does:

- **No dimension:** the totals of the date range.
- **Date only:** one row per day.
- **One dimension:** its top 500 values in the date range.
- **Date and one dimension:** the top 500 values of each day, for up to 31 days per request; for a longer range, leave out the date.

A chart with two dimensions other than the date (such as Country and Device together) gets a message instead of numbers. Use a filter for the second one.

## Filters

The data source's **Filters** field takes the [filters of the dashboard](https://nvivio.com/docs/filters-and-periods#filter-syntax), one per line, such as `country:BE`, `referrer:google.com`, `path:~/blog/*` or `device:!mobile`. They apply to every chart of that data source. Looker Studio's own filters and controls work too, on the rows that come back.

## Limits

Every request of the connector counts towards your organisation's API requests per hour ([Limits](https://nvivio.com/docs/api#limits)). The connector keeps each answer for 5 minutes, so a report that refreshes or opens twice does not ask again. A chart by date and dimension asks once per day. Above the limit the chart says so; it works again the next hour.

## Add the connector

A Looker Studio connector is a small Google Apps Script project. Ours is two files:

1. At [script.google.com](https://script.google.com), choose **New project**.
2. Replace the contents of `Code.gs` with [nvivio-looker-studio.js](https://nvivio.com/downloads/nvivio-looker-studio.js).
3. In **Project Settings**, tick **Show "appsscript.json" manifest file in editor**, open `appsscript.json` and replace its contents with [nvivio-looker-studio.json](https://nvivio.com/downloads/nvivio-looker-studio.json).
4. Choose **Deploy › Test deployments** and copy the **Head deployment ID**. Open `https://lookerstudio.google.com/datasources/create?connectorId=` followed by that id, and go on with step 3 of [Connect](#connect).

The connector reads only the public API, with your key, and sends it nowhere else (the manifest allows requests to `nvivio.com` only). To share it with colleagues, choose **Deploy › New deployment** and share the Looker Studio link with that deployment's id.