mParticle CDP extension

Customer data Unbundled: Extension

Issues

CUSTDP

Git

Git

Latest

1.1.2

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:

From version 1.1.2, you should use the trait definition configuration. It’s also advised to disable the audienceDetector filter and the old trait named "mpAudiences".

Filter: config -> /server/filters/audienceDetector
Trait: /cdp-mparticle/traits/mpAudiences.yaml

Features

  • Store audiences from mParticle in the mParticle Audiences content app.

    mparticle contentapp icon

  • Fetch mParticle audiences instantly with the Sync Audiences action.

    mparticle contentapp

  • 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.

    mparticle audiences trait
    mparticle audiences trailt items

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.2</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.2.jar tomcatDir/webapp/ROOT/WEB-INF/lib/

Configuration

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

    mparticle client secret

  2. 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"}'

  3. 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>

  4. Change platform_key in a JavaScript snippet for frontend integration by following mParticle SDK Initialization

    ${mpfn.getPlatformKey()}

  5. 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'

Trait definition

Available with version 1.1.2+.

To enable personalization based on user data from mParticle, define traits in your Magnolia light module’s personalization configuration. Traits map mParticle user audiences to personalization rules.

The following examples define traits for Audiences based on Magnolia standard traits: cookieTrait or headerTrait, requestParameterTrait.

Place this trait definition in your light module under the traits directory. For example, if your light module is named my-cdp-module, create the file at:

<your-magnolia-project>/light-modules/my-cdp-module/traits/file-name.yaml

  • mpAudienceCookie

  • mp-audiences-header

  • mpAudiencesRequestParameter

<your-magnolia-project>/light-modules/my-cdp-module/traits/mpAudiencesCookie.yaml
name: mpAudiencesCookie (1)
$type: cookieTrait (2)
voterClass: info.magnolia.cdp.mparticle.personalization.traits.voter.NameAndMultiValueVoter
defaultRuleTrait: false
defaultPreviewTrait: false
ruleField:
  $type: comboBoxField
  name: value
  label: CDP mParticle Audience Cookie Trait
  datasource: &datasource (3)
    $type: jcrDatasource
    workspace: mparticle-audiences
    includeProperties: false
    allowedNodeTypes:
      - mgnl:mpAudience
    sortBy:
      jcrName: ascending
valueField:
  $type: comboBoxField
  label: CDP mParticle Audience Cookie Trait
  datasource: *datasource
traitStorageClass: info.magnolia.personalization.trait.storage.StorageAwareTraitCollector$RequestScopedTraitStorage (4)
1 The name identifies the trait in personalization rules.
2 The $type indicates the trait is populated from a cookie or request header or request parameter (e.g., ?mpAudiencesRequestParameter=<Audiences>).
3 List of Audiences from the mParticle Audiences content app.
4 The traitStorageClass stores the trait for the duration of the user’s request. This is ideal for temporary data like recent browsing activity.
<your-magnolia-project>/light-modules/my-cdp-module/traits/mp-audiences-header.yaml
name: mp-audiences-header (1)
$type: headerTrait (2)
voterClass: info.magnolia.cdp.mparticle.personalization.traits.voter.NameAndMultiValueVoter
defaultRuleTrait: false
defaultPreviewTrait: false
ruleField:
  $type: comboBoxField
  name: value
  label: CDP mParticle Audience Header Trait
  datasource: &datasource (3)
    $type: jcrDatasource
    workspace: mparticle-audiences
    includeProperties: false
    allowedNodeTypes:
      - mgnl:mpAudience
    sortBy:
      jcrName: ascending
valueField:
  $type: comboBoxField
  label: CDP mParticle Audience Header Trait
  datasource: *datasource
traitStorageClass: info.magnolia.personalization.trait.storage.StorageAwareTraitCollector$RequestScopedTraitStorage (4)
1 The name identifies the trait in personalization rules.
2 The $type indicates the trait is populated from a cookie or request header or request parameter (e.g., ?mpAudiencesRequestParameter=<Audiences>).
3 List of Audience from the mParticle Audiences content app
4 The traitStorageClass stores the trait for the duration of the user’s request. This is ideal for temporary data like recent browsing activity.
<your-magnolia-project>/light-modules/my-cdp-module/traits/mpAudiencesRequestParameter.yaml
name: mpAudiencesRequestParameter (1)
$type: requestParameterTrait (2)
voterClass: info.magnolia.cdp.mparticle.personalization.traits.voter.NameAndMultiValueVoter
defaultRuleTrait: false
defaultPreviewTrait: false
ruleField:
  $type: comboBoxField
  name: value
  label: CDP mParticle Audience RequestParameter Trait
  datasource: &datasource (3)
    $type: jcrDatasource
    workspace: mparticle-audiences
    includeProperties: false
    allowedNodeTypes:
      - mgnl:mpAudience
    sortBy:
      jcrName: ascending
valueField:
  $type: comboBoxField
  label: CDP mParticle Audience RequestParameter Trait
  datasource: *datasource
traitStorageClass: info.magnolia.personalization.trait.storage.StorageAwareTraitCollector$RequestScopedTraitStorage (4)
1 The name identifies the trait in personalization rules.
2 The $type indicates the trait is populated from a cookie or request header or request parameter (e.g., ?mpAudiencesRequestParameter=<Audiences>).
3 List of Audience from the mParticle Audiences content app
4 The traitStorageClass stores the trait for the duration of the user’s request. This is ideal for temporary data like recent browsing activity.
To verify, restart Magnolia and check the Personalization app in AdminCentral; the defined trait should appear in the trait selection dropdown.

Usage

Variant components

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

mparticle personalization

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 or header or requestParam.

mpAudiences: 53730|53731|53730
mparticle cookie
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>
Feedback

Incubators

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the CDP integration framework docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules