How to set up the Google Sheets integration
Connect Google Sheets so spreadsheet data flows into journey map metric cards.
An Admin connects Google Sheets once at the account level. After that, anyone in the workspace can build metrics from your sheets.
In this guide
Set up the Google Sheets integration
Prerequisites
Admin role at the account level
A Google account with access to the spreadsheets you want to read
For service account auth: access to a Google Cloud project (you can create one as part of setup)
Available on all plans, for both authentication methods.
In Smaply, go to Account Settings > Integrations and click Set up next to Google Sheets.
The Configure Google Sheets page opens with two authentication options under Select integration type.
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.
A service account is a Google identity that connects Smaply to Google Sheets without being tied to a single person's login. You create the account in Google Cloud, share each source spreadsheet with its email address, and upload its key file in Smaply.
Keep the Configure Google Sheets page open in another tab. You'll come back to it at the end of this flow to upload the key file.
Choose Login with your Google Sheets service account
On the Configure Google Sheets page, the Login with your Google Sheets service account option is selected by default. The right pane shows the Configure service account form where you'll upload the JSON key.
Create a Google Cloud project
In the Google Cloud Console, create a new project for the integration. We recommend naming it something like Smaply-Sheets 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 Sheets API
Inside the project, open APIs & Services > Library, search for Google Sheets API, and click Enable. Smaply needs this API to read data from any sheet the service account has access to.
The Google Sheets API is not enabled by default in new Google Cloud projects. Skipping this step is the most common cause of "no spreadsheets available" later.
Create a service account
Open IAM & Admin > Service Accounts and click Create Service Account. Give it a recognisable name (for example, smaply-sheets-reader) and an optional description. You don't need to grant the service account any project-level roles, since access is granted per spreadsheet in Google Sheets itself. For full background on service accounts, see Google's Service Account documentation.
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. Note the service account's email address from the same page (it ends in @<project>.iam.gserviceaccount.com). You'll need it in the next step.
Share each source spreadsheet with the service account
In Google Sheets, open every spreadsheet you want Smaply to read. Click Share in the top-right corner of the sheet, paste the service account's email address into the people field, set the access level to Viewer, and click Send (or Share). Repeat for every spreadsheet you plan to use.
Sharing a spreadsheet with the service account works the same way as sharing it with any colleague. The service account email just looks like a long email address. If you skip this step, the spreadsheet won't appear in the picker when you build a metric.
Upload the key in Smaply
Back on the Configure Google Sheets page in Smaply, click + Upload File under Service account file and select the JSON key you downloaded.
Verify the connection
A green Success banner confirms the connection. The right pane now shows Added on and Added by (the service account email for service-account connections), plus a red Disconnect account button you can use later if you need to remove the connection.
OAuth signs Smaply in as you. The connection inherits whatever spreadsheets your Google account already has access to, and tokens are tied to your individual permissions in Google.
Choose Login with your Google Sheets account (oAuth)
On the Configure Google Sheets page, choose Login with your Google Sheets account (oAuth). The right pane shows a Connect Google Sheets section with a three-step info panel and the Connect Google Sheets button.
Click Connect Google Sheets
Click Connect Google Sheets. Smaply redirects you to Google.
Sign in with Google
Pick the Google account that has access to the spreadsheets you want to use in Smaply. If you're already signed in to multiple Google accounts, choose the one with the right spreadsheet access.
Grant Smaply read access
On Google's consent screen, review the permissions Smaply is requesting and click Allow. Smaply only needs read access to your Google Sheets data.
Verify the connection
Google sends you back to Smaply. A green Success banner confirms the connection, and the right pane now shows Added on, Added by, and a red Disconnect account button.
OAuth tokens expire periodically. If you sign out of Google, revoke Smaply's access in your Google account, or lose access to a spreadsheet, the connection drops and metrics that depend on it stop pulling data. Click Connect Google Sheets again from the same page to restore it.
Verify the setup
Reopen the Configure Google Sheets page from Account Settings > Integrations. A green Success banner and the Added on and Added by details confirm the connection is live. To check that your data is reachable, start a new Google Sheets metric and confirm a spreadsheet you shared (service account) or have access to (OAuth) appears when you click Select file.
If the connection shows an error or no spreadsheets resolve, see Troubleshooting below.
Use Google Sheets in a metric
After the integration is connected, Editors create Google Sheets metrics like any other Smaply metric. In the metric configuration modal, set Source to Google Sheet and then pick the spreadsheet, sheet, and column layout.
For Series and Comparison metrics, the Source step exposes these Google-Sheets-specific fields:
Spreadsheet - Click Select file to open Google's spreadsheet picker and pick a sheet you've shared with the connected account.
Sheet - Pick the tab inside the spreadsheet. Disabled until a spreadsheet is selected.
Make top row headers - Treats the first row as column names. Checked by default.
Data label - The column that supplies labels (for example, dates or category names).
Data values - The column that supplies numeric values.
Select bottom rows and Number of rows (max 50) - Limit the metric to the most recent rows. Smaply reads up to 50 rows per metric.
For Number metrics, the Source step is simpler: pick the spreadsheet and sheet, then enter a single cell reference (for example, A2) and optional prefix and suffix (for example, $ and %).
The Save button stays disabled until Spreadsheet, Sheet, and the data fields for your chosen type are all set.
For the full metric flow, including chart types, filters, and how the card behaves on a journey map, see How to create and configure a metric.
Tip: Match the sheet to the journey context
If a journey is structured around weekly cohorts, point the metric at a sheet whose rows are weeks. If it's structured around regions, use a sheet with one row per region. Smaply renders what's in the sheet, so the cleaner the sheet's shape matches the journey, the more legible the metric card.
Google Sheets 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 Sheets page means Smaply cannot reach Google Sheets with the stored credentials.
For service account: confirm the Google Sheets API is enabled in the Google Cloud project. Re-upload the JSON key if the file may have been corrupted or replaced.
For OAuth: click Connect Google Sheets again from the Configure page. The token may have expired or been revoked.
The spreadsheet picker is empty or my sheet isn't listed - Access issue
The connection succeeds, but Smaply doesn't show the spreadsheet you expected when you click Select file during metric setup.
For service account: the spreadsheet hasn't been shared with the service account email address. Open the spreadsheet in Google Sheets, click Share, paste the service account email, set access to Viewer, and click Send. The sheet appears in Smaply's picker once sharing is in place.
For OAuth: the Google account you signed in with doesn't have access to that spreadsheet. Make sure the sheet is shared with that account in Google Sheets, or sign in with the account that does have access.
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 Sheets page and click Connect Google Sheets to refresh the token.
If you regularly hit token expiry, consider switching to a service account. Switching disconnects the current OAuth connection, so existing metrics stop pulling until you reconnect.
Service account lost access to a sheet - Permissions issue
A metric that previously worked starts returning no data, even though the connection still looks active.
The service account was probably removed from the spreadsheet in Google Sheets. Open the sheet, click Share, confirm the service account email is still listed with Viewer access, and re-add it if missing.
If the spreadsheet itself was deleted or moved out of a shared drive, Smaply can't reach it. Move the file back or point the metric at a replacement sheet.
A metric returns no data or unexpected values - Data issue
Check the Data label and Data values columns in the metric. If headers shifted or columns were reordered in the source sheet, the metric may be reading the wrong column.
If Make top row headers is unchecked but the sheet does have a header row, that row gets read as data. Re-check the box, or remove the header from the sheet.
If Select bottom rows is enabled, confirm Number of rows (max 50) is high enough to cover the data range you expect to see.
Confirm the values in the Data values column are numeric. Cells containing text, formulas that return text, or
#REF!errors won't render as numbers.
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