Skip to main content

Mapping

Mapping transforms your events - either as they come from sources or before they go to destinations. Use the same mapping syntax in both places.

Why Mapping?​

For Sources: Clean up messy input data, filter unwanted events, normalize formats

For Destinations: Transform events to match what each tool expects (GA4, Meta, etc.)

When to Use​

Source Mapping:

  • Filter test/debug events before they reach your collector
  • Rename inconsistent event names from different sources
  • Validate or normalize data before processing

Destination Mapping:

  • Transform event names to match destination requirements (e.g., product view → view_item for GA4)
  • Reshape data to fit destination APIs
  • Add required fields like currency codes

How It Works​

Map events by their entity-action structure:

// Source: Clean up what comes in
sources: {
  browser: {
    config: {
      mapping: {
        product: {
          click: { name: 'product view' }  // Standardize clicks to views
        },
        test: {
          '*': { ignore: true }  // Filter out test events
        }
      }
    }
  }
}

// Destination: Format for specific tools
destinations: {
  gtag: {
    config: {
      mapping: {
        product: {
          view: {
            name: 'view_item',  // GA4 expects this name
            data: {
              map: {
                item_id: 'data.id',
                value: 'data.price'
              }
            }
          }
        }
      }
    }
  }
}

Both mappings are independent - one event can be transformed differently at each stage.

What You Can Do​

  • Rename events to match your needs or destination requirements
  • Filter events by ignoring unwanted ones
  • Reshape data to match destination formats
  • Add static values like currency codes
  • Validate data before sending
  • Require consent to respect user privacy

Event Mapping with getMappingEvent​

getMappingEvent(event: WalkerOS.PartialEvent, mapping?: Mapping.Rules): Promise<Mapping.Result>

This function finds the appropriate mapping configuration for an event based on its entity and action.

Basic Event Mapping​

Map specific entity-action combinations to custom event names:

Configuration
Result

Wildcard Mappings​

Use wildcards (*) to match multiple entities or actions:

Configuration
Result

Conditional Mappings​

Use conditions to apply different mappings based on event properties:

Configuration
Result

Ignoring Events​

Skip processing certain events by setting ignore: true:

Configuration
Result

Value Mapping with getMappingValue​

getMappingValue(value: unknown, mapping: Mapping.Data, options?: Mapping.Options): Promise<WalkerOS.Property | undefined>

This function transforms values using various mapping strategies.

String Key Mapping​

Use a string to extract a value by its property path:

Configuration
Result

Array Access​

Access array elements using dot notation:

Configuration
Result

Static Values​

Return static values using the value property:

Configuration
Result

Custom Functions​

Transform values using custom functions:

Configuration
Result

Object Mapping​

Create new objects by mapping properties:

Configuration
Result

Array Processing with Loop​

Process arrays and transform each item:

Configuration
Result

Validation​

Validate values and return undefined if validation fails:

Configuration
Result

Only return values when required consent is granted:

Configuration
Result

Usage Examples​

Source Mapping​

Normalize events before they reach the collector:

await startFlow({
  sources: {
    browser: {
      code: sourceBrowser,
      config: {
        mapping: {
          // Rename DOM clicks to views
          product: { click: { name: 'product view' } },
          // Ignore test events
          test: { '*': { ignore: true } },
        },
        policy: {
          // Normalize user email
          'user.email': { fn: (e) => e.user?.email?.toLowerCase() }
        }
      }
    }
  }
});

Destination Mapping​

Transform for specific destination APIs:

await startFlow({
  destinations: {
    gtag: {
      code: destinationGtag,
      config: {
        mapping: {
          product: {
            view: {
              name: 'view_item',
              data: {
                map: {
                  item_id: 'data.id',
                  value: 'data.price',
                  currency: { value: 'USD' }
                }
              }
            }
          }
        }
      }
    }
  }
});

Combined Flow​

Event processed twice with different configs:

// 1. Browser sends: "product click"
// 2. Source mapping: "product click" → "product view"
// 3. Destination mapping: "product view" → "view_item"
// 4. GA4 receives: "view_item"

Best Practices​

  1. Source mapping: Normalize, filter, validate incoming events
  2. Destination mapping: Transform to destination-specific formats
  3. Use specific mappings over wildcards for better performance
  4. Validate critical data before sending to destinations
  5. Respect consent by using consent-based mappings
  6. Keep transformations simple - complex logic in custom functions
💡 Need Professional Support?
Need professional support with your walkerOS implementation? Check out our services.