Google Analytics 4 (import)

1. What comes in, and what does not

Both paths read from your Google account and are switched on separately. They answer different questions, and you do not need both.

Path	What it fetches	What for
Data API	Daily totals: sessions, users, page views, engaged sessions	The coverage question. GA4 counts 3,000 sessions, MousePlayer recorded 40 - without the reference figure the difference cannot even be noticed.
BigQuery import	Individual GA4 sessions with their events	What happened during a visit MousePlayer could not record.

An imported session cannot be replayed. GA4 keeps no snapshot of the page and no mouse movement, so there is nothing a replay could be built from. What you get are figures and events beside your recordings - no more than that, and we do not present it as more.

The import lives in its own tables and is never mixed into your recordings. Otherwise the meaning of every derived figure would change silently - the behaviour profiles, the visitor valuation, the friction analysis - and afterwards nobody could say which row was measured and which was fetched.

2. Path 1: Data API

You need two things: the property ID and a service account key.

The property ID is not the measurement ID

This is the most common failed attempt, and Google's own error message does not name it. The measurement ID looks like G-ABC123XYZ, sits in your tracking snippet and is visible everywhere. The property ID is purely numeric and appears only in the admin area, under Admin, Property settings. The second one is what is needed; we reject the first with a note rather than let you run into a 400.

Creating and authorising the service account

In the Google Cloud Console, create a service account and generate a JSON key.
In the same project, enable the Google Analytics Data API.
In GA4 under Admin, Property access management, add the service account's e-mail address as a Viewer. A service account is a user of its own; without this step Google answers 403, and without saying why.

Paste the contents of the JSON file into the field. It is stored encrypted and shown only in shortened form afterwards.

3. Path 2: BigQuery import

This path reads the GA4 raw export. You have to set that up once in GA4: Admin, BigQuery links. Tables only appear from the following day - before that the import finds nothing, and that is not a fault.

What you enter

The GCP project ID the export lives in. That is not necessarily the same project you export MousePlayer data into.
The dataset ID. GA4 names it analytics_<propertyId>.
A service account key with BigQuery Data Viewer on the dataset and BigQuery Job User in the project. Read access is enough; please do not grant more.

What it costs, and who pays

BigQuery bills by bytes read, and that bill is yours. This is why the import reads only a few days per run and only ever runs a single query - a second one would read the same tables again. On top of that a hard cap aborts the query before it gets expensive; when that happens, the message in the delivery log says the time window is too large.

The cadence

Every six hours by default, and each run re-fetches the last three days. That is not arbitrary: GA4 backfills for up to 48 hours, and the daily export only appears the day after. Asking more often does not get you fresher numbers, just the same ones.

4. The key that links both sides

If you also set the analytics bridge to GA4, MousePlayer records the client ID from the _ga cookie with every session. That is exactly the value the BigQuery export carries as user_pseudo_id.

With it, a GA4 session can be matched to one of your recordings - and the other way round, you can see what GA4 counted during the same visit. Without the bridge both sides simply sit next to each other, unconnected.

The same field also carries your own customer identifier if you use setUserId(). You cannot have both: either the Google client ID sits there, or your own number.

5. Consent, retention, deletion

What comes in had a cookie

Only rows carrying a user_pseudo_id are imported. Where a visitor declines, GA4 sends cookieless hits under Consent Mode, and those carry none - so they drop out without anyone having to give an assurance. Modelled, that is estimated, rows stay out for the same reason: storing an estimate as a session would mean storing visits that never happened.

How long it stays

180 days by default, counted from the day the row describes - not from the moment of import. Otherwise the period would never expire, because every run fetches the same days again.

Deleting

If a visitor asks for their data to be erased, their imported GA4 sessions go with it - as far as they can be attributed through the identifier above. If you delete the project, they go in any case, including rows that never belonged to one of your recordings. The daily retention run deliberately leaves them alone: GA4 data runs on its own clock, and your recordings expire earlier.

6. When nothing arrives

Every run writes its result to the delivery log on the integrations page - failures included, in plain words. That usually already says what is missing.

Message	What to do
Property ID must be purely numeric	You entered the measurement ID. The right number is in GA4 under Property settings.
HTTP 403 from the Data API	The service account is not a Viewer on the GA4 property, or the Data API is not enabled in the GCP project.
Dataset or export tables not found	The BigQuery link is missing, the dataset is named differently, or a day has not passed yet.
Access denied (BigQuery)	The service account lacks BigQuery Data Viewer on the dataset or BigQuery Job User in the project.
The query would have read too much	The cost cap aborted it before anything was billed. Choose a smaller time window.
no sessions in the window	Not a fault. There was no consented session in the days fetched.

How can we help?