mParticle CDP extension

Customer data Unbundled: Extension

Issues

Git

Latest

1.1.1

Compatible with Magnolia 6.2.

The mParticle Integration module integrates Magnolia with mParticle (a customer data platform) to facilitate personalization.

You need the following mParticle credentials. Please contact mParticle to obtain this information.

platform_key for Web SDK integration
client_id and client_secret for authentication
accountId, orgId, and workspaceId for the Audiences (Platform API) and Profile API

For more details:

Features

Store audiences from mParticle in the mParticle Audiences content app.
Fetch mParticle audiences instantly with the Sync Audiences action.

Use the Scheduler module to fetch mParticle audiences with audiencesSyncJob (only run on author instances).

config.yaml

jobs:
 audiencesSyncJob:
   catalog: mparticle
   command: audiencesSync
   cron: '0 0 1 * * ?'
   description: 'Sync Audiences from mParticle - Every day at 1am'
   enabled: false
   params:
     cleanInActiveAudiences: 'true'
     disableNotification: 'true'

Use the mpAudiences trait to display and configure audiences from the mParticle audiences app.

Templating functions

You can use the mpfn templating function with the following methods.

Get Platform Key ${mpfn.getPlatformKey()}
Get User Profile Path ${mpfn.getUserProfilePath()}

REST endpoints

There are several REST endpoints you can use to fetch profiles and audiences.

You must add the mparticle-profile-rest-role (for anonymous) and mparticle-rest-role (for administrator) role for the user calling REST.

Get mParticle profile

POST .rest/mparticle/profile

Request body:

{
    "mpid": "<mpid>",
    "userprofile_path": "<OrgId>/<AccountId>/<workspaceId>"
}

Get all audiences

POST .rest/mparticle/get-audiences

Request body:

{
    "accountId": "<accountId>" (1)
}

1	This is your mParticle `accountId`.

Delete an audience

POST .rest/mparticle/delete-audience

Request body:

{
    "audienceId": "<audienceId>" (1)
}

1	This is your mParticle `audienceId`.

Get all audiences by workspace

POST .rest/mparticle/get-audiences-workspace

Request body:

{
    "accountId": "<accountId>", (1)
    "workspaceId": "<workspaceId>" (2)
}

1	This is your mParticle `accountId`.
2	This is your mParticle `workspaceId`.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.cdp</groupId>
  <artifactId>magnolia-cdp-mparticle</artifactId>
  <version>1.1.1</version>
</dependency>

For common use with a DX-Core bundle, you need to build a jar file and then copy it to lib folder.

mv cdp-mparticle-1.1.1.jar tomcatDir/webapp/ROOT/WEB-INF/lib/

Configuration

Add and publish client_secret to the Passwords app for security best practices and copy the Password ID for later use.

Update client_id and client_secret for mParticle authentication via decoration in <your-light-module>/decorations/cdp-mparticle/restClients/mparticle-authentication.yaml file.

mparticle-authentication.yaml

baseUrl: https://sso.auth.mparticle.com
cacheConfiguration:
  expireIn: 60
timeoutConfiguration:
  readTimeout: 5
  fallbackToCache: true
restCalls:
  authenticate:
    method: POST
    path: '/oauth/token'
    # https://docs.magnolia-cms.com/product-docs/6.2/modules/list-of-modules/rest-client-module/#_hiding_sensitive_information
    body: '{"client_id":"<client_id>}","client_secret":"{@password:<The Password ID in Password App>}","audience":"https://api.mparticle.com","grant_type":"client_credentials"}'

Update platform_key, accountId, orgId ,and workspaceId via decoration in <your-light-module>/decorations/cdp-mparticle/config.yaml file.
config.yaml
```
orgId: <mParticle org Id>
accountId: <mParticle Account Id>
workspaceId: <mParticle Workspace Id>
platformKey: <mParticle Platform Key>
```
Change platform_key in a JavaScript snippet for frontend integration by following mParticle SDK Initialization
```
${mpfn.getPlatformKey()}
```

Enable Audiences Sync Job and its scheduler time by decoration in <your-light-module>/decorations/scheduler/config.yaml file.

config.yaml

jobs:
 audiencesSyncJob:
   catalog: mparticle
   command: audiencesSync
   cron: '0 0 1 * * ?'
   description: 'Sync Audiences from mParticle - Every day at 1am'
   enabled: false
   params:
     cleanInActiveAudiences: 'true'
     disableNotification: 'true'

Usage

Variant components

Use Component Personalization to set up a new variant component on your page. You can use Segment or Trait configuration.

Frontend integration

Perform frontend integration using the mParticle Web SDK.

See cdp-mparticle/templates in the Resources app for a sample frontend integration.

Parse mParticle audiences

Get User audiences from mParticle and parse the list into a string using "|" as a delimiter and save it to the mpAudiences cookie.

mpAudiences: 53730|53731|53730

Example

<script>
    window.addEventListener('load', function() {
        var user = mParticle.Identity.getCurrentUser();
        const data = {
            "mpid": user.getMPID(),
            "userprofile_path": "${mpfn.getUserProfilePath()}"
        };
        console.log('mpid header', user.getMPID());
        Cookies.remove('mpAudiences');
        $.ajax({
            type: "POST",
            data: JSON.stringify(data),
            url: "${ctx.contextPath}/.rest/mparticle/profile",
            headers: {
                "Content-Type": "application/json",
            },
            success: function (data) {
                debugger;
                if (data.audience_memberships && data.audience_memberships.length > 0) {
                    console.log("audience_memberships form profile", data.audience_memberships);
                    Cookies.set('mpAudiences', data.audience_memberships.map(audience => audience.audience_id).join('|'), {
                        expires: 365
                    });
                    console.log("[Header] mpAudiences from cookies", Cookies.get('mpAudiences'));
                }
            },
            dataType: "json"
        });
    });
    window.addEventListener('load', function() {
        const url = new URL(window.location.toString());
        const pageTitle = url.pathname.replace("${ctx.contextPath}", "");
        mParticle.logPageView(
            pageTitle,
            {page: window.location.toString()},
            // if you're using Google Analytics to track page views
            {"Google.Page": window.location.pathname.toString(),
                "Google.Title": "FW from mParticle - ${content.windowTitle!content.title!}"
            }
        );
    });
</script>

mParticle CDP extension

Features

Templating functions

REST endpoints

Get mParticle profile

Get all audiences

Delete an audience

Get all audiences by workspace

Installing with Maven

Configuration

Usage

Variant components

Frontend integration

Parse mParticle audiences

Location

Main doc sections