Skip to main content
Ask your AI

mParticle

Server Source code Package Beta

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.

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/collector @walkeros/server-destination-mparticle
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,
        },
      },
    },
  },
});

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​

PropertyTypeDescriptionMore
apiKey*stringmParticle input feed API key from the mParticle dashboard (Setup > Inputs > Feeds).
apiSecret*stringmParticle 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'.
userIdentitiesRecord<string, any>Mapping that resolves to user_identities per batch. Keys are mParticle identity types (like customer_id, email); values are walkerOS mapping values.
userAttributesanyMapping value that resolves to the user_attributes object placed on the batch.
consentRecord<string, any>Static consent_state envelope forwarded verbatim on the batch. See mParticle consent_state docs.
ipanyMapping value resolving to the client IP for the batch.
sourceRequestIdanyMapping 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.

PropertyTypeDescriptionMore
eventTypePer-event mParticle event type. Default: 'custom_event'.
customEventTypeCustom event type category for 'custom_event'. Default: 'other'.
commerceanyMapping value resolving to the commerce fields (product_action, currency_code, products, ...) for a commerce_event.
userIdentitiesRecord<string, any>Per-event override mapping for user_identities. Merged over settings.userIdentities.
userAttributesanyPer-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).

Event
{
  "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"
  }
}
Mapping
{
  "settings": {
    "eventType": "commerce_event",
    "commerce": {
      "map": {
        "currency_code": "data.currency",
        "product_action": {
          "map": {
            "action": {
              "value": "purchase"
            },
            "transaction_id": "data.id",
            "total_amount": "data.value"
          }
        }
      }
    }
  }
}
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 settings.userIdentities mapping customer_id to user.id, the batch carries the user id.

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 settings.userIdentities (customer_id: user.id, email: user.email).

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. The user identities come from settings.userIdentities (customer_id: user.id).

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 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's user_attributes object.
  • consent: a fixed consent_state object, sent unchanged on every batch whatever the event's walkerOS consent says.
  • sourceRequestId: defaults to event.id if 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.

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