Mapping.Rule

A Mapping.Rule is the object that sits at config.mapping[entity][action] on a source or destination. It decides whether an event applies, renames it, reshapes its data, gates it by consent, and can emit side effects (batching, custom settings). The shape is defined in packages/core/src/types/mapping.ts.

Configuration

Property	Type	Description	More
name	string	Custom event name override (e.g., "view_item" for "product view")
data	Mapping.Value | Mapping.Value[]	Data transformation rules for event
settings	any	Destination-specific settings for this event mapping
condition	string	Condition function as string: return true to process event
consent	WalkerOS.Consent	Required consent states to process this event
policy	Record<string, Mapping.Value>	Event-level policy overrides (applied after config-level policy)
batch	number	Batch size: bundle N events for batch processing
include	Array<string>	Event sections (e.g. ["context", "globals"]) flattened into context.data
ignore	boolean	Skip the event entirely. No push, no side effects. Use for suppression.
skip	boolean	Run side effects (settings.identify, ...) but skip the default push call.

Every value-shaped field (data, entries in policy, entries in settings that take values) accepts any form documented in Mapping.Value.

How destinations consume a rule

When an event reaches a destination, the collector looks up mapping[event.entity][event.action]. An array means "try each in order, first matching rule wins". A wildcard '*' on either entity or action acts as a fallback.

Configuration

Loading...

Result

Loading...

Once a rule matches, the collector runs policy (event-level), resolves data, checks consent and condition, then hands the result to the destination's push (or buffers it when batch is set).

Conditional rules

Use an array with conditions to branch by event contents; the first matching rule wins.

Configuration

Loading...

Result

Loading...

Ignore vs skip

Two flags control destination behaviour and they are not interchangeable:

• ignore: true: the rule matched but nothing happens. No data transform, no destination call, no side effects. Use for suppression.
• skip: true: the rule matched and the destination's push() is called. settings.identify, settings.revenue, settings.group, and other side effects 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 are set on the same rule, ignore wins.

Configuration

Loading...

Result

Loading...

{
  user: {
    login: {
      skip: true,
      settings: { identify: { map: { user: 'data.id' } } },
    },
  },
}

The example runs the destination's identify() side effect on user login events but skips the default forwarding call.

API reference

The two functions below power mapping resolution. Destinations and sources call them through the collector, but they are exported for direct use in custom transformers or tests.

getMappingEvent

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

Resolves the matching rule for an event based on event.name (the "entity action" string). Returns { eventMapping, mappingKey } where eventMapping is the matched Mapping.Rule and mappingKey is the lookup key that matched (including wildcards).

getMappingValue

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

Resolves a Mapping.Value against an input. Used internally for every data, policy, and set resolution. The companion reference for each value form lives in Mapping.Value.

Rule-level examples

Source mapping

Normalize events before they reach the collector:

Loading...

Destination mapping

Transform for a specific destination API:

Loading...

Combined flow

The same event can be transformed at both stations:

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

See also

• Mapping.Value: the eight value forms used in every rule field
• Consent guide: consent model and gating
• Destinations reference: destination-specific settings
• mapping.ts source