> Part of the walkerOS documentation. Project overview and full index: # mParticle [Server](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/mparticle) [Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/mparticle)[ ](https://www.npmjs.com/package/@walkeros/server-destination-mparticle) [Package](https://www.npmjs.com/package/@walkeros/server-destination-mparticle) Beta Server-side event delivery to [mParticle](https://www.mparticle.com/) 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[​](#installation "Direct link to 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](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md) ## Configuration[​](#configuration "Direct link to Configuration") This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see [destination configuration](https://www.walkeros.io/docs/destinations.md#configuration). Package-specific fields live under `config.settings` and are listed below. ## Settings[​](#settings "Direct link to 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` | 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` | 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[​](#mapping "Direct link to Mapping") Per-event rules under `config.mapping`. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md). | Property | Type | Description | More | | ----------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---- | | `eventType` | `'custom_event' \| 'screen_view'` | Per-event mParticle event type. Default: 'custom\_event'. | | | `customEventType` | `'navigation' \| 'location' \| 's` | 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` | 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[​](#identities-and-attributes "Direct link to 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.