mParticle

Server Source code Package Beta

Server-side event delivery to mParticle via the HTTP Events API. Events are packaged into batches and POSTed to the regional mParticle pod using HTTP Basic auth (apiKey / apiSecret). Supports user identities, user attributes, consent state, and environment targeting.

Where this fits

mParticle is a server destination in the walkerOS flow:

Receives events server-side from the collector and forwards them to mParticle's input feed for fan-out to downstream destinations.

Installation

npm install @walkeros/server-destination-mparticle

Integrated
Bundled

import { startFlow } from '@walkeros/collector';
import { destinationMParticle } from '@walkeros/server-destination-mparticle';

await startFlow({
destinations: {
  mparticle: {
    code: destinationMParticle,
    config: {
      settings: {
        apiKey: 'YOUR_MPARTICLE_API_KEY',
        apiSecret: 'YOUR_MPARTICLE_API_SECRET',
        pod: 'us1',
        environment: 'production',
      },
    },
  },
},
});

Add to your flow.json destinations:

"destinations": {
"mparticle": {
  "package": "@walkeros/server-destination-mparticle",
  "config": {
    "settings": {
      "apiKey": "YOUR_MPARTICLE_API_KEY",
      "apiSecret": "YOUR_MPARTICLE_API_SECRET",
      "pod": "us1",
      "environment": "production"
    }
  }
}
}

See bundled mode setup | CLI reference

Configuration

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings

Property	Type	Description
`apiKey*`	`string`	mParticle input feed API key from the mParticle dashboard (Setup > Inputs > Feeds).
`apiSecret*`	`string`	mParticle input feed API secret paired with apiKey. Used for HTTP Basic auth.
`pod`	`'us1' \| 'us2' \| 'eu1' \| 'au1'`	mParticle data pod selecting the regional endpoint. Default: 'us1'.
`environment`	`'production' \| 'development'`	Environment the batch targets. Default: 'production'.
`userIdentities`	`Record<string, any>`	Mapping that resolves to user_identities per batch. Keys are mParticle identity types (like customer_id, email); values are walkerOS mapping values.
`userAttributes`	`any`	Mapping value that resolves to the user_attributes object placed on the batch.
`consent`	`Record<string, any>`	Static consent_state envelope forwarded verbatim on the batch. See mParticle consent_state docs.
`ip`	`any`	Mapping value resolving to the client IP for the batch.
`sourceRequestId`	`any`	Mapping value resolving to the source_request_id for the batch. Falls back to event.id when unset.

* Required fields

Mapping

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Property	Type	Description
`eventType`		Per-event mParticle event type. Default: 'custom_event'.
`customEventType`		Custom event type category for 'custom_event'. Default: 'other'.
`commerce`	`any`	Mapping value resolving to the commerce fields (product_action, currency_code, products, ...) for a commerce_event.
`userIdentities`	`Record<string, any>`	Per-event override mapping for user_identities. Merged over settings.userIdentities.
`userAttributes`	`any`	Per-event override mapping for user_attributes.

Examples

Commerce purchase

A completed order becomes an mParticle commerce_event with a purchase product_action block.

Event

{
  "name": "order complete",
  "data": {
    "id": "ORD-300",
    "total": 249.99,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "user-123"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000300000",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000300000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}

Mapping

{
  "settings": {
    "eventType": "commerce_event",
    "commerce": {
      "map": {
        "currency_code": "data.currency",
        "product_action": {
          "map": {
            "action": {
              "value": "purchase"
            },
            "transaction_id": "data.id",
            "total_amount": "data.total"
          }
        }
      }
    }
  }
}

Out

sendServer("https://s2s.mparticle.com/v2/events", "{\"events\":[{\"event_type\":\"commerce_event\",\"data\":{\"currency_code\":\"EUR\",\"product_action\":{\"action\":\"purchase\",\"transaction_id\":\"ORD-300\",\"total_amount\":249.99},\"timestamp_unixtime_ms\":1700000300000,\"source_message_id\":\"ev-1700000300000\"}}],\"environment\":\"production\",\"user_identities\":{\"customer_id\":\"user-123\"},\"source_request_id\":\"ev-1700000300000\"}", {
  "headers": {
    "Authorization": "Basic a2V5OnNlY3JldA==",
    "Content-Type": "application/json"
  }
})

Custom event

A walker event is sent to mParticle as a custom_event with user identities resolved from destination settings.

Event

{
  "name": "product view",
  "data": {
    "id": "SKU-A1",
    "name": "Shoe",
    "price": 129.99
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "user-123"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000100000",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000100000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}

Out

sendServer("https://s2s.mparticle.com/v2/events", "{\"events\":[{\"event_type\":\"custom_event\",\"data\":{\"event_name\":\"product view\",\"custom_event_type\":\"other\",\"timestamp_unixtime_ms\":1700000100000,\"source_message_id\":\"ev-1700000100000\"}}],\"environment\":\"production\",\"user_identities\":{\"customer_id\":\"user-123\"},\"source_request_id\":\"ev-1700000100000\"}", {
  "headers": {
    "Authorization": "Basic a2V5OnNlY3JldA==",
    "Content-Type": "application/json"
  }
})

User identities

A form submission sends a custom_event whose batch carries user_identities resolved from destination settings.

Event

{
  "name": "form submit",
  "data": {
    "type": "newsletter"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "user-123",
    "email": "user@example.com"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000400000",
  "trigger": "test",
  "entity": "form",
  "action": "submit",
  "timestamp": 1700000400000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}

Out

sendServer("https://s2s.mparticle.com/v2/events", "{\"events\":[{\"event_type\":\"custom_event\",\"data\":{\"event_name\":\"form submit\",\"custom_event_type\":\"other\",\"timestamp_unixtime_ms\":1700000400000,\"source_message_id\":\"ev-1700000400000\"}}],\"environment\":\"production\",\"user_identities\":{\"customer_id\":\"user-123\",\"email\":\"user@example.com\"},\"source_request_id\":\"ev-1700000400000\"}", {
  "headers": {
    "Authorization": "Basic a2V5OnNlY3JldA==",
    "Content-Type": "application/json"
  }
})

Screen view

A page view is mapped to an mParticle screen_view event with the event name as the screen name.

Event

{
  "name": "page view",
  "data": {
    "title": "Checkout",
    "path": "/checkout"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "user-123"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000200000",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000200000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "express",
    "platform": "server"
  }
}

Mapping

{
  "settings": {
    "eventType": "screen_view"
  }
}

Out

sendServer("https://s2s.mparticle.com/v2/events", "{\"events\":[{\"event_type\":\"screen_view\",\"data\":{\"screen_name\":\"page view\",\"timestamp_unixtime_ms\":1700000200000,\"source_message_id\":\"ev-1700000200000\"}}],\"environment\":\"production\",\"user_identities\":{\"customer_id\":\"user-123\"},\"source_request_id\":\"ev-1700000200000\"}", {
  "headers": {
    "Authorization": "Basic a2V5OnNlY3JldA==",
    "Content-Type": "application/json"
  }
})

The apiKey and apiSecret come from an mParticle input feed (Setup, Inputs, Feeds, Custom Feed). Each batch posts to https://s2s.{pod}.mparticle.com/v2/events using HTTP Basic auth.

Identities and attributes

userIdentities: map walkerOS event fields to mParticle identity types (customer_id, email, other, etc.).
userAttributes: resolved from each event and placed on the batch's user_attributes object.
consent: forwarded verbatim as consent_state on the batch.
sourceRequestId: defaults to event.id if unset; used by mParticle for deduplication.

💡 Need implementation support?

elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)

Installation​

Configuration​

Settings​

Mapping​

Examples

Commerce purchase

Custom event

User identities

Screen view

Identities and attributes​

Installation

Configuration

Settings

Mapping

Identities and attributes