Event

The mParticle integration with the Adobe Experience Platform (AEP) allows you to forward your event data from mParticle to Adobe where you can use it to build and deliver rich, personalized experiences for your customers. Adobe Experience Platform enables organizations to centralize and standardize customer data from any system.

This integration makes your mParticle data available across each of the tools within the Adobe Experience Platform.

Prerequisites

Before you can create and connect to an Adobe Experience Platform output in the mParticle UI, you must:

1. Configure access to Adobe Experience Platform for mParticle
2. Configure a schema, data set, and data stream in Adobe Experience Platform

You will need:

• Access to your organization’s Adobe Admin Console
• Access to your organization’s Adobe Developer Console

After configuring access to Adobe for mParticle (and before configuring your schema, data set, and data stream), you should have:

• The Client ID (also referred to as API key) for your Adobe account (this is a single key that can be referred to as either the API Key or the Client ID)
• The Organization ID for your Adobe account
• A valid Access Token for the Adobe Edge Network API
• The Sandbox name where you will be sending your mParticle data

1 Configure access to Adobe Experience Platform for mParticle

1.1 Create a new product profile for mParticle in the Adobe Experience Platform

1. Log in to the Adobe Admin Console.
2. Click Products in the top navigation menu, and select “Adobe Experience Platform” from All products and experiences.
   
3. Click New profile.
4. Enter a Product profile name, such as “mParticle Integration”, and an optional display name and description.
5. Click Save.

1.2 Configure API access to Adobe Experience Platform for mParticle

1. Log in to the Adobe Developer Console.

2. Make sure you have the correct organization selected using the dropdown menu in the top right corner.

   

3. Click Create new project under Quick Start.
4. Click Add API.
5. Under Filter by product select Adobe Experience Platform, then select Experience Platform API and click Next.

6. In the next screen, keep the OAuth Server-to-Server option enabled (checked by default). Under Credential name, enter a meaningful name for your new API credential.
7. Click Next.
8. Under Select product profiles, select the new product profile you created in the previous step 1.1.
9. Click Save configured API.
10. Click on your new credentials under Connected credentials.

11. From the Credential details tab:

    • Copy your Client ID
    • Click Retrieve Client Secret, and save the generated client secret
    • Copy your Organization ID

Note: You can also refer to the Adobe API guide which has similar instructions to above.

2 Configure a schema, data set, and data stream in Adobe Experience Platform

After completing the previous section, you should now have the Client ID/API Key and Client Secret for your new API credentials, and the Organization ID for the Adobe Experience Platform account you want to send data to.

Before continuing, find the name of the Sandbox in Adobe Experience Platform you want to send your data to:

1. Log into the Adobe Experience Platform.
2. Your active Sandbox name is displayed in the upper right. The highlighted blue Prod or Dev indicates the sandbox type.
   
3. You can change your active Sandbox by clicking the Sandbox name, or going to Sandbox under Administration in the left hand nav bar.

2.1 Schema setup

Similar to the mParticle JSON schema which defines how data is structured in mParticle, a schema in the Adobe Experience Platform defines the structure and format of your data in Adobe’s platform.

Before sending data from mParticle to Adobe, you must configure a new schema in Adobe that will correctly handle the format of mParticle’s event data.

mParticle provides a schema template that you can use. To add this schema to your Adobe Experience Platform account:

1. Copy the schema template into a text editor. You will need to replace each of the following placeholders within the schema with information specific to your Adobe Experience Platform account before uploading the schema to Adobe.

2. Within the schema template, replace <XDM_TENANTID_PLACEHOLDER> with your Tenant ID.

   • To find your Tenant ID, log into Adobe Experience Cloud.
   • After logging in, the URL in your browser will resemble https://experience.adobe.com/#/@yourcompany/home
   • Your Tenant ID is the text after the @ sign. In the above example, it would be “yourcompany”.

3. Replace <schema-identifier> with any unique identifier, using only alphanumeric characters [a-z], [0-9]. For example: 57df50cef153c3fe7342efa5353364712beb5b516df65994.

   • Repeat this step for each of the following identifier placeholders in your schema:

     • datatype-identifier-1
     • datatype-identifier-2
     • datatype-identifier-3
     • datatype-identifier-4
     • datatype-identifier-5
     • field-group-identifier
4. Replace <Your schema name> with any name you want to use to refer to your schema within Adobe.
5. Replace <Your field group name> with any name you want to use to refer to your field group in Adobe.
6. Replace <your-sandbox-id> with the ID of the Sandbox you want to send your data to.
7. Replace <your-sandbox-type> with the type of your sandbox. This will either be Production or Development.
8. After making the above changes to the provided schema, submit the following API request to the Adobe Platform API endpoint: https://platform.adobe.io/data/foundation/schemaregistry/rpc/import.

Example curl request:

curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/rpc/import \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
    "schema": { /* Sample JSON schema here */ }
}'

• Make sure to replace {ACCESS_TOKEN}, {API_KEY}, {ORG_ID}, {SANDBOX_NAME} with the credentials saved from the previous step.
• Replace /* Sample JSON schema here */ with your modified schema.
• A successful request will receive an HttpStatusCode = 201(created) response.

9. To verify that your schema was added successfully:

   • Sign in to your Adobe Experience Platform account.
   • Click Schemas under Data Management in the left hand nav bar.
   • Select the Browse tab, and look for your new schema in the list.

2.2 Dataset configuration

In the Adobe Experience Platform, a dataset handles how data is stored and managed within your account. Datasets in Adobe take the form of a table containing your schema (which defines the columns of your data) and a series of fields (the rows of data ingested from mParticle). You can read more in Adobe’s Datasets overview guide.

You can create a new dataset for the schema uploaded in the previous using either the Adobe Experience Platform UI or the Adobe Platform API.

Before creating your dataset, make sure you’ve completed step 2.1 Schema setup. You will also need your:

• Client ID/API Key
• Organization ID
• Access token
• Sandbox ID
• Schema ID (value you entered in place of <schema-identifier> in step 2.1.3 above)

Using the above information, follow instructions from Adobe’s guide for creating a dataset to create a dataset using either the Adobe UI or by submitting the following API request:

curl -X POST \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "name":<dataset-name>,
    "schemaRef": {
        "id": <your-schema-id>,
        "contentType": "application/vnd.adobe.xed+json;version=1"
    }
}'

• Make sure to replace {ACCESS_TOKEN}, {API_KEY}, {ORG_ID}, {SANDBOX_NAME} with the credentials saved from the previous step.
• Replace {your-schema-id} with values entered in step 2.1.3 above.

2.3 Datastream configuration

After configuring your schema and dataset, you can configure your datastream. A datastream in Adobe is a server-side configuration that enables mParticle to forward your data to the Adobe Experience Platform by way of Adobe’s Edge Network API.

To create a new datastream for mParticle:

1. Log into the Adobe Experience Platform.
2. From the left hand nav bar, select Datastreams.
3. Click the New Datastream button.
4. Enter a name for your datastream (required) and an optional description.
5. Under Mapping Schema, use the dropdown menu to select the schema created in step 2.1 Schema setup.
6. Check any additional details you want to capture in your dataset under Geolocation and Network Lookup, Device Lookup, and Advanced Options. These settings are entirely optional.
7. Click Save and Add Mapping.
8. Under Define incoming data, either upload or paste the mParticle event mapping JSON template.
9. Click Next.
10. Review the mappings between the mParticle JSON schema and the Adobe Experience Platform schema. You can make any changes or modifications to these mappings manually here before clicking Save.
11. Select your new datastream from the list, and click Add Service.
12. Using the dropdown menu, select Adobe Experience Platform.
13. Leave Enabled turned on.
14. Under Event Dataset, select the new dataset you created in step 2.2 Dataset configuration.
15. Leave Profile Dataset blank, since this integration only supports event data.
16. Click Save.

After completing your datastream configuration, you can return to the mParticle UI to create and configure your Adobe Experience Platform connection.

mParticle AEP event integration setup instructions

Before beginning this step, make sure that you have completed all of the prerequisites. It’s critical that you have configured your schema, dataset, and datastream in the Adobe Experience Platform before creating a connection to Adobe in mParticle.

1) Create an Adobe Experience Platform output

1. Log into your mParticle account, and navigate to the Integrations Directory (Data Platform > Setup > Directory).
2. Search for “Adobe Experience Platform”, hover your cursor over the Adobe Experience Platform tile, and click Setup.
3. Check the box labeled Event, and click Configure.
4. Enter a descriptive name under Configuration Name.
5. Check Use same settings for Development & Production, if you want the same settings to be used regardless of the data environment you are ingesting data from.
6. Enter the Client ID and Client Secret that you created in step 1.2 of the prerequisites.
7. Enter the Organization ID for your Adobe Experience Platform organization.

8. Enter the Sandbox name for your Adobe Experience Platform organization.

   

9. Click Save & Open in Connections.

2) Create a connection with your new Adobe Experience Platform output

1. From your mParticle account, navigate to Connections > Connect in the left hand navigation.
2. Select a configured input to connect to the Adobe Experience Platform.
3. Click Connect Output, and click Adobe Experience Platform from the list of outputs. Select the configuration you just created from the Configuration Name dropdown menu, and click Next.
4. Set Connection Status to Active or Inactive. You can always activate a connection later after completing the configuration, but only active connections will forward data.
5. Enter the Datastream ID for the datastream you configured in Step 2.3 Datastream configuration.
6. Use the dropdown menu to select the Primary Identity Type to forward to Adobe. mParticle will forward all available identifiers with your event data, but Adobe requires one of them to be marked as the primary identity type.
7. Click Add Connection.

Data forwarding

Requirements

Adobe requires that all event data forwarded from mParticle include a Primary Identity Type. You would set this in the required Connecting setting by choosing the associated user identifier. Though mParticle forwards all available identifiers, one identifier must be set as the primary for Adobe

Limits

By default, mParticle imposes a limit of 8 events per request to the Adobe API to remain compliant with the Adobe Edge Network Server API requirements. However, you can increase this limit by first contacting Adobe and requesting an increase, and then following up with your mParticle Support representative to have the limit on the mParticle integration increased.

Upload frequency

mParticle forwards event data to active Adobe Experience Platform connections in real time.

Verify and troubleshoot your connection

Before activating your new connection, or when troubleshooting issues, please check the following:

Verify your connection settings

Verify that each required ID, token, and event mapping has been entered correctly.

Monitor your mParticle System Alerts

1. Navigate to your System Alerts by logging into mParticle and going to Activity > System Alerts in the left hand navigation.
2. Scroll to and select Adobe Experience Platform in the Connections list.
3. Filter system alerts by Date and Environment.

Settings reference

Configuration settings

Connection settings

Event Mapping JSON template

Click the link below to open the JSON event mapping template you can use when configuring the mParticle events integration for the Adobe Experience Platform.

You will need to use this JSON when completing step 8 of section 2.3 Datastream configuration in the prerequisites of the Adobe Experience Platform integration guide.

Click to open the Mapping Template

Schema template

Click the link below to open the schema template you can use when configuring the mParticle events integration for the Adobe Experience Platform.

After copying the schema into a text editor of your choice, you will need to make some specific changes so that the schema works with your particular Adobe account configuration as described in the Adobe Experience Platform integration guide.

Click to open the Schema Template