Google Analytics 4

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.

Once installed, the Google Analytics 4 app uses a Google Cloud service account to load analytics data into Contentful, giving your team access to GA4 insights from the entry editor sidebar. The sidebar shows page-based analytics for published entries, including total or unique views, selectable date ranges, the resolved page path, and a link back to Google Analytics when the entry maps to a single page path.

The app can match Contentful entries to GA4 page paths according to the following options:

• For standard sites, select a content type, a slug field, and an optional URL prefix.

• For complex URL structures, use advanced matching to build custom path patterns from entry fields, locales, wildcard path segments, or query strings.
  

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 whose entries map to pages on your website:

  • For standard configuration - the content type must include a short text or short text list field that stores the page slug.

  • For advanced matching - the app can build page paths from short text, short text list, and integer fields.

NOTE: If you do not have access to Google Cloud or the ability to generate the required credentials, please contact your technical administrator to obtain them.

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.

All these checks must be green for the app to work. They ensure that:

1. Your configuration has a valid service account

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

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

4. 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

After selecting a GA4 property, configure the content types whose entries should show analytics in the sidebar. Each configuration rule tells the app how to resolve a Contentful entry to the page path stored in Google Analytics.

As an option, you can add more than one rule. This is useful when:

• Multiple content types represent pages on your site.

• The same content type can appear at multiple URL paths.

• A page URL is built from multiple entry fields.

• Your GA4 page path includes query parameters or localized path segments.

You can map content types according to one of the following options:

• Standard matching - Select this option when each entry maps to a single page path composed of an optional URL prefix and a single slug field.

• Advanced matching - Select this option when a page path cannot be represented by a single prefix and a single slug field.

Standard matching

To configure standard matching:

1. Select the content type.

2. Select the slug field. The field list includes Short text and Short text list fields.

3. Enter a URL prefix if the page path includes a fixed segment before the slug.

4. Optional: Enable Append a trailing slash to all page paths if your production URLs and GA4 page paths use trailing slashes.

Example:

NOTE: If you select a short text list field as the slug field, the app joins the list values with forward slashes.

Advanced matching

To configure advanced matching:

1. Select the content type.

2. Select the Advanced checkbox.

3. Select the entry fields to insert into the path pattern. Supported field types include: Short text, Short text list, and Integer.

4. Enter or edit the Pattern field. Selected fields are inserted as substitution tags, such as {sectionSlug} or {articleId}.

5. Choose whether the app should match against Page path or Page path + query string.

6. Save the app configuration.

Use * when part of the URL can vary. For example: /shop/products/{product_id}/compare/*

Use Page path + query string when GA4 should match the path and its query parameters. For example: /search/?category={category}

Use Insert locale into Pattern when the locale is part of the page path. The app adds {locale} to the pattern, and editors can choose the locale from the sidebar when viewing analytics.

Examples:

NOTES:

Every selected field must appear in the Pattern field as a substitution tag.

Pattern substitution tags must refer to selected fields or the locale token. Literal brace segments are not supported.

Use * for wildcard path matching. Do not write regular expression syntax in the Pattern field.

Duplicate rules are not allowed. If two rules have the same content type and same matching configuration, remove one or change one of the values before saving.

Step 5: Using the App

Once installed, configured, and added to the sidebar, the app shows analytics for published entries that match your configured rules.

In the entry sidebar, the Google Analytics 4 widget can show:

• Total views or Unique views.

• Data from the last 24 hours, last 7 days, last 28 days, last 90 days, last 12 months, or a custom date range.

• A chart showing the selected metric over time.

• A locale selector, when the configured path pattern includes {locale}.

• The resolved page path for the entry.

• A list of included page paths when multiple rules apply to the same entry.

• A link to open the matching page path in Google Analytics when the entry maps to a single page path.

Analytics data refreshes when the sidebar loads and when you change the metric, date range, or locale.

NOTE: If multiple rules apply to the same entry, the app aggregates the analytics data across those rules and lists the included paths in the sidebar. In this case, the Open in Google Analytics link is not shown because there is no single page path to open.

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 the one on your production site.

If you are using advanced matching, confirm that the Pattern field resolves to the same page path stored in Google Analytics. Check the selected match type: use Page path for URLs without query parameters and Page path + query string when the query string is part of the GA4 page path. If the pattern includes {locale}, confirm that the sidebar is using the same locale segment as your production URL. GA4 reports can also lag behind real-time traffic, so newly visited test URLs may not appear immediately.

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.

How do I configure entries whose URLs include query parameters?

Enable Advanced for the rule, enter a pattern that includes the query string, and set Match against to Page path + query string. For example, /search/?category={category} can match a search page whose category comes from a Contentful field.

How do I configure localized page paths?

If the locale is part of the URL, enable Advanced and select Insert locale into Pattern. This inserts {locale} into the pattern. When editors view the entry sidebar, they can choose the locale used to resolve the GA4 page path.

Can one content type match multiple page paths?

Yes. Add multiple rules for the same content type and configure each rule with a different standard prefix or advanced pattern. When more than one rule applies to an entry, the sidebar aggregates the analytics data and lists each included path.

Why can I not save an advanced pattern?

The Pattern field is required when Advanced is enabled. Each selected entry field must appear in the pattern as a substitution tag, such as {slug} or {articleId}. The pattern can only use substitution tags for selected fields and supported app tokens such as {locale}.