GA4 Integration

GA4

Configure GA4 server-side forwarding from Selwise event stream with mapping and filter controls.

Audience: Analytics engineers and marketing teams using GA4 as primary measurement platform.

Critical: GA4 provider key is ga4 and is configured through PUT /api/v1/sites/:siteId/integrations/ga4.

Integrations Overview Event Mapping Operations

Who This Page Is For

Use this page when you need to forward Selwise events to GA4 with explicit mapping, filtering, and test workflows.

Quick Start (2-5 Minutes)

Set GA4 config

Provide measurementId and optional apiSecret.

PUT /api/v1/sites/:siteId/integrations/ga4

Add event mapping

Map Selwise canonical events to GA4 event names.

{ "eventMapping": { "purchase": "purchase", "add_to_cart": "add_to_cart" } }

Add optional filters

Forward only events that pass conditional rules.

{ "eventFilters": { "purchase": { "enabled": true, "conditions": [{ "field": "order.total", "operator": "gte", "value": 1 }] } } }

Test connection

Run test endpoint to validate connectivity.

POST /api/v1/sites/:siteId/integrations/ga4/test

Inspect logs

Review delivery logs for failures and payload diagnostics.

GET /api/v1/sites/:siteId/integrations/ga4/logs?limit=50

GA4 config example

{
"enabled": true,
"config": {
  "measurementId": "G-XXXXXXXXXX",
  "apiSecret": "GA4_API_SECRET"
},
"eventMapping": {
  "page_view": "page_view",
  "search_query": "search",
  "add_to_cart": "add_to_cart",
  "purchase": "purchase"
},
"testMode": false
}

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`enabled`	Optional	`boolean`	GA4 update payload	Turns GA4 forwarding on or off.
`config.measurementId`	Required	`string`	GA4 update payload	GA4 measurement stream ID.
`config.apiSecret`	Optional	`string`	GA4 update payload	Secret for Measurement Protocol-style forwarding.
`eventMapping`	Optional	`Record<string,string>`	GA4 update payload	Selwise-to-GA4 event mapping table.
`eventFilters`	Optional	`Record<string,filter>`	GA4 update payload	Conditional forwarding rules by event type.

Currency Behavior

GA4 payload currency is resolved with fallback order: event -> order -> site -> EUR.
Hardcoded USD fallback is not used in provider forwarding.
Revenue/value fields should be emitted with the resolved currency only.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Initial GA4 setup	PUT /integrations/ga4	Single source of truth for GA4 config.
Connectivity validation	POST /integrations/ga4/test	Ensures credentials and channel health.
Production failure diagnosis	GET /integrations/ga4/logs	Detailed delivery status visibility.
Need baseline mapping template	GET /integrations/ga4/mappings	Provider default mapping reference.
Need temporary no-send validation	testMode=true	Audit payload flow without external sends.

Common Errors and Fixes

GA4 test fails with auth/config error

Cause: measurementId or apiSecret invalid for target property.

Fix: Re-issue credentials and rerun provider test.

Some events absent in GA4

Cause: Missing eventMapping entries or restrictive filters.

Fix: Map all required canonical events and review filter conditions.

Unexpected event naming in GA4

Cause: Custom mapping overwriting expected names.

Fix: Align mapping with GA4 naming convention strategy.

Traffic visible in logs only

Cause: testMode left enabled.

Fix: Disable testMode after validation.

Production Checklist

measurementId and apiSecret are validated with live test call.Required
Canonical purchase and cart events are explicitly mapped.Required
eventFilters are minimal and documented to avoid accidental drops.Required
testMode is disabled in production.Required
GA4 delivery logs are monitored during release windows.Required