mParticle
Server-side event delivery to mParticle via the HTTP Events API. Each event is sent as its own batch, one POST per event, to the regional mParticle pod using HTTP Basic auth (apiKey / apiSecret). Supports user identities, user attributes, consent state, and environment targeting.
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/collector @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: process.env.MPARTICLE_API_KEY,
apiSecret: process.env.MPARTICLE_API_SECRET,
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "server"
},
"destinations": {
"mparticle": {
"package": "@walkeros/server-destination-mparticle",
"config": {
"settings": {
"apiKey": "$secret.MPARTICLE_API_KEY",
"apiSecret": "$secret.MPARTICLE_API_SECRET"
}
}
}
}
}
}
}The apiKey and apiSecret come from an mParticle input feed (Setup, Inputs, Feeds, Custom Feed). Requests go to https://s2s.mparticle.com/v2/events for the default pod us1 and to https://s2s.{pod}.mparticle.com/v2/events for the other pods.
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 | More |
|---|---|---|---|
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. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
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. The user identities come from settings.userIdentities (customer_id: user.id).
{
"name": "order complete",
"data": {
"id": "ORD-300",
"value": 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"
}
}{
"settings": {
"eventType": "commerce_event",
"commerce": {
"map": {
"currency_code": "data.currency",
"product_action": {
"map": {
"action": {
"value": "purchase"
},
"transaction_id": "data.id",
"total_amount": "data.value"
}
}
}
}
}
}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 settings.userIdentities mapping customer_id to user.id, the batch carries the user id.
{
"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"
}
}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 settings.userIdentities (customer_id: user.id, email: user.email).
{
"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"
}
}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. The user identities come from settings.userIdentities (customer_id: user.id).
{
"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"
}
}{
"settings": {
"eventType": "screen_view"
}
}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"
}
})Consent
The quickstart sets no config.consent, so mParticle receives every event, whatever consent the event carries. To send only events with consent, add consent: { marketing: true } to config, next to settings (with several keys listed, one granted key is enough). An event without that consent is skipped or queued, depending on the collector's consentDenied. Server flows built by the CLI skip it and count it in skipped. With startFlow it waits in the destination's queue by default: a later event that carries consent does not release it, and only a walker consent command does, which then sends the waiting events of every user at once. Pass consentDenied: 'skip' to startFlow to skip such events instead (see Gate a destination with consent and consent-denied events on a server).
Identities and attributes
userIdentities: map walkerOS event fields to mParticle identity types (customer_id,email,other, etc.). Without it the batch carries no user identities.userAttributes: resolved from each event and placed on the batch'suser_attributesobject.consent: a fixedconsent_stateobject, sent unchanged on every batch whatever the event's walkerOS consent says.sourceRequestId: defaults toevent.idif unset; used by mParticle for deduplication.
Event properties reach mParticle as custom_attributes only through a mapping rule's data or include, or the destination's config.data or config.include. Without any of them, mParticle receives the event name, its timestamp and its id.
Delivery failures
A non-2xx answer from mParticle fails the push with transport and that status, logged at ERROR; a 429 and a 5xx are retryable, other 4xx answers are not. A missing apiKey or apiSecret fails with config.