Connect Google Analytics#

Reportworq connects to Google Analytics 4 (GA4) through a CData driver, which presents your Analytics account as a relational, tabular source you query with the same table or SQL modes as any database. In the connector catalog the tile is Google Analytics.

This build of the driver supports Google Analytics 4 only. It does not offer Universal Analytics.

This page covers creating the Google credentials, registering the redirect URI, and signing in. For the shared CData add-and-test flow, see Connect CData sources.

Choose how Reportworq signs in#

Set the connection's Auth Scheme to the option that fits how you want Reportworq to reach Google.

Before you begin#

• You are an administrator. Only administrators can add or configure datasource connections.
• Reportworq is reachable over HTTPS. OAuth sign-in cannot complete over plain http:// on a non-localhost address, and Reportworq stops with a message saying so.
• You have a Google Cloud project where you can create credentials, and access to the Google Analytics 4 property you want to read.
• You know the property's Property Id (see Find your Property Id).

Set up your Google OAuth client#

For the OAuth scheme you create an OAuth client in your own Google Cloud project, then give its Client ID and Client secret to Reportworq.

1. In the Google Cloud console, select your project and go to APIs & Services.

2. Enable the Google Analytics Data API and the Google Analytics Admin API for the project. The data API serves reports; the admin API serves the account and property lists.

3. Configure the OAuth consent screen if you have not already.

4. Go to Credentials > Create credentials > OAuth client ID, and choose the Web application type.

5. Under Authorized redirect URIs, add this exact address, replacing the host with your Reportworq address:

   https://<your-reportworq-host>/server/v0/oauth-redirect
   

   The redirect URI must match exactly, character for character, the address you reach Reportworq at. A mismatch is the most common cause of a failed sign-in.

6. Create the client, then copy the Client ID and Client secret. Treat the secret like a password.

The default scope Reportworq requests is read-only (analytics.readonly), so Reportworq can read your analytics data but cannot change it.

Find your Property Id#

Report queries need a Property Id. In Google Analytics, open Admin and select Property details; the Property ID is the number shown there. It is a number, not the G- measurement id.

Add the connection in Reportworq#

1. Sign in to Reportworq as an administrator and go to Settings > Integrations.
2. On the DATASOURCES tab, select Add, find Google Analytics in the catalog, and add it. The connection editor opens.
3. In the General section at the top of the editor, select Enable Integration and give the connection a Display name. This is the name your formulas refer to, so it must be unique across the instance.
4. Leave Auth Scheme at OAuth. Enter your Property Id. Select Show Advanced Options to reveal the OAuth section, then enter your OAuth Client Id and OAuth Client Secret. Make sure Initiate OAuth is set to GETANDREFRESH so Reportworq can refresh the token for you.
5. Save your changes. Selecting Authenticate with unsaved edits returns "Please save changes before performing this operation."
6. Select Authenticate. A new browser tab opens with Google's sign-in. Sign in with an account that has access to the property and approve the request. When it completes, the tab tells you that authentication is complete. Close the tab and return to Reportworq.
7. Back in the OAuth section, the read-only token fields populate. These confirm the sign-in succeeded; you do not edit them by hand.
8. Select Test connection, then Save.

To disconnect, select Sign out, which clears the stored tokens from the connection. Save any other edits first.

Google asks you to pick an account and approve access on every sign-in. This is normal. Google shows its account chooser and then its consent screen each time, and in return always issues a refresh token, including when you sign in again after Sign out. The refresh token is what keeps the connection working after the first hour. Approve the screen each time; it does not mean something is wrong.

Use a service account#

A service account lets Reportworq connect without any person signing in, which suits scheduled jobs.

1. In the Google Cloud console, create a service account and a key for it, and download the key.
2. In Google Analytics, open Admin and Property access management, and add the service account's email address with Viewer access.
3. In Reportworq, set Auth Scheme to OAuthJWT and fill in the service account properties the editor shows, as described in CData's Google Analytics documentation.
4. Enter the Property Id, then select Test connection and Save. No Authenticate step is needed for a service account.

Query your analytics data#

Once the connection tests, a model author builds views over it on each view's Design tab, starting from a table or writing SQL, exactly as for the other CData and relational sources. See Build a view with the designer and Data models.

The connection offers two kinds of tables and views:

• Report views answer analytics questions, grouped by theme: Acquisitions, Engagement, Tech, Demographics, Monetization, and a set of prebuilt Report views.
• Admin views describe your Analytics setup itself, such as Accounts, Properties, and DataStreams.

Report views are always read against a Property Id. CData's own reference lists every view and its columns: Google Analytics ADO.NET provider docs.

Behavior and limits#

• Google Analytics 4 only. Universal Analytics is not offered by this driver build.
• Read-only. The connection reads analytics data; it does not write back to Google Analytics.
• Tokens are stored encrypted on the connection and refreshed automatically at run time. If the connection later stops authenticating, run Authenticate again.
• Reportworq must be reached over HTTPS for the OAuth sign-in to complete.
• Linux servers: the driver talks to several Google hosts, and Google rotates its server certificates, so Reportworq does not pin a certificate for this connector. If Test connection on a Linux server reports that server certificate verification failed, contact support and quote the message.
• Only administrators can add or configure the connection, and editing, disabling, or deleting a live datasource breaks every job and form that refreshes from it.

Troubleshooting#

Related#

• Connect CData sources for the shared CData add-and-test flow.
• Connect QuickBooks Online, which uses the same server-side OAuth sign-in.
• Connector catalog for every connector Reportworq ships.
• Connect a data source for the general add, test, and manage flow.
• Data models for turning the connection into curated, reusable data for report authors.