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_itemfor GA4) - Reshape data to fit destination APIs
- Add required fields like currency codes
How It Works
Map events by their entity-action structure:
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
- Apply policies to modify events at config or event level
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:
Wildcard Mappings
Use wildcards (*) to match multiple entities or actions:
Conditional Mappings
Use conditions to apply different mappings based on event properties:
Ignoring Events
Skip processing certain events by setting ignore: true:
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:
Array Access
Access array elements using dot notation:
Static Values
Return static values using the value property:
Custom Functions
Transform values using custom functions:
Object Mapping
Create new objects by mapping properties:
Array Processing with Loop
Process arrays and transform each item:
Validation
Validate values and return undefined if validation fails:
Consent-Based Mapping
Only return values when required consent is granted:
Policy
Policies modify events before processing. Apply them at config-level (all events) or event-level (specific entity-action combinations).
Processing order: Config policy → Event matching → Event policy → Data transformation
Config-Level Policy
Global transformations applied to all events:
Event-Level Policy
Transformations for specific events:
Policies work with wildcards and conditions, and both levels can be combined - config policy runs first, then event policy for the matched rule.
Usage Examples
Source Mapping
Normalize events before they reach the collector:
Destination Mapping
Transform for specific destination APIs:
Combined Flow
Event processed twice with different configs:
Best Practices
- Source mapping: Normalize, filter, validate incoming events
- Destination mapping: Transform to destination-specific formats
- Use specific mappings over wildcards for better performance
- Validate critical data before sending to destinations
- Respect consent by using consent-based mappings
- Keep transformations simple - complex logic in custom functions