> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/integrations/metrics-tools/google-analytics/how-to-use-google-analytics-in-a-metric.md).

# How to use Google Analytics in a metric

Turn a number from Google Analytics, like sessions or page views, into a live chart on any journey map.

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* The Google Analytics integration is set up at the account level. See [How to set up the Google Analytics integration](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration.md).
* Editor role at the workspace level.
  {% endhint %}

#### Add a Google Analytics metric

You can create a Google Analytics metric from two places:

* **From the workspace Metrics tab** - Click **Metrics** in the sidebar, then **+ Create metric**. The full-page **Add metric** form opens.
* **From a journey map** - Click **+ Add card** on a card slot and pick **Metric** under **Advanced cards**. In the **Add metric** picker, pick an existing metric or type a name and click **Create**. The metric opens in a compact modal; use **Full screen view** to switch to the full-page form.

The steps below walk the workspace-tab flow because the full-page form shows every field on screen. The journey map modal has the same fields in a more compact layout.

{% stepper %}
{% step %}
**Name the metric and pick Google Analytics as the source**

In the **Add metric** form, type a name that describes what the metric shows (for example, `Website signups`). In **Source**, pick **Google Analytics**.

<figure><img src="/files/zHTxnP28I3A8h62aEjUt" alt="Source dropdown open on the Add metric form, listing Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source dropdown, Google Analytics selected</p></figcaption></figure>

If you see a red **Google Analytics setup required** error below the Source field, the integration isn't connected for this account yet. Follow [How to set up the Google Analytics integration](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration.md) before continuing.
{% endstep %}

{% step %}
**Pick the metric type**

Open the **Type** dropdown and pick **Series**, **Number**, or **Comparison**. The fields below the Type dropdown depend on this choice, so set it before mapping the Google Analytics fields.

<figure><img src="/files/GArvZmyIYjtTQQy9lc4B" alt="Type dropdown open on the Add metric form, showing Series, Number, and Comparison options, each with a small icon to the left of the label."><figcaption><p>Type dropdown, three metric types</p></figcaption></figure>

For which type fits which question, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric.md).
{% endstep %}

{% step %}
**Map the Google Analytics fields**

With **Series** selected, the form shows a **Date range** field, a **Google analytics metric** selector, and a **Google Analytics dimension** selector. The metric is the number you're plotting; the dimension groups it.

<figure><img src="/files/KNaqHVN11TveI7rnKUYT" alt="Add metric form with Source set to Google Analytics and Type set to Series. The left column shows Name, Source, Type, a Date range dropdown, a Google analytics metric dropdown, a Google Analytics dimension dropdown, and Filters sections for AND and NOT conditions. The right column shows the Default card preview with a chart-type strip and Chart heading and subheading fields."><figcaption><p>Add metric, Google Analytics fields for a Series metric</p></figcaption></figure>

* Pick the number to plot under **Google analytics metric** (for example, **Sessions**, **Page views**, or **Active users**).
* Pick how to group it under **Google Analytics dimension** (for example, **Country**, **Device**, or **Page title**).
* Set a window under **Date range**.

Both selectors list only the metrics and dimensions an Admin chose when connecting the property, so the lists are deliberately short. If the value you need isn't there, ask whoever set up the connection to add it. For what each field means, see [Field mapping](#field-mapping) below.

{% hint style="info" %}

#### **Important: Number and Comparison metrics show different fields**

A **Number** metric drops the series-specific options and may ask for an aggregation, since it resolves to one value rather than a sequence. A **Comparison** metric collects two values to compare. The Google analytics metric and dimension selectors work the same way across all three types.
{% endhint %}
{% endstep %}

{% step %}
**Set the chart options**

In the **Default card preview** panel on the right, pick a default chart type from the strip (**Bar chart**, **Horizontal bar**, **Pie chart**, **Line chart**, or **Number**). Add an optional **Chart heading** and **Chart subheading** for labels above the chart. These settings are the defaults for new metric cards built from this metric; each card can override them on a journey map. For the full chart-options reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric.md).
{% endstep %}

{% step %}
**Save the metric**

Click **Save**. The metric appears in the workspace **Metrics** list and is ready to drop onto any journey map as a metric card.

For placing the metric as a card and customising it per-map, see [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards.md).
{% endstep %}
{% endstepper %}

***

#### Field mapping

Google Analytics organises data as a **Property** that holds **Dimensions** and **Metrics**. The example below walks a **Series** metric, the most common type, showing sessions grouped by country.

* **Property** - A website, mobile application, or device; a container for the data Google Analytics collects. The property is chosen once when the integration is connected, so it isn't a field on the metric form. Every metric you build pulls from a property an Admin already connected.
* **Dimensions** - Attributes used to filter and group your data, such as **Country**, **Device**, or **Page title**. The **Google Analytics dimension** selector lists the dimensions curated at connection time. Picking **Country**, for example, gives one data point per country.
* **Metrics** - Quantitative measurements of activity on your site or app, such as **Sessions**, **Page views**, or **Goal completions**. The **Google analytics metric** selector is the number that gets plotted.

You can narrow the data further with **Filters (items to include)** for AND conditions and **Filters (items to exclude)** for NOT conditions, each pairing a dimension with a value.

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the dimension to the journey stage**

Pick the **Google Analytics dimension** that matches what the journey stage is about. A regional journey reads cleanly with the **Country** or **City** dimension; a journey about a specific flow reads better grouped by **Page title** or **Page path**. The metric renders one data point per dimension value, so a focused dimension keeps the chart legible.
{% endhint %}

***

#### Refresh behaviour

Google Analytics metrics refresh on access, not on a timer. When you open the **Metrics** section or load a journey map with a Google Analytics metric, Smaply checks the data and pulls fresh values from Google Analytics only if what it has is more than about an hour old. There's no manual refresh button and no constant background sync.

Because of that hour-long window, events that just happened in Google Analytics may not appear in Smaply immediately. The next time the metric or map loads after the window passes, the values catch up.

***

#### Troubleshooting

If the connection itself isn't working, see [How to set up the Google Analytics integration](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration.md) for connection troubleshooting. The issues below cover data-side problems once the connection is in place.

<details>

<summary><strong>The metric or dimension dropdown is empty or missing a value you need</strong> - Curated at connection time</summary>

The **Google analytics metric** and **Google Analytics dimension** selectors only list the metrics and dimensions chosen when the property was connected. The list is kept short on purpose, so a value you expect may simply not have been added.

Ask whoever set up the Google Analytics integration to add the metric or dimension you need on the **Configure Google Analytics** page, then reopen the metric form.

</details>

<details>

<summary><strong>No property's data is selectable, or the metric returns nothing</strong> - Access or API issue</summary>

The metric builds but comes back blank, or no Google Analytics data is available to pick from.

* The connection identity may not have access to the property. For service-account auth, the service account email must be granted on the property in Google Analytics under **Admin > Property Access Management**. For OAuth, the signed-in Google account must have that access itself.
* The property may be listing fine but returning no numbers because the **Google Analytics Data API** is disabled in the Google Cloud project. The Admin API populates the property and field lists; the Data API serves the actual values, so one can work while the other doesn't.

Both are connection-side fixes. See [How to set up the Google Analytics integration](/integrations/metrics-tools/google-analytics/how-to-set-up-the-google-analytics-integration.md).

</details>

<details>

<summary><strong>A metric returns no data despite a valid metric and dimension</strong> - Incompatible pairing (Google Analytics behaviour)</summary>

Some Google Analytics metric and dimension combinations aren't compatible and return nothing, even when each is valid on its own. This is a Google Analytics platform constraint, not a Smaply one.

Edit the metric and try a more standard pairing (for example, **Sessions** by **Country**) to confirm the connection works, then narrow from there.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level.md).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Set up Google Analytics</strong></td><td>Connect Google Analytics at the account level using service account or OAuth.</td><td><a href="/pages/qVm6oVefSmnvkYdAi5u6">/pages/qVm6oVefSmnvkYdAi5u6</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Place a metric card on a journey map and customise its display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpdesk.smaply.app/integrations/metrics-tools/google-analytics/how-to-use-google-analytics-in-a-metric.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.