How to Integrate mParticle with Your Headless CMS

What is mParticle?

mParticle is a customer data platform that collects event, identity, consent, and audience data, then routes it to analytics, marketing, warehouse, and personalization destinations. Product, growth, data, and lifecycle teams use it to standardize customer events across web, mobile, server-side systems, and third-party tools. Its core value is data control: define what gets collected, validate it with data plans, and send it to the right destinations without rewriting every app integration.

Why integrate mParticle with a headless CMS?

Content teams publish campaigns, articles, product stories, landing pages, and offer modules every day. Analytics teams need to know which of those assets actually affect signups, purchases, retention, or churn. If your content system and mParticle don’t talk to each other, you usually end up with brittle naming rules, spreadsheet mappings, or frontend-only tracking that misses context like author, topic, campaign, product line, locale, and release ID.,A headless CMS setup works best for mParticle when the content is structured, not trapped inside page HTML. With Sanity’s AI Content Operating System, content lives as typed JSON in the Content Lake, so a published article can include stable fields like contentId, audienceSegment, campaignCode, productSku, locale, and experimentKey. GROQ can select exactly those fields, and webhooks can fire when a document is published, updated, or deleted.,The alternative is slower and messier. Someone copies campaign metadata into mParticle by hand, engineers scrape rendered pages for IDs, or analytics events ship with only a URL and page title. That works for a few pages. It breaks when you have 12 locales, 40 campaign variants, mobile apps, and a lifecycle team that needs audience data within minutes of publish.

Architecture overview

A typical Sanity and mParticle integration has two event paths. First, content events: an editor publishes or updates a document in Sanity Studio, the change is committed to the Content Lake, and a Sanity webhook or Function runs on that mutation. The webhook can use a GROQ filter such as _type in ["article", "campaign", "productPage"] and a projection that sends only _id, _type, slug, and revision data. The handler then uses @sanity/client to fetch the full analytics payload with GROQ, including referenced fields like category, product, campaign, author, locale, and experiment metadata. From there, the handler calls mParticle’s Events API at https://s2s.mparticle.com/v2/events with HTTP Basic Auth using the server-to-server input key and secret. The payload is sent as a custom_event such as Content Published or Content Updated, with custom_attributes mapped from Sanity fields. Second, user behavior events: your site or app renders the same Sanity content and logs Content Viewed, CTA Clicked, or Offer Accepted through the mParticle Web SDK, iOS SDK, Android SDK, or server-side Events API. Because both paths use the same content_id, campaign_code, and locale, mParticle can connect publishing activity to user behavior, audiences, data warehouse exports, and downstream destinations.

Common use cases

Step-by-step integration

1. 1

   Set up mParticle inputs

   Create or open your mParticle workspace, add a Web, iOS, Android, or Custom Feed input, and copy the API key and secret for server-side Events API calls. If your team uses Data Planning, define events such as Content Published, Content Updated, Content Viewed, and CTA Clicked with required attributes like content_id, content_type, locale, and campaign_code.

2. 2

   Model analytics fields in Sanity Studio

   Add explicit fields to your schemas instead of relying on page titles. For an article, campaign, or product page, include fields such as analyticsName, campaignCode, audienceTags, experimentKey, variantId, locale, topic, and product references. Keep IDs stable, because mParticle events need consistent identifiers across web, mobile, and warehouse destinations.

3. 3

   Create a publish trigger

   Use a Sanity webhook or Function that runs only for published content. A common webhook filter is _type in ["article", "campaign", "productPage"] && !(_id in path("drafts.**")). Send a small projection from the webhook, then fetch the full document inside your handler with GROQ.

4. 4

   Call the mParticle Events API

   In your webhook handler, use @sanity/client to fetch the document and POST a custom_event batch to https://s2s.mparticle.com/v2/events. Use the server-to-server key and secret with Basic Auth, keep those values in environment variables, and include environment as production or development.

5. 5

   Add frontend tracking

   Install the mParticle SDK in your site or app, then log user events with the same Sanity identifiers. For example, when a Sanity-powered page renders, send Content Viewed with content_id, slug, campaign_code, locale, and variant_id.

6. 6

   Test the full path

   Publish a test document in Sanity Studio, confirm the webhook or Function runs, and inspect the event in mParticle Live Stream. Then load the frontend page and verify that Content Viewed uses the same content_id as the publish event.

How Sanity + mParticle works

CMS approaches to mParticle

Keep building

Explore related integrations to complete your content stack.