Google Analytics 4 App Guide

The Google Analytics 4 app allows you to see content performance metrics from Google Analytics in the sidebar of your entries. You can also link directly to pages in Google Analytics to view deeper performance insights.

Overview

Once installed, the Google Analytics 4 app allows you to use a service account in Google Cloud to load analytics data, giving your entire team access to analytics in Contentful. The app is installed on the sidebar, and shows page view data, the option to look at data over different time periods, and a link back to Google Analytics.

Requirements

To use this app, you will need:

• Administrator access to the Google Cloud Platform to configure a service account

• A previously configured instance of Google Analytics 4

• A content type with a slug field

If you do not have access to Google Cloud or the ability to generate the needed credentials, please contact your technical administrator to generate the credentials.

Usage

Step 1: Configuring a Google Cloud Service Account

Please refer to these instructions (or share them with an administrator) to generate the service account needed to make the app work.

In general, the Google Analytics 4 app needs to be configured with a service account in Google Cloud to get access to your analytics data. This method ensures that all of your team has access to analytics data, and does not need to sign in or have their access and permissions updated to see data.

Configuring a service account requires administrator access to Google Cloud. The process can be tricky - please contact support if you run into issues!

Step 2: Installing the App

The app can be installed either through the Contentful Marketplace or within your Contentful space. On the first step of the app installation process, you will need to paste the service account credentials on the appropriate field in the app configuration screen and click "Save" to install the app in the initial state.

After your credentials are installed, the app configuration screen will walk you through some additional steps needed to "enable" the app's access to required APIs in Google Analytics. You will also need to invite your newly created service account to the Google Analytics property you wish to associate your Contentful environment with (see Step 3 below).

We automatically check permissions and access to ensure that the app has access to the data and APIs it needs to function. You can see these checks when saving the app or by clicking “Show status checks” next to the status.

These checks must all be green for the app to work. They ensure that:

1. Your configuration has a valid service account

2. That the Admin API is activated for your account (this change is read only and is safe to enable in Google Cloud)

3. That the Data API is activated for your account (this change is read only and is safe to enable in Google Cloud)

4. That the service account has access to valid Google Analytics 4 Account Properties.

If any of these checks fail, you can click the Details button to either learn how to resolve the error or enable the required service(s).

Step 3: Choosing a Google Analytics property

Once your credentials are installed and working, you will be able to select the Account and Property that you want to map to Contentful.

The available list will show all the analytics properties that exist in any analytics accounts your service account is connected to. Importantly, you will need to ensure your service account is explicitly added as a "Viewer" in the Property Access Management section of your Google Analytics 4 admin page. If you need help with this step, please reference the last step in this guide: Set up a Service Account

Generally, you want to select the Account that maps to the content that you manage in the selected Contentful space. For example, if you have a space for your knowledge base and a Google Analytics 4 account for that knowledge base, you will want to select that property in the dropdown:

Step 4: Mapping content types to Google Analytics data

Next, select the content type(s) that represent "pages" on your website. In general this will mean a specific content entry will map one to one with a "page path" in Google Analytics. You can map as many content types as you want, but each must provide a slug field that identifies content entries uniquely in the URL of the page on your website as well as provide any prefixes that sit in front of the content’s URL.

By way of example, let's say you host a blog that has blog posts hosted on Contentful using a "Blog Post" content type. You have a `pageSlug` field that uniquely identifies the URL slug for each Blog Post. If you had a blog post called "My Favorite Apple Pie Recipe," it might have a `pageSlug` field value of `my-favorite-apple-pie-recipe`. When you publish the page on your blog, it will live at a URL that looks like "http://www.mycoolrecipes.com/blog/my-favorite-apple-pie."

Using this example, to connect your blog post entries to the correct page path in Google Analytics, you'd select the`‘Blog Post` Content Type, the `pageSlug` Slug field, and a prefix of `/blog/`.

The fields appearing in the Slug field selection are Short Text and Short Text (List) fields. If you select a Short Text (List) field, the elements of the array will be joined using forward slashes. You can also select the checkbox to append a trailing slash to every URL, if needed.

Once configured, hit Save to apply the settings. The Google Analytics 4 app is automatically added as the second sidebar item on the content type you selected.

Step 5: Using the App

Once installed, configured, and added to the sidebar, you can start to view analytics data! To see the app in action, navigate to a published entry with the content type you selected above. 

Within the entry, you will now see a sidebar widget for Google Analytics 4. This widget will show core analytics data about that entry, including:

• Total page or screen views, non-unique

• The option to select from data captured in the last 24 hours, 7 days, or 28 days

• A chart showing the page views by day for your selected timeslice

• The page path that the entry is linked to, matching the production URL of your content

• A link to the specific screen in Google Analytics that matches the page slug, allowing easy access to more insights

Analytics data is refreshed each time that you load the page.

FAQ and Troubleshooting

I can’t find an Account that I expect in the list

If you do not see an Account that should populate on the list during configuration, you may have a misconfigured service account. Ensure that the service account you configured has access to all needed Accounts, so that data can be pulled for any projects.

I receive an error about content types

There are two common cases when the app shows an error due to content type configuration:

1. Content type not configured. This occurs when a content type is not selected during app configuration, but the app is installed on a sidebar. You can resolve this error by following step 2 in this guide completely.

2. Short text slug field not configured. If you have not configured a valid short text slug field, the app cannot map your Contentful entries to Google Analytics. Ensure that a slug field is created and mapped to use the app.

The app shows no data even though I know I have analytics data for a page

This is likely due to a misconfigured slug mapping. Ensure that you have captured any prefixes for your pages and that the slug you configure in Contentful matches with your production site.

When I click on the ‘Open in Google Analytics’ link in the sidebar, I see a ‘missing permissions’ error in Google Analytics

The app can be configured with any GA4 properties that are shared with the Google Service Account and then that data can be viewed in the sidebar. However, in order for a particular user to see additional data in Google Analytics, the user must have permission to see that property.