Settings
Open Analytics → Settings in the CP nav (or Settings → Plugins → Google Analytics, which
redirects to the same page).
Connect Google
Under Settings → OAuth, enter the OAuth Client ID and OAuth Client Secret from a Google Cloud OAuth app (with the Google Analytics Reporting/Admin APIs enabled), then click Connect. Once authorized, the plugin can list your GA4 accounts/properties directly from Google instead of requiring you to copy IDs by hand.
Sources (GA4 properties)
Analytics → Sources is where a GA4 property gets registered as a Source: account, property, and measurement ID/API secret. Each source also carries a currency (used to format widget/report values) and, once connected via OAuth, can be picked from an account/property explorer rather than typed in manually.
Sites
Analytics → Sites maps each Craft site to one of the configured Sources. This is what lets a
multi-site install report site A against one GA4 property and site B against another; the mapping
is stored as a SiteSource record per Craft site ID.
Tracking behavior
| Setting | Effect |
|---|---|
| googleAnalyticsMeasurementId / googleAnalyticsMeasurementApiSecret | Default GA4 Measurement Protocol credentials, used when a source doesn't override them |
| autoSendPageView | Send a page_view event automatically after every non-AJAX page render |
| enabledGa4Events | Which of the available GA4 events (page view, product view, cart view, login, sign up, search, add to cart, remove from cart) are actually sent |
| sendUserId | Attach the logged-in user's ID to events as GA4's user_id property |
| createGclidCookie | Create a gclid cookie for Google Ads click-ID attribution if one doesn't already exist |
| stripQueryString | Strip the query string from the tracked page URL before sending |
| adminExclude / groupExcludes | Exclude logged-in admins, or specific user-group handles, from tracking |
| serverExcludes | Regex filters against $_SERVER keys (defaults to excluding localhost/127.0.0.1/::1) |
| filterBotUserAgents | Skip sending events for requests that look like bots |
| sendAnalyticsInDevMode | Whether events still send while Craft devMode is on |
| logExcludedAnalytics | Log (for debugging) events that were filtered out instead of sent |
Widgets and field type
| Setting | Effect |
|---|---|
| enableWidgets | Enable/disable the E-commerce, Realtime, and Analytics Report dashboard widgets |
| enableRealtime | Additionally required for the Realtime widget to be selectable (GA4 Realtime API calls cost more quota) |
| realtimeRefreshInterval | How often (seconds) the Realtime widget polls GA4 |
| enableFieldtype | Enable/disable the Analytics Report field type |
| enableCache / cacheDuration | Cache GA4 API responses (widgets, field type, reports) for the given PHP date interval |
| mapsApiKey | Google Maps API key, used by the geographic (Geo) chart |
Validate
After connecting a source and mapping sites:
- Visit Analytics → Tests (
gaanalytics/tests/*) to confirm formatting, template variables, and live GA4/GA4-metadata calls succeed. - Add an E-commerce or Realtime widget to the Dashboard and confirm it renders data for the selected source instead of a "not connected" / "no sources" placeholder.
- Browse the storefront and check the GA4 property's Realtime report (or DebugView, with a debug measurement ID) for incoming events.
See Use Cases for the end-to-end connection workflow and Developer / API for the event pipeline and CP routes.