Set up a Service Account for Google Analytics 4 Integration

The guide below will walk you through the steps to create a "service account" in Google, for use with Contentful's Google Analytics 4 app.

The process is somewhat technical and requires certain access rights and permissions within your organization's Google account. If you run into difficulties you may need to enlist the help of your IT department.

Overview

How Contentful uses Google's "service accounts"

Service accounts are non-human users of a system that can communicate with other systems and services.

For the Google Analytics 4 app, Contentful makes use of a service account (that you configure) to fetch page-based analytics data from Google Analytics and display it alongside content entries throughout your space. This allows all users of your space to view relevant page analytics in the context of content entries, without needing to log in to Google Analytics individually.

For more information on service accounts in Google and how they work, see the official documentation.

Who this guide is for

This guide might be right for you if you are: 

• A Contentful space admin who is installing the Google Analytics 4 app and has moderate technical skills

• An IT administrator supporting your organization in installing Google Analytics 4

This guide does not serve as: 

• A deep dive into Google-specific concepts

• A debugging tool for any unrelated Google Analytics errors

Setup

Follow the steps below to create and configure a service account for use with Contentful's Google Analytics 4 app.

Step 1: Install the Google Analytics 4 app in a Contentful space

If you're reading this guide, you've likely already started the process of installing the Google Analytics 4 app. If not, you should install it now.

After authorizing the app to access your space, you should see a screen that looks like this:

Step 2: Create or select a Google Cloud Platform project

In order to use Google Analytics with Contentful, you’ll need to create a new project in Google Cloud Platform. If you already have an existing Google Cloud project you wish to use, feel free to skip this step.

1. Go to the Google Cloud Platform Manager.

2. Click + CREATE PROJECT at the top of the page.

3. Choose any project name that makes sense for your organization. We recommend something simple like "{Space Name} Analytics" or "Analytics for Contentful."

Step 3: Create a service account within your Google Cloud Platform project

Next, you'll create a new service account within the project you created in Step 2, which Contentful will use to access analytics data from your organization's Google Analytics account.

1. Navigate to IAM & Admin > Service Accounts. Be sure to choose the project you created in Step 1 above if it's not selected already.

2. Click the + CREATE SERVICE ACCOUNT button.

3. Choose a name for the service account that makes sense for your organization. We recommend something simple like "{Space Name} Analytics Account" or "My Analytics Account." Optionally, provide a description.

4. Click "DONE" to create the Service Account.

Note: By default only you will be able to administer the service account you create here. You can optionally grant other users in your organization access to this service account in the "Grant users access to this service account" section of the form.

Step 4: Create a private key for your service account

1. Navigate to IAM & Admin > Service Accounts. Be sure to select the project you created in Step 2 above if it's not selected already.

2. Click the link (under the "Email" column) to the Service Account you created in Step 3.

3. Click the "KEYS" tab at the top of the screen.

4. Click the "ADD KEY" dropdown and choose "Create new key."

5. Choose the "JSON" option and click "CREATE."

6. A file containing the new Service Account Key (with a name like test-name-010194laedy.json) will be downloaded to your computer automatically.

Step 5: Add the service account private key to Contentful

1. Navigate to the Contentful App Configuration screen for the Google Analytics 4 app from Step 1. (If you closed that tab, you can just follow the Google Analytics 4 installation process again.)

2. Open the file you downloaded from Step 4 in a text editor of your choice. (Some browsers also allow you to open JSON files directly by choosing "File > Open File...")

3. Copy the entire contents of the file.

4. Paste the contents of the file into the large text field labeled “Private Key File (required)" on the app configuration screen.

5. Click "Install" at the top right of the screen.

Enabling the API

After setting the Service Account Key, you might see an error message about needing to enable the API. In order for Contentful to receive data from your analytics account, you’ll need to follow the link in the error message to grant API access to Contentful. 

Rest assured, Contentful only uses this to list properties available in your analytics account and will not change anything in your dashboard. 

Granting your service account access to your Google Analytics 4 property In order to choose a Google Analytics 4 property for the app, you will need to explicitly grant access to the Service Account for the property you wish to use.

1. Navigate to IAM & Admin > Service Accounts. Be sure to choose the project you created in Step 1 above if it's not selected already.

2. Click the ‘Copy to Clipboard’ button by the Service Account Email.

3. Navigate to Google Analytics and click on the ‘Admin’ cog in the left sidebar.

4. Ensure that you are in the correct Account and Property, and then click on ‘Property Access Management’

5. This will open a new pane where you can view and add users to the property. Click on the blue ‘+’ button to add access permissions to new users, and select ‘Add users’

6. In this new pane, you will paste the Service Account email address you copied in the first step. Deselect ‘Notify new users by email’ and select ‘Viewer’ as the option for ‘Direct roles and data restrictions’ and click the blue ‘Add’ button.

Wrapping up

If you follow the steps in this guide successfully, you should successfully have connected your Contentful space to a Google service account.

Follow the remaining instructions on the app configuration screen in the Google Analytics 4 app to ensure your service account and project are correctly authorized to fetch analytics data from the Google Analytics property you wish to connect to.