# mParticle Integration

> This guide shows how to activate customer data from mParticle Integration for personalization.

Source: https://docs.uniform.app/docs/integrations/data/mparticle

Integrating mParticle with Uniform enables edge personalization with customer data coming from mParticle, delivering exceptional performance and Core Web Vitals.

### Prerequisites

- An account for mParticle with access to the Web SDK
- A Uniform account with access
- An app set up with the Uniform SDK.

## Step 1: Uniform Project Setup

### Step 1.1: Add Quirks for mParticle User Attributes

1. In your Uniform project, navigate to Optimization > Personalization > Quirks.
2. Click Create a Quirk and set up quirks corresponding to the user attributes you want to use from mParticle.
3. Create signals based on these quirks in the Signals section.
4. Click **Publish** to make this configuration available for your application.

### Step 1.2: Add Personalization to a Component in Canvas

1. Go to Experience > Compositions and select a composition.
2. Choose a component and click Personalize This in the Context tab.
3. Add criteria based on the signals you created.
4. Author the personalized content and save the composition.

## Step 2: Connect Your App with mParticle

### Step 2.1: Initialize mParticle SDK in Your App

This step is not specific to Uniform. Before you can use mParticle in your app, you need to initialize the SDK.

> **Front-end framework:**
>
> The example below are for any React-based app. We will use Next.js specifically in this example.

Add the following code to your app's entry point (e.g., `\_app.tsx` for Next.js):

```javascript
import mParticle from "@mparticle/web-sdk";

if (typeof window \!== "undefined") {
  mParticle.init(process.env.NEXT_PUBLIC_MPARTICLE_API_KEY as string, {});
}
```

### Step 2.2: Enable mParticle Analytics

This part is responsible for sending personalization and test events to mParticle. This is not strictly required for personalization, however if you want to enrich your visitor data with more context, this is a good place to do it.

Create a file named `MParticleContextPlugin.ts` with the following content:

```javascript
import {
 ContextPlugin,
 PersonalizationEvent,
 TestEvent,
} from "@uniformdev/context";
import mParticle from "@mparticle/web-sdk";

export const enableMParticleAnalytics = (options?: { emitAll?: boolean; }): ContextPlugin => {
 const { emitAll } = options || {};

  return {
    init: (context) => {
    if (typeof window === "undefined") {
    return () => {};
    }

     // Handle emitting personalization results to mParticle
     const onPersonalizationResult = (result: PersonalizationEvent) => {
       // Only emit analytics events when personalization changes (not on every re-render)
       if (!emitAll && !result.changed) {
         return;
       }

       mParticle.logEvent("Uniform Personalization", mParticle.EventType.Other,
         {
           personalizationName: result.name,
           variantIds: result.variantIds
             .map((variant) => variant.id)
             .join(", "),
           isControlGroup: result.control,
         }
       );
     };

     // Handle emitting test results to mParticle
     const onTestResult = (result: TestEvent) => {
       // Only emit analytics events when a variant is assigned (not on every re-render)
       if (!emitAll && !result.variantAssigned) {
         return;
       }

       mParticle.logEvent("Uniform Test", mParticle.EventType.Other, {
         testName: result.name,
         testVariantId: result.variantId,
         testVariantAssigned: result.variantAssigned,
       });
     };

     context.events.on("personalizationResult", onPersonalizationResult);
     context.events.on("testResult", onTestResult);

     return () => {
       context.events.off("personalizationResult", onPersonalizationResult);
       context.events.off("testResult", onTestResult);
     };
    },
  };
};

```

### Step 2.3: Sync mParticle User Attributes with Uniform Context

This component is central to the personalization area. The React component below is responsible for fetching the user's attributes from mParticle and updating the Uniform context with these attributes as quirks.

You can also perform this action from the server-side or from an edge function / middleware / worker if you wish.

Create a component named `TrackerScoreSync.tsx` with the following content:

```javascript
import { useEffect } from "react";
import { useUniformContext } from "@uniformdev/context-react";
import mParticle from "@mparticle/web-sdk";

const TrackerScoreSync = () => {
  const { context } = useUniformContext();

  useEffect(() => {
    const fetchTraits = async () => {

      // Ensure this runs only on the client side
      if (typeof window === "undefined") return;

      // Wait for mParticle to be ready before interacting with the SDK
      mParticle.ready(() => {
        const currentUser = mParticle.Identity.getCurrentUser();

        // If no current user is available, handle identification logic
        if (!currentUser) {
         mParticle.Identity.identify(
           {
             userIdentities: {
               // Replace with your actual mParticle user identification logic
               email: "user@example.com",
               customerid: "12345",
             },
           },
           (result) => {
             if (result.getUser()) {
               console.log("User identity set successfully");
               // Update user context after identifying the new user
               updateUserContext(result.getUser());
             } else {
               console.error("Error setting user identity", result.getPreviousUser());
             }
           }
         );
       } else {
         // If user exists, fetch their attributes and update the context
         updateUserContext(currentUser);
       }
     });
  };

  // Function to update the Uniform context with user attributes from mParticle
    const updateUserContext \= (currentUser: mParticle.User) => {
    const userAttributes \= currentUser.getAllUserAttributes();
    if (!userAttributes || Object.keys(userAttributes).length === 0) {
    console.warn("No user attributes found");
    return;
  }

    // Format user attributes for use in Uniform context
    const formattedAttributes = Object.keys(userAttributes).reduce(
       (acc, key) => {
         const value = userAttributes[key];
         acc[key] = Array.isArray(value) ? value.join(", ") : value?.toString() ?? "";
         return acc;
       },
       {} as { \[key: string\]: string }
     );

     console.log("User attributes fetched", formattedAttributes);

     // Update the Uniform context with the fetched user attributes as quirks
     context.update({
       quirks: formattedAttributes,
     });

  };

  // Fetch user traits and update context on component mount
  fetchTraits();
  }, [context]);

  return null;
};

export default TrackerScoreSync;
```

## Step 3: Implement the Integration

1. Add the `TrackerScoreSync` component to your app's main component or layout.
2. Use the `enableMParticleAnalytics` function when initializing your Uniform Context.

## Step 4: (Optional) Activate Edge Personalization Mode

To enable edge-side personalization:

1. Choose a CDN that supports programmable edge runtime.
2. Follow the CDN-specific instructions to set up edge functions or workers:

- [Akamai](https://docs.uniform.app/docs/integrations/cdn/akamai/akamai-edge-personalization)
- [Cloudflare](https://docs.uniform.app/docs/integrations/cdn/cloudflare/cloudflare-edge-personalization)
- [Netlify](https://docs.uniform.app/docs/integrations/cdn/netlify/netlify-edge-personalization)
- [Vercel](https://docs.uniform.app/docs/integrations/cdn/vercel/add-edge-middleware)

Following these steps, you'll have successfully integrated mParticle with Uniform, enabling powerful personalization capabilities driven by mParticle's user data.