mytart 0.3.0 → 0.4.0

package/README.md

@@ -86,6 +86,64 @@ When `appType: 'browser'` is set:
 - SSR-safe: silently succeeds when `window` is undefined (e.g. during server-side rendering)
 - `apiSecret` is not required (and not used)
 
+#### Google Signals (demographics)
+
+To enable demographic data (age, gender, interests) in GA4 reports, set `signals: true`:
+
+```typescript
+{
+  provider: 'google-analytics',
+  measurementId: 'G-XXXXXXXXXX',
+  appType: 'browser',
+  enabled: true,
+  signals: true,
+}
+```
+
+This does two things automatically:
+
+1. Passes `allow_google_signals: true` and `allow_ad_personalization_signals: true` to `gtag('config')`
+2. Sets Consent Mode v2 defaults granting `ad_personalization`, `ad_user_data`, `ad_storage`, and `analytics_storage`
+
+Set `signals: false` to explicitly disable Google Signals. Omit the flag entirely to use Google's default behaviour.
+
+> **Note**: You must also enable Google Signals in the GA4 admin panel (Admin > Data Settings > Data Collection) for demographic data to appear.
+
+#### Consent Mode v2
+
+For GDPR/privacy compliance you can control Consent Mode v2 directly. Use `defaultConsent` to set the initial consent state (emitted before `gtag('config')`), and `updateConsent()` to change it at runtime when the user interacts with a cookie banner.
+
+```typescript
+const analytics = new Mytart({
+  providers: [{
+    provider: 'google-analytics',
+    measurementId: 'G-XXXXXXXXXX',
+    appType: 'browser',
+    enabled: true,
+    signals: true,
+    defaultConsent: {
+      ad_storage: 'denied',
+      analytics_storage: 'denied',
+      ad_user_data: 'denied',
+      ad_personalization: 'denied',
+    },
+    consentWaitForUpdate: 500, // wait 500ms for consent banner
+  }],
+});
+
+// After the user accepts the cookie banner:
+await analytics.updateConsent({
+  ad_storage: 'granted',
+  analytics_storage: 'granted',
+  ad_user_data: 'granted',
+  ad_personalization: 'granted',
+});
+```
+
+When both `signals: true` and `defaultConsent` are set, the explicit `defaultConsent` takes precedence over the auto-consent that `signals` would generate. This lets you combine `signals: true` (for the config flags) with a GDPR-safe denied-by-default consent flow.
+
+Consent Mode is a no-op in server mode (the Measurement Protocol does not support it).
+
 ### Mixpanel
 
 ```typescript
@@ -180,6 +238,22 @@ interface PageOptions {
 }
 ```
 
+### `analytics.updateConsent(consent: ConsentSettings): Promise<void>`
+
+Updates Google Consent Mode v2 state at runtime. Call this when the user interacts with a cookie/consent banner. Only affects Google Analytics in browser mode; all other providers ignore it.
+
+```typescript
+interface ConsentSettings {
+  ad_storage?: 'granted' | 'denied';
+  analytics_storage?: 'granted' | 'denied';
+  ad_user_data?: 'granted' | 'denied';
+  ad_personalization?: 'granted' | 'denied';
+  functionality_storage?: 'granted' | 'denied';
+  personalization_storage?: 'granted' | 'denied';
+  security_storage?: 'granted' | 'denied';
+}
+```
+
 ### `analytics.addProvider(config: ProviderConfig): void`
 
 Dynamically add a provider at runtime.
@@ -220,7 +294,7 @@ All types are exported:
 import type {
   MytartConfig, BaseProviderConfig, ProviderConfig, TrackOptions, IdentifyOptions, PageOptions,
   TrackResult, MytartError, EventContext, ProviderName, GoogleAnalyticsAppType,
-  GoogleAnalyticsConfig, MixpanelConfig, SegmentConfig,
+  GoogleAnalyticsConfig, ConsentSettings, ConsentState, MixpanelConfig, SegmentConfig,
   AmplitudeConfig, PlausibleConfig, PostHogConfig,
 } from 'mytart';
 ```

package/dist/index.d.mts

@@ -8,6 +8,33 @@ interface BaseProviderConfig {
     /** Whether this provider is active. Defaults to `false` when omitted. */
     enabled?: boolean;
 }
+type ConsentState = 'granted' | 'denied';
+/**
+ * Google Consent Mode v2 settings.
+ * Controls how Google tags behave based on user consent.
+ *
+ * Key fields for Google Signals demographics (age, gender, interests):
+ * - `ad_personalization` — must be `'granted'` for Google Signals to attribute
+ *   demographic data to sessions.
+ * - `ad_user_data` — must be `'granted'` for user data to be sent to Google
+ *   for advertising purposes.
+ */
+interface ConsentSettings {
+    /** Controls storage of advertising-related cookies. */
+    ad_storage?: ConsentState;
+    /** Controls storage of analytics-related cookies. */
+    analytics_storage?: ConsentState;
+    /** Controls whether user data can be sent to Google for advertising. */
+    ad_user_data?: ConsentState;
+    /** Controls whether data can be used for personalized advertising. */
+    ad_personalization?: ConsentState;
+    /** Controls storage for functional purposes (e.g. language settings). */
+    functionality_storage?: ConsentState;
+    /** Controls storage for personalization (e.g. video recommendations). */
+    personalization_storage?: ConsentState;
+    /** Controls storage for security purposes (e.g. authentication). */
+    security_storage?: ConsentState;
+}
 type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog';
 type GoogleAnalyticsAppType = 'browser' | 'server';
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
@@ -17,6 +44,44 @@ interface GoogleAnalyticsConfig extends BaseProviderConfig {
     clientId?: string;
     debug?: boolean;
     appType?: GoogleAnalyticsAppType;
+    /**
+     * Default consent state set before gtag('config'). In browser mode this
+     * emits `gtag('consent', 'default', ...)` so Google tags respect user
+     * consent from the very first hit. Use `Mytart.updateConsent()` to change
+     * consent at runtime (e.g. after a cookie banner interaction).
+     *
+     * For Google Signals demographics, `ad_personalization` and `ad_user_data`
+     * must eventually be set to `'granted'`.
+     */
+    defaultConsent?: ConsentSettings;
+    /**
+     * When `true`, sets `wait_for_update` (in milliseconds) on the default
+     * consent command. This tells Google tags to wait the specified number of
+     * milliseconds for a consent update before sending the first hit. Useful
+     * when a consent management platform loads asynchronously.
+     * Defaults to `undefined` (no wait).
+     */
+    consentWaitForUpdate?: number;
+    /**
+     * Convenience flag to enable or disable Google Signals for demographics
+     * (age, gender, interests).
+     *
+     * - `true`  — passes `allow_google_signals: true` and
+     *   `allow_ad_personalization_signals: true` in the `gtag('config')`
+     *   call. If `defaultConsent` is not explicitly set, automatically
+     *   configures Consent Mode v2 to grant `ad_personalization`,
+     *   `ad_user_data`, `ad_storage`, and `analytics_storage`.
+     * - `false` — passes `allow_google_signals: false` and
+     *   `allow_ad_personalization_signals: false` to explicitly disable
+     *   Google Signals.
+     * - `undefined` (default) — uses Google's default behaviour (Signals
+     *   enabled when the GA4 property has it turned on in Admin).
+     *
+     * **Note**: Google Signals must also be enabled in the GA4 admin panel
+     * (Admin › Data Settings › Data Collection) for demographic data to
+     * appear. This flag controls the client-side consent and config only.
+     */
+    signals?: boolean;
 }
 interface MixpanelConfig extends BaseProviderConfig {
     provider: 'mixpanel';
@@ -106,6 +171,16 @@ declare class Mytart {
     track(options: TrackOptions): Promise<TrackResult[]>;
     identify(options: IdentifyOptions): Promise<TrackResult[]>;
     page(options: PageOptions): Promise<TrackResult[]>;
+    /**
+     * Update consent state across all providers that support consent management.
+     * Currently this is meaningful for Google Analytics (Consent Mode v2) in
+     * browser mode. Call this when the user interacts with a cookie/consent
+     * banner.
+     *
+     * To enable Google Signals demographics (age, gender, interests), grant
+     * at least `ad_personalization` and `ad_user_data`.
+     */
+    updateConsent(consent: ConsentSettings): Promise<void>;
     addProvider(config: ProviderConfig): void;
     removeProvider(name: string): void;
     getProviders(): string[];
@@ -116,6 +191,11 @@ declare abstract class BaseProvider {
     abstract track(options: TrackOptions): Promise<TrackResult>;
     abstract identify(options: IdentifyOptions): Promise<TrackResult>;
     abstract page(options: PageOptions): Promise<TrackResult>;
+    /**
+     * Update consent state. Only meaningful for providers that support consent
+     * management (e.g. Google Analytics Consent Mode v2). Default is a no-op.
+     */
+    updateConsent(_consent: ConsentSettings): Promise<void>;
     protected buildError(message: string, code: string, originalError?: unknown): TrackResult;
     protected buildSuccess(statusCode?: number): TrackResult;
 }
@@ -147,6 +227,10 @@ declare class GoogleAnalyticsProvider extends BaseProvider {
      *     gtag('config', 'TAG_ID');
      *   </script>
      *
+     * When `defaultConsent` is configured, a `gtag('consent', 'default', ...)`
+     * call is emitted **before** `gtag('js')` and `gtag('config')`, as required
+     * by Google's Consent Mode v2 specification.
+     *
      * Key details:
      * - The script URL MUST include ?id=TAG_ID for Google Tag Tester detection
      * - dataLayer and the gtag shim are set up BEFORE the script loads
@@ -164,6 +248,18 @@ declare class GoogleAnalyticsProvider extends BaseProvider {
     private identifyBrowser;
     private pageBrowser;
     private buildGtagResult;
+    /**
+     * Updates the consent state at runtime. In browser mode this emits
+     * `gtag('consent', 'update', ...)`. Call this when the user interacts
+     * with a cookie/consent banner.
+     *
+     * To enable Google Signals demographics (age, gender, interests), grant
+     * at least `ad_personalization` and `ad_user_data`.
+     *
+     * In server mode this is a no-op — the Measurement Protocol does not
+     * support Consent Mode.
+     */
+    updateConsent(consent: ConsentSettings): Promise<void>;
     track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
     identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
     page({ name, url, referrer, userId, anonymousId }: PageOptions): Promise<TrackResult>;
@@ -226,4 +322,4 @@ declare class PostHogProvider extends BaseProvider {
     page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };

package/dist/index.d.ts

@@ -8,6 +8,33 @@ interface BaseProviderConfig {
     /** Whether this provider is active. Defaults to `false` when omitted. */
     enabled?: boolean;
 }
+type ConsentState = 'granted' | 'denied';
+/**
+ * Google Consent Mode v2 settings.
+ * Controls how Google tags behave based on user consent.
+ *
+ * Key fields for Google Signals demographics (age, gender, interests):
+ * - `ad_personalization` — must be `'granted'` for Google Signals to attribute
+ *   demographic data to sessions.
+ * - `ad_user_data` — must be `'granted'` for user data to be sent to Google
+ *   for advertising purposes.
+ */
+interface ConsentSettings {
+    /** Controls storage of advertising-related cookies. */
+    ad_storage?: ConsentState;
+    /** Controls storage of analytics-related cookies. */
+    analytics_storage?: ConsentState;
+    /** Controls whether user data can be sent to Google for advertising. */
+    ad_user_data?: ConsentState;
+    /** Controls whether data can be used for personalized advertising. */
+    ad_personalization?: ConsentState;
+    /** Controls storage for functional purposes (e.g. language settings). */
+    functionality_storage?: ConsentState;
+    /** Controls storage for personalization (e.g. video recommendations). */
+    personalization_storage?: ConsentState;
+    /** Controls storage for security purposes (e.g. authentication). */
+    security_storage?: ConsentState;
+}
 type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog';
 type GoogleAnalyticsAppType = 'browser' | 'server';
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
@@ -17,6 +44,44 @@ interface GoogleAnalyticsConfig extends BaseProviderConfig {
     clientId?: string;
     debug?: boolean;
     appType?: GoogleAnalyticsAppType;
+    /**
+     * Default consent state set before gtag('config'). In browser mode this
+     * emits `gtag('consent', 'default', ...)` so Google tags respect user
+     * consent from the very first hit. Use `Mytart.updateConsent()` to change
+     * consent at runtime (e.g. after a cookie banner interaction).
+     *
+     * For Google Signals demographics, `ad_personalization` and `ad_user_data`
+     * must eventually be set to `'granted'`.
+     */
+    defaultConsent?: ConsentSettings;
+    /**
+     * When `true`, sets `wait_for_update` (in milliseconds) on the default
+     * consent command. This tells Google tags to wait the specified number of
+     * milliseconds for a consent update before sending the first hit. Useful
+     * when a consent management platform loads asynchronously.
+     * Defaults to `undefined` (no wait).
+     */
+    consentWaitForUpdate?: number;
+    /**
+     * Convenience flag to enable or disable Google Signals for demographics
+     * (age, gender, interests).
+     *
+     * - `true`  — passes `allow_google_signals: true` and
+     *   `allow_ad_personalization_signals: true` in the `gtag('config')`
+     *   call. If `defaultConsent` is not explicitly set, automatically
+     *   configures Consent Mode v2 to grant `ad_personalization`,
+     *   `ad_user_data`, `ad_storage`, and `analytics_storage`.
+     * - `false` — passes `allow_google_signals: false` and
+     *   `allow_ad_personalization_signals: false` to explicitly disable
+     *   Google Signals.
+     * - `undefined` (default) — uses Google's default behaviour (Signals
+     *   enabled when the GA4 property has it turned on in Admin).
+     *
+     * **Note**: Google Signals must also be enabled in the GA4 admin panel
+     * (Admin › Data Settings › Data Collection) for demographic data to
+     * appear. This flag controls the client-side consent and config only.
+     */
+    signals?: boolean;
 }
 interface MixpanelConfig extends BaseProviderConfig {
     provider: 'mixpanel';
@@ -106,6 +171,16 @@ declare class Mytart {
     track(options: TrackOptions): Promise<TrackResult[]>;
     identify(options: IdentifyOptions): Promise<TrackResult[]>;
     page(options: PageOptions): Promise<TrackResult[]>;
+    /**
+     * Update consent state across all providers that support consent management.
+     * Currently this is meaningful for Google Analytics (Consent Mode v2) in
+     * browser mode. Call this when the user interacts with a cookie/consent
+     * banner.
+     *
+     * To enable Google Signals demographics (age, gender, interests), grant
+     * at least `ad_personalization` and `ad_user_data`.
+     */
+    updateConsent(consent: ConsentSettings): Promise<void>;
     addProvider(config: ProviderConfig): void;
     removeProvider(name: string): void;
     getProviders(): string[];
@@ -116,6 +191,11 @@ declare abstract class BaseProvider {
     abstract track(options: TrackOptions): Promise<TrackResult>;
     abstract identify(options: IdentifyOptions): Promise<TrackResult>;
     abstract page(options: PageOptions): Promise<TrackResult>;
+    /**
+     * Update consent state. Only meaningful for providers that support consent
+     * management (e.g. Google Analytics Consent Mode v2). Default is a no-op.
+     */
+    updateConsent(_consent: ConsentSettings): Promise<void>;
     protected buildError(message: string, code: string, originalError?: unknown): TrackResult;
     protected buildSuccess(statusCode?: number): TrackResult;
 }
@@ -147,6 +227,10 @@ declare class GoogleAnalyticsProvider extends BaseProvider {
      *     gtag('config', 'TAG_ID');
      *   </script>
      *
+     * When `defaultConsent` is configured, a `gtag('consent', 'default', ...)`
+     * call is emitted **before** `gtag('js')` and `gtag('config')`, as required
+     * by Google's Consent Mode v2 specification.
+     *
      * Key details:
      * - The script URL MUST include ?id=TAG_ID for Google Tag Tester detection
      * - dataLayer and the gtag shim are set up BEFORE the script loads
@@ -164,6 +248,18 @@ declare class GoogleAnalyticsProvider extends BaseProvider {
     private identifyBrowser;
     private pageBrowser;
     private buildGtagResult;
+    /**
+     * Updates the consent state at runtime. In browser mode this emits
+     * `gtag('consent', 'update', ...)`. Call this when the user interacts
+     * with a cookie/consent banner.
+     *
+     * To enable Google Signals demographics (age, gender, interests), grant
+     * at least `ad_personalization` and `ad_user_data`.
+     *
+     * In server mode this is a no-op — the Measurement Protocol does not
+     * support Consent Mode.
+     */
+    updateConsent(consent: ConsentSettings): Promise<void>;
     track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
     identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
     page({ name, url, referrer, userId, anonymousId }: PageOptions): Promise<TrackResult>;
@@ -226,4 +322,4 @@ declare class PostHogProvider extends BaseProvider {
     page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };

package/dist/index.js

@@ -43,6 +43,13 @@ module.exports = __toCommonJS(index_exports);
 
 // src/providers/base.ts
 var BaseProvider = class {
+  /**
+   * Update consent state. Only meaningful for providers that support consent
+   * management (e.g. Google Analytics Consent Mode v2). Default is a no-op.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async updateConsent(_consent) {
+  }
   buildError(message, code, originalError) {
     return {
       provider: this.name,
@@ -105,6 +112,10 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
    *     gtag('config', 'TAG_ID');
    *   </script>
    *
+   * When `defaultConsent` is configured, a `gtag('consent', 'default', ...)`
+   * call is emitted **before** `gtag('js')` and `gtag('config')`, as required
+   * by Google's Consent Mode v2 specification.
+   *
    * Key details:
    * - The script URL MUST include ?id=TAG_ID for Google Tag Tester detection
    * - dataLayer and the gtag shim are set up BEFORE the script loads
@@ -120,8 +131,33 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
     window.gtag = function gtag() {
       window.dataLayer.push(arguments);
     };
+    const resolvedConsent = this.config.defaultConsent ?? (this.config.signals === true ? {
+      ad_storage: "granted",
+      analytics_storage: "granted",
+      ad_user_data: "granted",
+      ad_personalization: "granted"
+    } : void 0);
+    if (resolvedConsent) {
+      const consentParams = { ...resolvedConsent };
+      if (this.config.consentWaitForUpdate !== void 0) {
+        consentParams["wait_for_update"] = this.config.consentWaitForUpdate;
+      }
+      window.gtag("consent", "default", consentParams);
+    }
     window.gtag("js", /* @__PURE__ */ new Date());
-    window.gtag("config", this.config.measurementId);
+    const configParams = {};
+    if (this.config.signals === true) {
+      configParams["allow_google_signals"] = true;
+      configParams["allow_ad_personalization_signals"] = true;
+    } else if (this.config.signals === false) {
+      configParams["allow_google_signals"] = false;
+      configParams["allow_ad_personalization_signals"] = false;
+    }
+    if (Object.keys(configParams).length > 0) {
+      window.gtag("config", this.config.measurementId, configParams);
+    } else {
+      window.gtag("config", this.config.measurementId);
+    }
     return new Promise((resolve) => {
       const script = document.createElement("script");
       script.async = true;
@@ -189,6 +225,27 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
     };
   }
   // ---------------------------------------------------------------------------
+  // Consent Mode v2
+  // ---------------------------------------------------------------------------
+  /**
+   * Updates the consent state at runtime. In browser mode this emits
+   * `gtag('consent', 'update', ...)`. Call this when the user interacts
+   * with a cookie/consent banner.
+   *
+   * To enable Google Signals demographics (age, gender, interests), grant
+   * at least `ad_personalization` and `ad_user_data`.
+   *
+   * In server mode this is a no-op — the Measurement Protocol does not
+   * support Consent Mode.
+   */
+  async updateConsent(consent) {
+    if (!this.isBrowser || typeof window === "undefined") {
+      return;
+    }
+    await this.ensureGtag();
+    window.gtag("consent", "update", consent);
+  }
+  // ---------------------------------------------------------------------------
   // Public API — routes to browser or server mode
   // ---------------------------------------------------------------------------
   async track({ event, properties, userId, anonymousId, timestamp }) {
@@ -748,6 +805,18 @@ var Mytart = class {
     };
     return Promise.all(this.providers.map((p) => p.page(enriched)));
   }
+  /**
+   * Update consent state across all providers that support consent management.
+   * Currently this is meaningful for Google Analytics (Consent Mode v2) in
+   * browser mode. Call this when the user interacts with a cookie/consent
+   * banner.
+   *
+   * To enable Google Signals demographics (age, gender, interests), grant
+   * at least `ad_personalization` and `ad_user_data`.
+   */
+  async updateConsent(consent) {
+    await Promise.all(this.providers.map((p) => p.updateConsent(consent)));
+  }
   addProvider(config) {
     if (config.enabled !== true) return;
     this.providers.push(createProvider(config));

package/dist/index.mjs

@@ -1,5 +1,12 @@
 // src/providers/base.ts
 var BaseProvider = class {
+  /**
+   * Update consent state. Only meaningful for providers that support consent
+   * management (e.g. Google Analytics Consent Mode v2). Default is a no-op.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async updateConsent(_consent) {
+  }
   buildError(message, code, originalError) {
     return {
       provider: this.name,
@@ -62,6 +69,10 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
    *     gtag('config', 'TAG_ID');
    *   </script>
    *
+   * When `defaultConsent` is configured, a `gtag('consent', 'default', ...)`
+   * call is emitted **before** `gtag('js')` and `gtag('config')`, as required
+   * by Google's Consent Mode v2 specification.
+   *
    * Key details:
    * - The script URL MUST include ?id=TAG_ID for Google Tag Tester detection
    * - dataLayer and the gtag shim are set up BEFORE the script loads
@@ -77,8 +88,33 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
     window.gtag = function gtag() {
       window.dataLayer.push(arguments);
     };
+    const resolvedConsent = this.config.defaultConsent ?? (this.config.signals === true ? {
+      ad_storage: "granted",
+      analytics_storage: "granted",
+      ad_user_data: "granted",
+      ad_personalization: "granted"
+    } : void 0);
+    if (resolvedConsent) {
+      const consentParams = { ...resolvedConsent };
+      if (this.config.consentWaitForUpdate !== void 0) {
+        consentParams["wait_for_update"] = this.config.consentWaitForUpdate;
+      }
+      window.gtag("consent", "default", consentParams);
+    }
     window.gtag("js", /* @__PURE__ */ new Date());
-    window.gtag("config", this.config.measurementId);
+    const configParams = {};
+    if (this.config.signals === true) {
+      configParams["allow_google_signals"] = true;
+      configParams["allow_ad_personalization_signals"] = true;
+    } else if (this.config.signals === false) {
+      configParams["allow_google_signals"] = false;
+      configParams["allow_ad_personalization_signals"] = false;
+    }
+    if (Object.keys(configParams).length > 0) {
+      window.gtag("config", this.config.measurementId, configParams);
+    } else {
+      window.gtag("config", this.config.measurementId);
+    }
     return new Promise((resolve) => {
       const script = document.createElement("script");
       script.async = true;
@@ -146,6 +182,27 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
     };
   }
   // ---------------------------------------------------------------------------
+  // Consent Mode v2
+  // ---------------------------------------------------------------------------
+  /**
+   * Updates the consent state at runtime. In browser mode this emits
+   * `gtag('consent', 'update', ...)`. Call this when the user interacts
+   * with a cookie/consent banner.
+   *
+   * To enable Google Signals demographics (age, gender, interests), grant
+   * at least `ad_personalization` and `ad_user_data`.
+   *
+   * In server mode this is a no-op — the Measurement Protocol does not
+   * support Consent Mode.
+   */
+  async updateConsent(consent) {
+    if (!this.isBrowser || typeof window === "undefined") {
+      return;
+    }
+    await this.ensureGtag();
+    window.gtag("consent", "update", consent);
+  }
+  // ---------------------------------------------------------------------------
   // Public API — routes to browser or server mode
   // ---------------------------------------------------------------------------
   async track({ event, properties, userId, anonymousId, timestamp }) {
@@ -705,6 +762,18 @@ var Mytart = class {
     };
     return Promise.all(this.providers.map((p) => p.page(enriched)));
   }
+  /**
+   * Update consent state across all providers that support consent management.
+   * Currently this is meaningful for Google Analytics (Consent Mode v2) in
+   * browser mode. Call this when the user interacts with a cookie/consent
+   * banner.
+   *
+   * To enable Google Signals demographics (age, gender, interests), grant
+   * at least `ad_personalization` and `ad_user_data`.
+   */
+  async updateConsent(consent) {
+    await Promise.all(this.providers.map((p) => p.updateConsent(consent)));
+  }
   addProvider(config) {
     if (config.enabled !== true) return;
     this.providers.push(createProvider(config));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mytart",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Multi-Yield Tracking & Analytics Relay Tool — framework-agnostic analytics for any project",
   "keywords": [
     "analytics",