Google Analytics

The Google add-on brings everything Google to Analytics Core: the Google tag and its browser event handler, the Measurement Protocol server route, the identifiers that route needs, and the wording of its test results. Core carries none of it. Both channels share Analytics → Settings → Google, a page the add-on registers.

Configure Google

1. Enter the browser Tag/Measurement ID. The add-on accepts G-, GT-, AW-, and DC- tag identifiers.
2. For server delivery, enter a GA4 Measurement ID beginning with G- and its Measurement Protocol API Secret.
3. If the browser tag field already contains the correct G- ID, leave the separate Measurement ID blank to reuse it. A GT-, AW-, or DC- value cannot substitute for the server Measurement ID.
4. Select Send … from the browser and Send … server-side for the events you want. Save and verify both the XPAC route and the provider's event view.

Disable Google Analytics pauses the configured Google integration. The API secret stays in WordPress settings; it is not included in public browser configuration.

For related sites using the same Google tag, enter a comma-separated list such as example.com, checkout.example.net in Cross-domain measurement domains. The Google linker can then carry the visitor's measurement context between those sites. Leave this field blank to keep your Google Admin domain settings; a list here overrides them. Configure the same related domains on each participating site and verify navigation in Google's cross-domain guide.

What this add-on adds

• The Google tag (gtag.js) in the browser, with Consent Mode defaults set before config from the shared consent state, and the googleTag event handler that sends enabled browser events through gtag('event', …).
• The googleMeasurementProtocol server route, with the transport that supplies its client_id, session_id and ga4_blocked event properties. Only this transport can set them; markup and the public capture call cannot.
• Server-side validation of those three properties, and the removal of the two identifiers when the visitor denies statistics consent.
• The reserved custom-event names secret and user_data, which would collide with its settings.
• The wording of Google's validation results on the Tools screen. Its test tool takes no input and shows no links.

Avoid duplicate events

Google's native events (page views, search, scroll, outbound clicks and downloads) are off by default in XPAC's browser and server event toggles. Enable them deliberately after reviewing what the tag or Enhanced Measurement already sends. Custom media and share events default to enabled.

Custom names must meet Google's web event naming rules. Reserved names such as session_start are omitted from Google routes while remaining available to other providers. Reserved parameter prefixes are also removed. Custom properties cannot override the configured destination, authenticated debug mode or account identity. See Google's reserved names.

The add-on's browser handler sends configured custom events through gtag('event', …). When the browser tag is ready and supplies the event, the server route skips its copy. When the tag is blocked or never becomes ready, enabled server routes can act as a fallback, subject to statistics consent, and the browser handler leaves that event to the server even if the tag loads later. This readiness signal does not prove that Google accepted the browser event.

A server event waits for the tag to hand back its client and session ID, for up to two seconds. The visitor leaving the page releases the wait, and once the deadline passes no later event on that page waits again. Clicks, downloads, shares, contact links and engagement time never wait. Other add-ons' waits run at the same time rather than adding up.

The fallback uses the Google client/session identifier when available. Otherwise the add-on keeps a generated first-party identifier and session in the browser's local storage (xpac_analytics_client_id and xpac_analytics_session) once statistics is permitted. The fallback session expires after 30 minutes of inactivity, and both values are forgotten the moment statistics consent is withdrawn or a page starts with it denied.

Consent and account matching

Configure the shared Privacy controls. Statistics permission controls event delivery. Google receives advertising consent fields derived from marketing permission.

The configured Google tag still loads while consent is denied. The add-on sets Consent Mode defaults before config from the current shared state, updates them on every consent change, and gates its own manual events and server forwarding; Google's tag may still send measurements without cookies. See Google's Consent Mode overview and integration guide.

Send hashed logged-in user data is off by default and additionally requires marketing permission when that signal is present. Identify signed-in users after consent separately sends the WordPress account ID as user_id on permitted browser and Measurement Protocol routes. Revocation clears the browser account association. Visitors' supplied event properties cannot select a different WordPress account.

Verify delivery

Visitor events, in the browser and over Measurement Protocol, never carry debug mode: event properties, data attributes and custom mappings cannot set it. Use Tools → Send test event below, then follow the DebugView guide to select the testing device and inspect arriving events.

Tools → Send test event first validates a generated event, then sends it with debug mode enabled. There is nothing to type: the tool takes no input, and wp xpac analytics test-event googlemeasurementprotocol takes no options. A successful run says that Google validated the event structure and accepted the collection request. A structure rejection names the validation code and, when Google supplies it, the field, in a note under the result. Validation does not verify credentials, and an HTTP success from the collection endpoint alone does not prove that an event appears in DebugView or reports. Confirm arrival in Google; see the Measurement Protocol validation guide.

Server calls have bounded timeouts and no durable retry. With a host that cannot release the visitor before shutdown, default delivery is nonblocking and its result cannot confirm provider acceptance.

For provider names, payload filters and the client-IP integration, see the Analytics developer guide and generated Google hooks.