@suucha/analytics-ga4

Google Analytics 4 reporter implementation for Suucha Web SDK. Dynamically loads the gtag.js script and forwards events.

Install

pnpm add @suucha/core @suucha/analytics-ga4

Usage

import { suucha } from '@suucha/core';
import { GA4Reporter } from '@suucha/analytics-ga4';

const ga4 = new GA4Reporter({
  measurementId: 'G-XXXXXXXXXX',
  anonymizeIp: true,         // GDPR-friendly default
  allowAdFeatures: false,    // disable advertising features
});

suucha.addReporter(ga4);

// Or register as a region reporter (only fires for overseas visitors)
suucha.region.reporters({
  global: [ga4],
});

GDPR / Consent Mode

import { suucha } from '@suucha/core';
import { GA4Reporter } from '@suucha/analytics-ga4';

// Don't load GA4 script until user grants consent
const ga4 = new GA4Reporter({
  measurementId: 'G-XXX',
  deferUntilConsent: true,
});

suucha.addReporter(ga4);

// ... later, after CMP callback ...
suucha.setConsent(true);
ga4.load();  // script loads, queued events flush automatically

Options

| Option | Default | Description | |---|---|---| | measurementId | (required) | GA4 Measurement ID, e.g. 'G-XXXXXXXX' | | sendTo | measurementId | Override for multi-account setups | | anonymizeIp | true | Anonymize IP (GDPR best practice) | | allowAdFeatures | false | Disable Google Signals / advertising features | | deferUntilConsent | false | Skip script load until load() called |

Event Mapping

Suucha events are forwarded directly to GA4 as gtag('event', name, params). Built-in anonymous_id is stripped automatically (GA4 reserves user properties).

License

MIT © Suucha Studio