Event Mapping and Filters

Event Mapping and Filters

Define forward mapping, reverse mapping, and conditional filters for provider integrations.

Audience: Integration engineers controlling event translation and forwarding quality.

Critical: Mapping and filter contracts are configured via provider update payloads on PUT /api/v1/sites/:siteId/integrations/:provider.

Integrations OverviewData LayerReference: Event Types

Who This Page Is For

Use this page when you need deterministic translation from Selwise canonical events to provider event names and conditional control over which events are forwarded.

Quick Start (2-5 Minutes)

1

Get default provider mappings

Start from provider default map before custom edits.

GET /api/v1/sites/:siteId/integrations/:provider/mappings

2

Set eventMapping

Map canonical Selwise events to provider-specific names.

{ "eventMapping": { "purchase": "Purchase", "search_query": "search" } }

3

Set reverseEventMapping

Map external data-layer event names back to Selwise canonical names.

{ "reverseEventMapping": { "begin_checkout": "checkout_begin" } }

4

Set eventFilters

Use field/operator/value conditions to allow or block sends.

{ "eventFilters": { "purchase": { "enabled": true, "conditions": [{ "field": "order.total", "operator": "gte", "value": 1 }] } } }

5

Validate with provider test

Confirm mapping/filter behavior in controlled test path.

POST /api/v1/sites/:siteId/integrations/:provider/test

Mapping payload example

{
"enabled": true,
"eventMapping": {
  "page_view": "PageView",
  "add_to_cart": "AddToCart",
  "purchase": "Purchase"
},
"reverseEventMapping": {
  "begin_checkout": "checkout_begin",
  "purchase": "purchase"
},
"eventFilters": {
  "purchase": {
    "enabled": true,
    "conditions": [
      { "field": "order.total", "operator": "gte", "value": 1 }
    ]
  }
}
}

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
eventMapping	Optional	Record<string,string>	Provider update payload	Canonical Selwise event -> provider event mapping.
reverseEventMapping	Optional	Record<string,string>	Provider update payload	External event -> canonical Selwise event mapping.
eventFilters.<event>.enabled	Optional	boolean	Provider update payload	Enables/disables forwarding for that event group.
eventFilters.<event>.conditions[]	Optional	{field,operator,value}[]	Provider update payload	Conditional forwarding rules evaluated on event payload.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Provider needs different event names	eventMapping	Translates Selwise names to provider schema.
External data layer uses custom names	reverseEventMapping	Normalizes back to canonical Selwise events.
Forward only qualified purchase events	eventFilters with conditions	Prevents noisy or invalid downstream conversions.
Need baseline map quickly	GET /integrations/:provider/mappings	Default map reference from provider implementation.
Need behavioral validation	POST /integrations/:provider/test + logs	Verifies mapping/filter impact in practice.

Common Errors and Fixes

Mapped events not appearing downstream

Cause: eventFilters blocking events or mapping key mismatch.

Fix: Verify canonical source event keys and filter conditions.

Reverse mapping has no effect

Cause: External event names do not match keys exactly.

Fix: Use exact external event names with case-accurate keys.

Category Analytics shows `unknown` category rows

Cause: `category_view` is mapped but category identifier is missing in payload.

Fix: Send `entityId` or `metadata.categoryPath` (and optionally `metadata.categoryName`) for mapped category events.

Unexpected provider event names

Cause: Conflicting custom mapping and defaults.

Fix: Audit full map and remove accidental overrides.

Filter conditions never pass

Cause: Condition field path not aligned with payload shape.

Fix: Inspect payload in logs and adjust field references.

Production Checklist

• Canonical event keys are used consistently in mapping definitions.Required
• Reverse mapping table is documented for external data-layer consumers.Required
• Filter conditions are tested with representative event payloads.Required
• Provider mapping defaults are reviewed before custom overrides.Required
• Post-change validation includes provider test plus delivery logs.Required

Next Steps

• GA4
• Meta
• Operations