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 - the same 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:
Skip vs Ignore
Two related but distinct rule flags control destination behavior:
ignore: true: the rule matched but nothing happens. No data transformation, no destination call, no side effects. Use for suppression.skip: true: the rule matched and the destination'spush()is called.settings.identify,settings.revenue,settings.group, etc. still run. Only the destination's default forwarding call (e.g.track(),capture(),event()) is suppressed. Use for "identify without an event" style flows.
If both flags are set on the same rule, ignore wins.
{
user: {
login: {
skip: true,
settings: { identify: { map: { user: 'data.id' } } },
},
},
}
The example above runs the destination's identify() side effect on
user login events but skips the destination's default forwarding call.
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