Mapping

The Mapping.Config stores all individual Mapping.EventConfig configurations for each entity-action event. The getMappingEvent function returns the matching event mapping while the getMappingValue is used to resolve a Mapping.Value settings for a specific property to return an actual value. The custom property is used by each destination individually.

interface Config<CustomEvent = unknown> {
  [entity: string]:
    | Record<string, EventConfig<CustomEvent> | Array<EventConfig<CustomEvent>>>
    | undefined;
}

const mapping: Config = {
  entity: {
    action: { name: 'entity_action' }, // Explicit EventConfig
    '*': {}, // Generic EventConfig for all entity entities
  },
  order: {
    complete: [
      {
        // EventConfig only for production
        condition: (event: WalkerOS.PartialEvent) =>
          event.globals?.env === 'prod',
        ignore: true,
      },
      { name: 'purchase' }, // Fallback EventConfig
    ],
  },
  '*': { '*': { ignore: true } },
};

getMappingEvent

getMappingEvent(event: string, mapping?: Mapping.Config<unknown>): EventMapping returns the matching eventMapping configuration and the used mappingKey for the given entity-action event name. If no mapping is found, it will return an empty object. An explicit key is favored over an asterisk * key. If available a condition will be checked to determine if the EventConfig applies. It's used by the sources.

interface EventMapping {
  eventMapping?: Event;
  mappingKey?: string;
}

getMappingEvent({ event: 'entity action' }, mapping);
// { eventMapping: { name: 'entity_action' }, mappingKey: 'entity action' }

getMappingEvent({ event: 'entity action' }, mapping);
// { eventMapping: { }, mappingKey: 'entity action' }

getMappingEvent({ event: 'order complete' }, mapping);
// { eventMapping: { name: 'purchase' }, mappingKey: 'order complete' }

getMappingEvent({ event: 'order complete', globals: { env: 'prod' } }, mapping);
// { eventMapping: { ignore: true, condition: Function }, mappingKey: 'order complete' }

getMappingEvent({ event: 'page view' }, mapping);
// { eventMapping: { ignore: true }, mappingKey: 'page view' }

getMappingValue

getMappingValue(event: WalkerOS.Event, mapping: Mapping.Value, options?: Mapping.Options): WalkerOS.Property | undefined primarily used by destinations to process values from the original event. This offers flexibility to configure individual tagging setups to standard fields of the destination.

type Value = ValueType | Array<ValueType>;
type ValueType = string | ValueConfig;

interface ValueConfig {
  condition?: Condition;
  consent?: WalkerOS.Consent;
  fn?: Fn;
  key?: string;
  loop?: Loop;
  map?: Map;
  validate?: Validate;
  value?: WalkerOS.PropertyType;
}

getMappingValue({ foo: 'bar' }, 'foo');
// bar

// key
getMappingValue({ foo: 'bar' }, { key: 'foo' });
// bar

// value
getMappingValue({}, { value: 'foo' });
// foo

// array notation
getMappingValue({ arr: ['foo', 'bar'] }, 'arr.0');
// foo

// fn
getMappingValue({ foo: 'bar' }, { fn: (obj) => obj.foo.toUpperCase() });
// BAR

// map
getMappingValue(
  { foo: 'bar' },
  {
    map: {
      foo: 'foo',
      bar: { value: 'baz' },
      obj: { map: { recursive: { value: true } } },
    },
  },
);
// { foo: 'bar', bar: 'baz', obj: { recursive: true } }

// loop
getMappingValue(
  { arr: [{ id: 'foo' }, { id: 'bar' }] },
  { loop: ['arr', { key: 'id' }] },
);
// ['foo', 'bar']

// condition
getMappingValue({ foo: 'bar' }, { key: 'foo', validate: (v) => v === 'bar' });
// bar

// consent
getMappingValue(
  { name: 'foo', consent: { functional: true } }, // event with consent state
  { key: 'name', consent: { marketing: true } }, // required consent
  { instance }, // instance with consent state
);
// undefined (no marketing required consent)

First the condition is checked to determine if the ValueConfig should be used. Second, the consent state gets checked if an instance is provided. If no required consent is given, no value will be returned. If a fn is provided, it will be called to define the value, otherwise the key or initial string value will be used with byPath. The current value will be check using the validate function and set to undefined if it fails. Finally, the value will be cast to match the WalkerOS.Property type. An empty ValueType will return undefined.

info

If you need professional support with your walkerOS implementation, check out our services.