How to set up the Google Analytics integration
Connect Google Analytics so your web traffic data flows into journey map metric cards.
An Admin connects Google Analytics once at the account level. After that, anyone in the workspace can build metrics from your GA properties.
In this guide
Set up the Google Analytics integration
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)
In Smaply, go to Account Settings > Integrations and click Set up next to Google Analytics.
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).
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.
Plan availability
Service account auth is available on the Governance plan only. OAuth auth (the other tab) is available on all plans.
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.
Create a Google Cloud project
In the Google Cloud Console, create a new project for the integration. We recommend naming it Smaply-GA so the purpose is obvious if you audit projects later.
A dedicated project keeps API access organised so you can see at a glance which credentials belong to Smaply.
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.
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.
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.
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.
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.
Google shows a security warning when you download a key. That warning is expected, and the JSON download is the intended path here.
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.
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.
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.
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.
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.
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.
Click Connect Google Analytics. Smaply redirects you to Google.
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).
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.
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.
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.
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.
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.
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.
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.
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 for the field mapping, and How to create and configure a metric for the full metric flow, including types, charts, and filters.
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.
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.
Connection Failed or Connection Error banner - Connection issue
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.
The Select properties list is empty - Properties issue
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.
Smaply finds properties but can't read data - Permissions issue
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.
Can't create a JSON key in Google Cloud - Org policy issue
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.
Token expired and metrics stopped pulling - OAuth issue
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.
A metric returns no data or unexpected values - Data issue
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.
For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see How to manage integrations.
Still not working? Contact support at help@smaply.com
Related topics
Last updated