> 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-set-up-the-google-analytics-integration.md).

# How to set up the Google Analytics integration

An Admin connects Google Analytics once at the account level. After that, anyone in the workspace can build metrics from your GA properties.

{% hint style="info" icon="clipboard-list" %}

#### In this guide

1. [Set up the Google Analytics integration](#set-up-the-google-analytics-integration)
2. [Configure Google Analytics in Smaply](#configure-google-analytics-in-smaply)
3. [Verify the setup](#verify-the-setup)
4. [Use Google Analytics in a metric](#use-google-analytics-in-a-metric)
5. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Google Analytics integration

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FAtfXz6ZuLY4oLHMBYOxK%2Fsetup_google_analytics.mp4?alt=media&token=6d479bc8-4f66-4615-bd28-95ee929878e1>" %}

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

#### Prerequisites

* Admin role at the account level
* A Google account with access to the Google Analytics 4 property you want to connect
* For service account auth: access to a Google Cloud project (you can create one as part of setup)
  {% endhint %}

In Smaply, go to **Account Settings > Integrations** and click **Set up** next to **Google Analytics**.

<figure><img src="/files/WGPVzrjjsG4FOQfxa3g1" alt="Smaply Account settings page with the Integrations tab open. The Metrics integrations section lists Google Analytics, Office 365 Excel, Power BI, Google Sheets, and Qualtrics, each with a Set up button to the right."><figcaption><p>Account settings > Integrations</p></figcaption></figure>

The **Configure Google Analytics** page opens with two options under **Select integration type**: **Service account** (selected by default and marked **Recommended**) and **Login with your Google account (oAuth)**.

<figure><img src="/files/sB8gEkRxIrbIiIdtjtc2" alt="Configure Google Analytics page in the unconfigured state. The left pane shows Select integration type with Service account selected (marked Recommended) and Login with your Google account (oAuth) below it. The right pane shows Configure service account with a Service account file label, the instruction Upload your Google Analytics service account JSON file, a No file uploaded yet empty state, and an Upload File button."><figcaption><p>Configure Google Analytics, unconfigured</p></figcaption></figure>

Pick the authentication method that fits:

* **Service account (recommended)** - Server-to-server, so the connection isn't tied to one person's login. Best when your team works on the same Smaply account.
* **OAuth** - Signs Smaply in as you. Simpler when only one person needs the data.

{% tabs %}
{% tab title="Service account (recommended)" %}
{% hint style="info" icon="tag" %}

#### Plan availability

Service account auth is available on the **Governance** plan only. OAuth auth (the other tab) is available on all plans.
{% endhint %}

A service account is a Google identity that connects Smaply to Google Analytics without being tied to a single person's login. You create the account in Google Cloud, give its email Viewer access to each GA property, download its key file, and upload that file in Smaply.

Keep the **Configure Google Analytics** page open in another tab. You'll come back to it at the end of this flow to upload the key file.

{% stepper %}
{% step %}
**Create a Google Cloud project**

In the [Google Cloud Console](https://console.cloud.google.com), create a new project for the integration. We recommend naming it `Smaply-GA` so the purpose is obvious if you audit projects later.

{% hint style="info" %}
A dedicated project keeps API access organised so you can see at a glance which credentials belong to Smaply.
{% endhint %}
{% endstep %}

{% step %}
**Enable the Google Analytics APIs**

Inside the project, open **APIs & Services > Library** and enable both:

* **Google Analytics Data API**
* **Google Analytics Admin API**

The Data API reads your metric data; the Admin API is what populates the property list in Smaply. Both must be enabled.

{% hint style="warning" %}
These APIs are not enabled by default in new Google Cloud projects. Missing the Admin API is the most common cause of a connection that authenticates but returns an empty property list.
{% endhint %}
{% endstep %}

{% step %}
**Create a service account**

Open **IAM & Admin > Service Accounts** and click **Create Service Account**. Give it a recognisable name (for example, `smaply-ga-reader`) and an optional description.
{% endstep %}

{% step %}
**Grant the service account a role**

When prompted to assign a role, choose **Viewer**. Viewer is enough for Smaply to read GA data and follows the principle of least privilege. Use **Editor** only if you have a specific reason to give the service account write access in Google Cloud.
{% endstep %}

{% step %}
**Create and download a JSON key**

On the service account's detail page, open the **Keys** tab, click **Add key > Create new key**, choose **JSON**, and download the file.

<figure><img src="/files/YLW5enxwReQuKuXnUjTK" alt="Google Cloud Console Service Accounts page with the Keys tab selected, where you create a new JSON key. The page shows an existing key row with creation and expiration dates, alongside Google&#x27;s security-warning banners about downloading service account keys."><figcaption><p>Google Cloud Console > Service Accounts > Keys</p></figcaption></figure>

Google shows a security warning when you download a key. That warning is expected, and the JSON download is the intended path here.

{% hint style="danger" %}

#### **Warning: The JSON key cannot be re-downloaded**

Save the file somewhere secure. If you lose it, you'll need to generate a new key and grant it access in Google Analytics again.
{% endhint %}
{% endstep %}

{% step %}
**Grant the service account access in each GA property**

Copy the service account's email from the same page (it ends in `@<project>.iam.gserviceaccount.com`). In Google Analytics, open **Admin > Property Access Management** for the property you want to connect, add the email, and assign the **Viewer** role.

<figure><img src="/files/f69MCTvaw1C2lqZpwIeY" alt="Google Analytics Property access management showing a service-account email added with the Viewer role, alongside the + button to add access permissions to new users."><figcaption><p>Admin > Property Access Management, service account added as Viewer</p></figcaption></figure>

Repeat for every GA4 property you want available in Smaply. The service account can read a property only after its email is granted access there, so skipping a property leaves it out of the list.

{% hint style="warning" %}

#### **Important: The service account starts with zero visibility into your data**

Granting the project-level Viewer role in step 4 does not give the service account access to any Analytics property. Until you add its email here, the property list in Smaply comes back empty. This is the step users most often miss.
{% endhint %}
{% endstep %}

{% step %}
**Upload the key in Smaply**

Back on the **Configure Google Analytics** page in Smaply, with **Service account** selected, click **Upload File** under **Service account file** and select the JSON key you downloaded.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="OAuth" %}
OAuth signs Smaply in as you. The connection inherits whatever GA properties your Google account already has access to, and tokens are tied to your individual permissions in Google.

{% stepper %}
{% step %}
**Choose Login with your Google account (oAuth)**

On the **Configure Google Analytics** page, select **Login with your Google account (oAuth)**. The right pane changes to **Configure oAuth** with a **Connect Google Analytics** heading and button.

<figure><img src="/files/gHFkSELwDYQI2iKZyTwF" alt="Configure Google Analytics page with Login with your Google account (oAuth) selected. The right pane shows Configure oAuth with a Connect Google Analytics heading, the helper text Grant permission for Smaply to access your Google Analytics account, and a Connect Google Analytics button."><figcaption><p>Configure Google Analytics, OAuth selected</p></figcaption></figure>

Click **Connect Google Analytics**. Smaply redirects you to Google.
{% endstep %}

{% step %}
**Sign in and grant access in Google**

Pick the Google account that has access to the GA properties you want to use, then review the permissions on Google's consent screen and click **Allow**. Smaply only needs read-only access to your Google Analytics data (the `https://www.googleapis.com/auth/analytics.readonly` scope).
{% endstep %}

{% step %}
**Verify the connection**

Google sends you back to Smaply. The **Configure Google Analytics** page shows the connected state, with the date the connection was added and a **Disconnect account** option, alongside the properties your account can read.

{% hint style="warning" %}
Smaply refreshes OAuth tokens automatically, so you don't need to sign in again under normal use. If you sign out of Google, revoke Smaply's access in your Google account, or lose access to a GA property, the connection drops and metrics that depend on it stop pulling data. Click **Connect Google Analytics** again from the same page to restore it. For team-wide use, switch to a service account so the connection isn't tied to one person's login.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

***

#### Configure Google Analytics in Smaply

Once the connection is established, the **Configure Google Analytics** page lists the GA properties it can read under **Select properties & apps**. For each property you pick which dimensions and metrics to expose, which shapes the choices Editors see when they build a metric.

<figure><img src="/files/q6QxVgPHakMGmH6CYG8T" alt="Connected Configure Google Analytics page. The Select properties &#x26; apps section lists a connected property with a green check, a Configure button, and a delete icon, plus an Add property link below it."><figcaption><p>Configure Google Analytics, connected</p></figcaption></figure>

{% stepper %}
{% step %}
**Add the properties you want**

Each connected property appears with a green check. Click **Add property** to include another property the connection can read. You can come back and add more at any time.
{% endstep %}

{% step %}
**Pick the dimensions to expose**

Click **Configure** next to a property to open the **Configure Google Analytics property** dialog, then open the **Dimensions** tab. Tick the dimensions Editors should be able to group data by (for example, **Country**, **Device model**, **Page title**). Use the search box or category filters to find them. Selected dimensions collect in the **Selected** panel on the right.

<figure><img src="/files/GDf8CrQZf56WELB9vqwd" alt="Configure Google Analytics property dialog on the Dimensions tab. A searchable, category-filtered list of GA dimensions sits on the left, each with a checkbox and description, and a Selected panel on the right lists the chosen dimensions such as Country, Device model, and Page title."><figcaption><p>Configure Google Analytics property, Dimensions tab</p></figcaption></figure>

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

#### **Tip: Keep it lean**

Only enable the dimensions and metrics you actually plan to use. A focused list is easier for Editors to scan when they build a metric.
{% endhint %}
{% endstep %}

{% step %}
**Pick the metrics to expose**

Switch to the **Metrics** tab and tick the metrics to make available (for example, **Active users**, **Sessions**, **Bounce rate**, **Total revenue**). Editors can then build metrics from any combination of the dimensions and metrics you enable here.

<figure><img src="/files/53NBVyEAP38gXRk4NAtT" alt="Configure Google Analytics property dialog on the Metrics tab. A searchable, category-filtered list of GA metrics sits on the left, and the Selected panel on the right lists chosen metrics such as Active users, Bounce rate, Sessions, and Total revenue."><figcaption><p>Configure Google Analytics property, Metrics tab</p></figcaption></figure>
{% endstep %}

{% step %}
**Apply your selections**

Click **Close** at the bottom of the dialog. Smaply applies your selections immediately, so any new metric using this property sees the dimensions and metrics you enabled. Repeat for each property you want to make available.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Open the **Configure Google Analytics** page. If your GA properties appear under **Select properties & apps**, the connection is working. If the list is empty or any check fails, see Troubleshooting below.

***

#### Use Google Analytics in a metric

With the connection verified, anyone in your account with an Editor role can add Google Analytics data to a metric card on any journey map. See [How to use Google Analytics in a metric](/integrations/metrics-tools/google-analytics/how-to-use-google-analytics-in-a-metric.md) for the field mapping, and [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric.md) for the full metric flow, including types, charts, and filters.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FySp6MfGck4NB6DeEF2IR%2FConfiguring%20GA%20dimensions%20(2).mp4?alt=media&token=ccce7369-1266-4963-8f4b-65633b55475d>" %}

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

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

If a journey is structured around device type, group by **Device**. If it's regional, group by **Country**. Picking the dimension that matches how the journey is read makes the metric card immediately legible.
{% endhint %}

Google Analytics metrics refresh on an hourly cycle, in line with all Smaply metric integrations. There's no continuous or streaming pull.

***

#### Troubleshooting

The Integrations tab in Account Settings shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Failed or Connection Error banner</strong> - Connection issue</summary>

A red banner on the **Configure Google Analytics** page means Smaply cannot reach GA with the stored credentials.

* For service account: confirm the **Google Analytics Data API** and **Google Analytics Admin API** are both enabled in the Google Cloud project. Check that the service account email is still listed under **Property Access Management** in GA with at least Viewer access.
* For OAuth: click **Connect Google Analytics** again from the Configure page. The token may have expired or been revoked.

</details>

<details>

<summary><strong>The Select properties list is empty</strong> - Properties issue</summary>

The connection succeeds but no properties appear.

* For service account: the service account email hasn't been added to any GA property, or the **Google Analytics Admin API** isn't enabled. Open each GA property's **Admin > Property Access Management**, add the service account email with Viewer access, and confirm the Admin API is on.
* For OAuth: the Google account you signed in with doesn't have access to any GA4 property. Sign in with an account that does, or have the GA owner grant access first.

</details>

<details>

<summary><strong>Smaply finds properties but can't read data</strong> - Permissions issue</summary>

* Check the role granted to the service account or user in **Property Access Management**. Viewer is the minimum. (Older Google Analytics phrases this permission as "Read & Analyze".)
* Confirm the connection points at the GA4 property you expect. Smaply reads through the GA4 Data API.

</details>

<details>

<summary><strong>Can't create a JSON key in Google Cloud</strong> - Org policy issue</summary>

The **Add key** option is disabled, or key creation fails outright.

* Some Google Cloud organisations block service-account key creation through an org policy. Work with your Google Cloud admin to allow key creation for the project, or use the OAuth method instead.

</details>

<details>

<summary><strong>Token expired and metrics stopped pulling</strong> - OAuth issue</summary>

Metrics that worked previously have stopped pulling data and the OAuth connection shows an error.

* Open the **Configure Google Analytics** page and click **Connect Google Analytics** to refresh the token.
* If you regularly hit token expiry, consider switching to a service account. Switching disconnects the current connection, so existing metrics stop pulling until you reconnect.

</details>

<details>

<summary><strong>A metric returns no data or unexpected values</strong> - Data issue</summary>

* Verify the **Date range** in the metric covers a window where the GA property actually has data.
* Check **Include filters** and **Exclude filters** for conditions that may be filtering everything out.
* Confirm the dimension and metric combination is supported in GA itself. Some GA dimensions can't be combined with some metrics; if GA's own Explore view returns nothing, Smaply will too.

</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>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><tr><td><strong>Use Google Analytics in a metric</strong></td><td>Add Google Analytics data to a metric card, including properties, dimensions, and metrics.</td><td><a href="/pages/pE9TkrsSoEgjD48nZSQ3">/pages/pE9TkrsSoEgjD48nZSQ3</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>Adding metric cards to a journey map and customising their display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</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-set-up-the-google-analytics-integration.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.