Google Analytics 4 extension

Once you have installed the analytics integration framework, you must connect to your data supplier. This page describes how to connect to a Google Analytics 4 (GA4) data supplier.

You must have an appropriate account and credentials to connect to GA4.

Licensing

The associated framework is included with your DX Core license and is free of charge. However, this extension is paid and requires an additional special license.

GA4 account prerequisites

To use GA4 as a data supplier, you need to create a GA4 property and generate a .json format API key.

Create a GA4 property

First, create a GA4 property in your Google Analytics dashboard. You can use GA4 Property Setup Assistant for this.

Generate a GA4 API key

You must generate Google Analytics data API key for authentication.

Go to Quickstart, and click Enable the Google Analytics Data API v1. This will generate a .json file with client configuration. Save the file as credentials.json.

Download and store this private key file carefully; you need it to authenticate Magnolia with Google. Also note the email that’s created in these instructions; you use it in step 4 to give this account access to GA4.

In your organization’s Google Cloud Console, go to APIs and Services.
In the Credentials section, register the new API key.

Go to Property access management and add the client_email from the credentials.json file to it.

Example:

{
  "type": "service_account",
  "project_id": "fakeAnalyticsTestProject-234412",
  "private_key_id": "randomId",
  "private_key": "randomKey",
  "client_email": "abc@email.com",
  "client_id": "randomId",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/"
}

An example of configuration with an email

The client email is linking GA4 to collect data.

Back in the Analytics dashboard, go to Account Settings and select Property Access Management. Add the client_email to the list. Once the email has been added, the API key you generated in step 1 can be used.
Switch to Magnolia, and go to the Resource Files app. In the action bar, click on Upload file and upload the credentials.json. Type “Google” in the Name search to make sure the newly generated json file and the supplier yaml files are both there.
Select the json key file from the list and copy the path that appears in the bottom-left corner.
Now, open the google4supplier file and paste the path under serviceAccountJsonPath.
In the same supplier file, modify the propertyId which can be found in your GA account, and click on Save changes.

Connecting GA4 as your data supplier

Data suppliers are defined under: /<module name>/dataSuppliers/<dataSupplierRegistryFile.yaml>.

/google-analytics-4/dataSuppliers/google4Supplier.yaml

class: info.magnolia.analytics.google4.datasource.GoogleAnalytics4DataSupplier
credentials:
  applicationName: Magnolia Analytics 4
  serviceAccountJsonPath: <YOUR-JSON-PRIVATE-KEY-PATH> (1)
parameters:
  propertyId: <YOUR-PROPERTY-ID> (2)
  startDate: 28daysAgo
  endDate: today
  dimensionName: audienceName
  metricExpression: activeUsers

1	Replace by the path to the `json` file with your private key (this can be found in the bottom-left corner when searching for `key.json` and then highlighting it).
2	Replace with your `propertyId` than can be found in your GA4 account dashboard.

Table 1. Properties
Property	Description
`class`	info.magnolia.analytics.google.datasource.GoogleDataSupplier
`credentials`	required
`applicationName`	required Name of the application requesting the data from the Google Analytics reporting service. For example: Magnolia Analytics
`serviceAccountJsonPath`	required Path to JSON file with service account credentials for your Google Analytics Service Account. For example: `/analytics-google-connector/analytics/google/private_key.json`.
`parameters`	required The parameters used in the REST call to configure the JSON results retrieved. These parameters vary depending on the data supplier used. Each parameter is a key-value pair. For Google Analytics, at least the `viewId` parameter is required: Sign in to your Google Analytics account Click Admin. In the `VIEW` column, click View Settings. The View ID is under Basic Settings. See the Google Analytics API documentation to find valid parameters for Google Analytics.
`filteringSubSetExpression`	optional Use to configure segment filtering.
`filtersExpression`	optional Expression to filter a segment. For example: `ga:pagePath=~%s*`

GA4 Metrics, dimensions and dates

GA4 in Magnolia are metrics, dimensions, and dates.
These can be modified in the same supplier file we've worked on in the steps above.

Metrics

In GA4, metrics and dimensions don’t contain the ga prefix as seen in previous versions. Read more about metrics and dimensions in the Google documentation.

Example of user dimensions

audienceId

The numeric identifier of an Audience. Users are reported in the audiences to which they belonged during the report’s date range. Current user behavior doesn’t affect historical audience membership in reports.

audienceName

The given name of an Audience. Users are reported in the audiences to which they belonged during the report’s date range. Current user behavior doesn’t affect historical audience membership in reports.

newVsReturning

New users have 0 previous sessions, and returning users have 1 or more previous sessions. This dimension returns two values: 'new' or 'returning'.

signedInWithUserId

The string 'yes' if the user signed in with the User-ID feature. To learn more about User-ID, see User-ID for cross-platform analysis.

Example of user metrics

active1DayUsers

The number of distinct active users on your site or app within a 1 day period. The 1 day period includes the last day in the report’s date range. Note: this is the same as Active Users.

active28DayUsers

The number of distinct active users on your site or app within a 28 day period. The 28 day period includes the last day in the report’s date range.

active7DayUsers

The number of distinct active users on your site or app within a 7 day period. The 7 day period includes the last day in the report’s date range.

activeUsers

The number of distinct users who visited your site or app.

activeUsers

The number of distinct users who visited your site or app.

The way you write the date slightly differs from the previous version (for example, before with UA = 7DaysAgo, now with GA4= 7daysAgo.) Read more about dates over here.

Example of dates

startDate

The inclusive start date for the query in the format YYYY-MM-DD. Can’t be after endDate. The format NdaysAgo, yesterday, or today is also accepted, and in that case, the date is inferred based on the property’s reporting time zone.

endDate

The inclusive end date for the query in the format YYYY-MM-DD. Can’t be before startDate. The format NdaysAgo, yesterday, or today is also accepted, and in that case, the date is inferred based on the property’s reporting time zone.

name

Assigns a name to this date range. The dimension dateRange is valued to this name in a report response. If set, can’t begin with date_range_ or RESERVED_. If not set, date ranges are named by their zero based index in the request: date_range_0, date_range_1, etc.

Google site tags

Connected site tags work with an additional gtag(config, G-XXXXX) call (without any parameters), which downloads a Google Analytics 4 tag container and sends an automatic page_view` event to the Google Analytics 4 property.

Read more about connected site tags in Set up Analytics.