Integration Configuration

Each integration has a configuration that defines how incoming Datafly events are transformed into the vendor’s API format. This page documents the configuration structure used by the Visual Builder.

Configuration Structure

An integration configuration has four main sections:

version: 2
delivery_mode: server_side
parameters:
  api_key: your_api_key
  measurement_id: G-XXXXXXXXXX
 
global:
  mappings: []
  enrichments: []
  transforms: []
 
defaults:
  action: drop
  mappings: []
 
events:
  Page Viewed:
    vendor_event_name: page_view
    enabled: true
    mappings: []
    enrichments: []
    transforms: []

Sections

Connection Parameters

Connection parameters hold vendor credentials and configuration (API keys, measurement IDs, pixel IDs, endpoints). These are stored securely and injected at delivery time — they do not appear in the event payload.

parameters:
  api_key: c247c9566fbbc983a9056b95f8a81d4f
  api_endpoint: https://api2.amplitude.com/2/httpapi

Global Parameters

Fields placed at the payload root level, outside the event wrapper. These are applied to every event sent to this integration, regardless of event type.

Use for fields that the vendor API expects at the top level of the request body: user identifiers, timestamps, consent signals, and authentication-adjacent data.

global:
  mappings:
    - source: vendor_ids.ga_client_id
      target: client_id
    - source: user_id
      target: user_id
    - source: timestamp
      target: timestamp_micros
      transform: date_format
      format: epoch_micros
    - source: context.consent.ad_user_data
      target: consent.ad_user_data
      value_map:
        '*': DENIED
        'true': GRANTED
        'false': DENIED

Example output — global fields appear at the root:

{
  "client_id": "1234567890.1740000000",
  "user_id": "user_98765",
  "timestamp_micros": 1774126074465000,
  "consent": { "ad_user_data": "GRANTED" },
  "events": [{ "name": "page_view", "params": { ... } }]
}

Global Event Parameters

Fields included inside every event object. These are applied to every event but are placed inside the event wrapper, not at the payload root.

Use for fields like device ID, IP address, user agent, session ID, and other context that every event needs but that the vendor API expects inside the event object.

defaults:
  action: drop
  mappings:
    - source: user_id
      target: user_id
    - source: anonymous_id
      target: device_id
    - source: context.ip
      target: ip
    - source: context.user_agent
      target: user_agent
    - source: context.locale
      target: language
    - source: context.session.id
      target: session_id
    - source: ''
      target: platform
      default_value: Web

Example output — global event parameters appear inside each event:

{
  "api_key": "...",
  "events": [{
    "event_type": "Page Viewed",
    "user_id": "user_98765",
    "device_id": "3ea581c3-be0b-41a3-a663-e7a2c1ff7be6",
    "ip": "90.250.8.149",
    "user_agent": "Mozilla/5.0 ...",
    "language": "en-GB",
    "session_id": 1774135428374,
    "platform": "Web",
    "event_properties": { ... }
  }]
}

Not all integrations need Global Event Parameters. Most vendor APIs (GA4, Meta, TikTok, Pinterest) expect common fields at the payload root, so only Global Parameters are needed. Amplitude is a notable exception — it requires identity and context fields inside each event object.

Event Specific Parameters

Fields specific to each event type. Each event mapping defines the vendor event name and the field mappings for that event.

events:
  Page Viewed:
    vendor_event_name: page_view
    enabled: true
    mappings:
      - source: context.page.url
        target: page_location
      - source: context.page.title
        target: page_title
      - source: context.page.referrer
        target: page_referrer
  Order Completed:
    vendor_event_name: purchase
    enabled: true
    mappings:
      - source: properties.order_id
        target: transaction_id
      - source: properties.revenue
        target: value
      - source: properties.currency
        target: currency

Unmatched Events

Controls what happens when an incoming event doesn’t match any configured event mapping:

Action	Description
Drop	Discard the event (recommended for most integrations)
Pass through	Forward the event with its original field names

Field Mapping Options

Each field mapping supports several options:

Basic Mapping

Map a source field to a target field:

- source: properties.revenue
  target: value

Static Value

Set a fixed value (leave source empty):

- source: ''
  target: platform
  default_value: Web

Transform

Apply a transformation to the mapped value:

- source: $traits.email
  target: user_data.sha256_email_address
  transform: sha256

Available transforms: lowercase, uppercase, trim, sha256, md5, base64_encode, to_string, to_number, date_format.

Value Map

Map specific input values to output values:

- source: context.consent.ad_user_data
  target: consent.ad_user_data
  value_map:
    '*': DENIED
    'true': GRANTED
    'false': DENIED

The * key sets the default value when no other key matches.

Date Format

Convert timestamps to specific formats:

- source: timestamp
  target: timestamp_micros
  transform: date_format
  format: epoch_micros

Available formats: epoch_seconds, epoch_millis, epoch_micros, iso8601.

Field Hierarchy

Target field paths use dot notation to create nested objects:

Target	Result
`client_id`	`{ "client_id": "..." }`
`user_data.email`	`{ "user_data": { "email": "..." } }`
`consent.ad_user_data`	`{ "consent": { "ad_user_data": "..." } }`
`items[].item_id`	`{ "items": [{ "item_id": "..." }] }`
`event_properties.page_url`	`{ "event_properties": { "page_url": "..." } }`

Blueprints

Blueprints are pre-built configurations for specific vendors and verticals. When you create a new integration, you can select a blueprint to pre-populate the configuration with recommended field mappings.

Blueprints include:

Global parameters for the vendor’s required root-level fields
Global event parameters (if the vendor requires them)
Event mappings for common events in your vertical (retail, SaaS, media, travel)
Recommended transforms (SHA-256 hashing for PII, consent value mapping)

After applying a blueprint, you can customise any field mapping, add new events, or modify the configuration to match your specific requirements.

Pipeline Engine Pipeline Configuration (V1)