@walkeros/web-destination-gtag 0.0.0-next-20251219153324

package/README.md

@@ -0,0 +1,314 @@
+# Google Gtag Destination for walkerOS
+
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/gtag)
+•
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-gtag)
+
+The Google Gtag destination provides a unified interface for sending events to
+Google Analytics 4 (GA4), Google Ads, and Google Tag Manager (GTM) through a
+single destination configuration.
+
+## Features
+
+- **Unified Configuration**: Configure GA4, Google Ads, and GTM in a single
+  destination
+- **Shared Script Loading**: Efficient gtag script loading shared across all
+  Google tools
+- **Tool-Specific Mappings**: Individual mapping configurations for each Google
+  tool
+- **TypeScript Support**: Full type safety with strict typing
+- **Flexible Usage**: Use one, two, or all three Google tools as needed
+
+## Installation
+
+```bash
+npm install @walkeros/web-destination-gtag
+```
+
+## Quick Start
+
+Configure in your Flow JSON:
+
+```json
+{
+  "version": 1,
+  "flows": {
+    "default": {
+      "web": {},
+      "destinations": {
+        "gtag": {
+          "package": "@walkeros/web-destination-gtag",
+          "config": {
+            "settings": {
+              "ga4": { "measurementId": "G-XXXXXXXXXX" },
+              "ads": { "conversionId": "AW-XXXXXXXXX" },
+              "gtm": { "containerId": "GTM-XXXXXXX" }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Or programmatically:
+
+```typescript
+import { startFlow } from '@walkeros/collector';
+import { destinationGtag } from '@walkeros/web-destination-gtag';
+
+const { elb } = await startFlow({
+  destinations: [
+    {
+      destination: destinationGtag,
+      config: {
+        settings: {
+          ga4: { measurementId: 'G-XXXXXXXXXX' },
+          ads: { conversionId: 'AW-XXXXXXXXX' },
+          gtm: { containerId: 'GTM-XXXXXXX' },
+        },
+      },
+    },
+  ],
+});
+```
+
+## Configuration
+
+| Name  | Type          | Description                                        | Required | Example                             |
+| ----- | ------------- | -------------------------------------------------- | -------- | ----------------------------------- |
+| `ga4` | `GA4Settings` | GA4-specific configuration settings                | No       | `{ measurementId: 'G-XXXXXXXXXX' }` |
+| `ads` | `AdsSettings` | Google Ads specific configuration settings         | No       | `{ conversionId: 'AW-XXXXXXXXX' }`  |
+| `gtm` | `GTMSettings` | Google Tag Manager specific configuration settings | No       | `{ containerId: 'GTM-XXXXXXX' }`    |
+
+### Event Mapping
+
+For custom event mapping (`mapping.entity.action.settings`):
+
+| Name  | Type         | Description                                     | Required | Example                            |
+| ----- | ------------ | ----------------------------------------------- | -------- | ---------------------------------- |
+| `ga4` | `GA4Mapping` | GA4-specific event mapping configuration        | No       | `{ include: ['data', 'context'] }` |
+| `ads` | `AdsMapping` | Google Ads specific event mapping configuration | No       | `{ label: 'conversion_label' }`    |
+| `gtm` | `GTMMapping` | GTM specific event mapping configuration        | No       | `{}`                               |
+
+## Consent Mode
+
+The gtag destination automatically handles Google Consent Mode v2 with a "deny
+by default" approach. Configure consent mode using the `como` setting:
+
+```typescript
+import { destinationGtag } from '@walkeros/web-destination-gtag';
+
+const destination = destinationGtag({
+  settings: {
+    como: true, // Enable with default mapping
+    ga4: { measurementId: 'G-XXXXXXXXXX' },
+  },
+});
+```
+
+### Configuration Options
+
+| Value    | Description          | Default Mapping                                                                                        |
+| -------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
+| `false`  | Disable consent mode | -                                                                                                      |
+| `true`   | Use default mapping  | `marketing` → `ad_storage`, `ad_user_data`, `ad_personalization`<br>`functional` → `analytics_storage` |
+| `object` | Custom mapping       | `{ [walkerOSGroup]: gtagParameter \| gtagParameter[] }`                                                |
+
+### Custom Mapping
+
+```typescript
+const destination = destinationGtag({
+  settings: {
+    como: {
+      marketing: ['ad_storage', 'ad_personalization'],
+      analytics: 'analytics_storage',
+    },
+    ga4: { measurementId: 'G-XXXXXXXXXX' },
+  },
+});
+```
+
+### Usage
+
+Consent mode automatically activates when you send consent events through
+walkerOS:
+
+```typescript
+// Grant consent
+elb('walker consent', { marketing: true, functional: true });
+
+// Deny consent
+elb('walker consent', { marketing: false, functional: false });
+```
+
+The destination handles all gtag consent calls automatically, ensuring
+compliance with privacy regulations.
+
+## Examples
+
+### E-commerce Purchase
+
+```typescript
+import { destinationGtag } from '@walkeros/web-destination-gtag';
+
+const destination = destinationGtag({
+  settings: {
+    ga4: { measurementId: 'G-XXXXXXXXXX' },
+    ads: { conversionId: 'AW-XXXXXXXXX' },
+  },
+  mapping: {
+    order: {
+      complete: {
+        name: 'purchase',
+        settings: {
+          ga4: { include: ['data'] },
+          ads: {
+            label: 'PURCHASE_LABEL', // Specify conversion label
+          },
+        },
+        data: {
+          map: {
+            transaction_id: 'data.id',
+            value: 'data.total',
+            currency: 'data.currency',
+            items: {
+              loop: [
+                'nested',
+                {
+                  condition: (entity) => entity.entity === 'product',
+                  map: {
+                    item_id: 'data.id',
+                    item_name: 'data.name',
+                    quantity: 'data.quantity',
+                  },
+                },
+              ],
+            },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+### Custom Event with All Tools
+
+```typescript
+const customEventMapping = {
+  product: {
+    view: {
+      name: 'view_item',
+      settings: {
+        ga4: { include: ['data', 'context'] },
+        ads: {}, // No conversion tracking for product views
+        gtm: {}, // Send to GTM dataLayer
+      },
+      data: {
+        map: {
+          item_id: 'data.id',
+          item_name: 'data.name',
+          item_category: 'data.category',
+          value: 'data.price',
+          currency: 'data.currency',
+        },
+      },
+    },
+  },
+};
+```
+
+## TypeScript
+
+Full TypeScript support with strict typing:
+
+```typescript
+import type { DestinationGtag } from '@walkeros/web-destination-gtag';
+
+// Type-safe configuration
+const config: DestinationGtag.Config = {
+  settings: {
+    ga4: {
+      measurementId: 'G-XXXXXXXXXX',
+      debug: true,
+    },
+  },
+};
+
+// Type-safe mapping rules
+const rules: DestinationGtag.Rules = {
+  order: {
+    complete: {
+      name: 'purchase',
+      settings: {
+        ga4: { include: ['data'] },
+      },
+      data: {
+        map: {
+          transaction_id: 'data.id',
+          value: 'data.total',
+        },
+      },
+    },
+  },
+};
+```
+
+## Best Practices
+
+1. **Use Combined Configuration**: When using multiple Google tools, configure
+   them in a single destination for better performance and maintenance.
+
+2. **Tool-Specific Mappings**: Use tool-specific mapping settings to customize
+   behavior for each Google product.
+
+3. **Conversion Labels**: For Google Ads, use descriptive conversion labels in
+   the mapping `name` field.
+
+4. **Data Inclusion**: Use GA4's `include` setting to control which data groups
+   are sent to minimize payload size.
+
+5. **Debug Mode**: Enable GA4 debug mode during development to verify event
+   tracking.
+
+## Troubleshooting
+
+**Events not appearing in GA4:**
+
+- Verify the measurement ID is correct
+- Check that events are being triggered
+- Enable debug mode to see events in GA4 DebugView
+
+**Google Ads conversions not tracking:**
+
+- Ensure conversion ID and labels are correctly configured
+- Verify the `settings.ads.label` field contains the correct conversion label
+- Check that the conversion action is set up in Google Ads
+
+**GTM events not appearing:**
+
+- Verify the container ID is correct
+- Check the dataLayer name matches your GTM configuration
+- Use GTM Preview mode to debug event flow
+
+## Type Definitions
+
+See [src/types/](./src/types/) for TypeScript interfaces.
+
+## Related
+
+- [Website Documentation](https://www.walkeros.io/docs/destinations/web/gtag/)
+- [Destination Interface](../../../core/src/types/destination.ts)
+
+## Contribute
+
+Feel free to contribute by submitting an
+[issue](https://github.com/elbwalker/walkerOS/issues), starting a
+[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
+[contact](https://calendly.com/elb-alexander/30min).
+
+## License
+
+MIT

package/dist/dev.d.mts

@@ -0,0 +1,240 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { Mapping as Mapping$2 } from '@walkeros/core';
+import { DestinationWeb } from '@walkeros/web-core';
+
+/**
+ * Include configuration for GA4
+ * Specifies which event properties to include
+ */
+declare const IncludeSchema: z.ZodArray<z.ZodEnum<{
+    all: "all";
+    context: "context";
+    data: "data";
+    event: "event";
+    globals: "globals";
+    source: "source";
+    user: "user";
+    version: "version";
+}>>;
+/**
+ * Consent Mode Configuration
+ * Can be false (disabled), true (use defaults), or custom mapping
+ */
+declare const ConsentModeSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>]>;
+declare const GA4SettingsSchema: z.ZodObject<{
+    measurementId: z.ZodString;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        all: "all";
+        context: "context";
+        data: "data";
+        event: "event";
+        globals: "globals";
+        source: "source";
+        user: "user";
+        version: "version";
+    }>>>;
+    pageview: z.ZodOptional<z.ZodBoolean>;
+    server_container_url: z.ZodOptional<z.ZodString>;
+    snakeCase: z.ZodOptional<z.ZodBoolean>;
+    transport_url: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodAny>;
+}, z.core.$strip>;
+/**
+ * Google Ads Settings Schema
+ * Configuration for Google Ads conversions
+ */
+declare const AdsSettingsSchema: z.ZodObject<{
+    conversionId: z.ZodString;
+    currency: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodAny>;
+}, z.core.$strip>;
+/**
+ * GTM Settings Schema
+ * Configuration for Google Tag Manager
+ */
+declare const GTMSettingsSchema: z.ZodObject<{
+    containerId: z.ZodString;
+    dataLayer: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodAny>;
+}, z.core.$strip>;
+
+declare const SettingsSchema: z.ZodObject<{
+    como: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>]>>;
+    ga4: z.ZodOptional<z.ZodObject<{
+        measurementId: z.ZodString;
+        debug: z.ZodOptional<z.ZodBoolean>;
+        include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            all: "all";
+            context: "context";
+            data: "data";
+            event: "event";
+            globals: "globals";
+            source: "source";
+            user: "user";
+            version: "version";
+        }>>>;
+        pageview: z.ZodOptional<z.ZodBoolean>;
+        server_container_url: z.ZodOptional<z.ZodString>;
+        snakeCase: z.ZodOptional<z.ZodBoolean>;
+        transport_url: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodAny>;
+    }, z.core.$strip>>;
+    ads: z.ZodOptional<z.ZodObject<{
+        conversionId: z.ZodString;
+        currency: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodAny>;
+    }, z.core.$strip>>;
+    gtm: z.ZodOptional<z.ZodObject<{
+        containerId: z.ZodString;
+        dataLayer: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodAny>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+/**
+ * Gtag Mapping Schema
+ * Tool-specific event-level mappings
+ */
+declare const MappingSchema: z.ZodObject<{
+    ga4: z.ZodOptional<z.ZodObject<{
+        include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            all: "all";
+            context: "context";
+            data: "data";
+            event: "event";
+            globals: "globals";
+            source: "source";
+            user: "user";
+            version: "version";
+        }>>>;
+    }, z.core.$strip>>;
+    ads: z.ZodOptional<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    gtm: z.ZodOptional<z.ZodObject<{}, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Type inference from MappingSchema
+ */
+type Mapping$1 = z.infer<typeof MappingSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const mapping$1: _walkeros_core_dev.JSONSchema;
+declare const ga4: _walkeros_core_dev.JSONSchema;
+declare const ads: _walkeros_core_dev.JSONSchema;
+declare const gtm: _walkeros_core_dev.JSONSchema;
+
+declare const index$1_AdsSettingsSchema: typeof AdsSettingsSchema;
+declare const index$1_ConsentModeSchema: typeof ConsentModeSchema;
+declare const index$1_GA4SettingsSchema: typeof GA4SettingsSchema;
+declare const index$1_GTMSettingsSchema: typeof GTMSettingsSchema;
+declare const index$1_IncludeSchema: typeof IncludeSchema;
+declare const index$1_MappingSchema: typeof MappingSchema;
+type index$1_Settings = Settings;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_ads: typeof ads;
+declare const index$1_ga4: typeof ga4;
+declare const index$1_gtm: typeof gtm;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { index$1_AdsSettingsSchema as AdsSettingsSchema, index$1_ConsentModeSchema as ConsentModeSchema, index$1_GA4SettingsSchema as GA4SettingsSchema, index$1_GTMSettingsSchema as GTMSettingsSchema, index$1_IncludeSchema as IncludeSchema, type Mapping$1 as Mapping, index$1_MappingSchema as MappingSchema, type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, index$1_ads as ads, index$1_ga4 as ga4, index$1_gtm as gtm, mapping$1 as mapping, index$1_settings as settings };
+}
+
+declare global {
+    interface Window {
+        gtag?: Gtag.Gtag;
+        [key: string]: unknown;
+    }
+}
+interface Env extends DestinationWeb.Env {
+    window: {
+        gtag: Gtag.Gtag;
+        dataLayer: unknown[];
+    };
+    document: {
+        createElement: (tagName: string) => {
+            src: string;
+            async?: boolean;
+            setAttribute: (name: string, value: string) => void;
+            removeAttribute: (name: string) => void;
+        };
+        head: {
+            appendChild: (node: unknown) => void;
+        };
+    };
+}
+interface AdsMapping {
+    label?: string;
+}
+interface Mapping {
+    ga4?: GA4Mapping;
+    ads?: AdsMapping;
+    gtm?: GTMMapping;
+}
+interface GA4Mapping {
+    include?: Include;
+}
+interface GTMMapping {
+}
+type Rule = Mapping$2.Rule<Mapping>;
+type Include = Array<'all' | 'context' | 'data' | 'event' | 'globals' | 'source' | 'user' | 'version'>;
+
+declare const init: Env | undefined;
+declare const push: Env;
+declare const simulation: string[];
+
+declare const env_init: typeof init;
+declare const env_push: typeof push;
+declare const env_simulation: typeof simulation;
+declare namespace env {
+  export { env_init as init, env_push as push, env_simulation as simulation };
+}
+
+declare function ga4Purchase$1(): unknown[];
+declare function ga4AddToCart$1(): unknown[];
+declare function adsConversion$1(): unknown[];
+declare function gtmEvent(): Record<string, unknown>;
+
+declare const events_gtmEvent: typeof gtmEvent;
+declare namespace events {
+  export { adsConversion$1 as adsConversion, ga4AddToCart$1 as ga4AddToCart, ga4Purchase$1 as ga4Purchase, events_gtmEvent as gtmEvent };
+}
+
+declare const ga4Purchase: Rule;
+declare const ga4AddToCart: Rule;
+declare const adsConversion: Rule;
+declare const gtmProductView: Rule;
+declare const combinedPurchase: Rule;
+declare const config: {
+    order: {
+        complete: Rule;
+    };
+    product: {
+        add: Rule;
+        view: Rule;
+    };
+};
+
+declare const mapping_adsConversion: typeof adsConversion;
+declare const mapping_combinedPurchase: typeof combinedPurchase;
+declare const mapping_config: typeof config;
+declare const mapping_ga4AddToCart: typeof ga4AddToCart;
+declare const mapping_ga4Purchase: typeof ga4Purchase;
+declare const mapping_gtmProductView: typeof gtmProductView;
+declare namespace mapping {
+  export { mapping_adsConversion as adsConversion, mapping_combinedPurchase as combinedPurchase, mapping_config as config, mapping_ga4AddToCart as ga4AddToCart, mapping_ga4Purchase as ga4Purchase, mapping_gtmProductView as gtmProductView };
+}
+
+declare const index_env: typeof env;
+declare const index_events: typeof events;
+declare const index_mapping: typeof mapping;
+declare namespace index {
+  export { index_env as env, index_events as events, index_mapping as mapping };
+}
+
+export { index as examples, index$1 as schemas };