Audiences

Audiences Overview

The mParticle Audience Manager allows you to define audiences and connect them to integrations for the purpose of engaging with your users. This can be very powerful when it comes to user engagement and monetization scenarios.

There are many use cases for Audiences - here’s a couple of high-level examples.

Drive User Engagement

Let’s say you want to engage with users that have recently installed your app but haven’t used your app very much. Your objective is to drive higher engagement and convert those new users to high lifetime value users. You want to accomplish this across multiple channels: push notification and email. Therefore, your audience qualification criteria is that the user has installed your app in the last 72 hours and has less than three sessions.

With Audience Manager, you can easily and visually define this audience, then configure audience integrations to push notification and email partners - in this example, let’s use Kahuna for push and Mailchimp for email. Once you configure the respective integrations in the Audience Manager, mParticle instantiates a corresponding audience in Kahuna and updates the corresponding email marketing list in Mailchimp. No coding is necessary.

Drive App Downloads

Let’s say you want to find more users like your currently highly engaged users and run an app download campaign in Facebook against that target audience. You start by defining your highly engaged users, using whatever criteria is important to you: lifetime value metrics, session activity, event activity, or any other data points you capture.

Once your audience is defined in Audience Manager, you configure the Facebook integration and corresponding custom audiences are defined in your Facebook account. From there you can leverage those custom audiences like any other custom audience in Facebook.

In this example, because we want to target users that look like our highly engaged users, we will create a Facebook lookalike audience from our highly engaged user audience and run a Facebook app install campaign that targets that lookalike audience.

The Audiences Page

The Audiences page is accessible from anywhere in the Dashboard via the left navigation. It displays a list of your audiences, separated into Single Workspace and Multi Workspace, with metrics for each audience:

• Size
• Adds (last 24 hours)
• Drops (last 24 hours)
• Volatility (change in audience size - last 24 hours)
• Connected Outputs
• Created By
• Last Updated
• Status
• Actions

Build Audiences

Capture Data

Audience Manager allows you to define audiences from any user-associated data you capture with mParticle, whether from Platform inputs or partner feeds.

When you fully instrument your app using the mParticle SDK, you are sending data from your apps to the mParticle platform. mParticle also has the ability to enrich that data stream with other data sources. For example, in addition to sending your app data you may want to send in data that is not collected in the app and have the mParticle platform match the data based upon a user identifier, and then leverage the capabilities of Audience Builder to create audiences based upon this superset of data. Examples of data sent server side might include CRM data, purchase / revenue data from other non-mobile channels, and so on. Making sure all data is captured is important for audience creation as that is the first step.

Define Use Case

The second step in using Audience Manager is fleshing out your segmentation and engagement strategies:

• What user audiences are important and why?
• How will you engage and/or monetize each user audience?
• How will you evaluate the effectiveness of your strategy?

These decisions will drive your implementation of Audience Manager.

Create Audience

When you first create an audience you must specify if it will be a single workspace or multi workspace audience. A single workspace audience includes data from a single workspace. A multi workspace audience allows you to combine data across your workspaces into a single audience definition.

To create an audience:

1. From the Audiences screen, select the Single Workspace or Multi Workspace tab, and click New Audience.

   

2. Enter the Audience Name. You also have the option to provide an External Name. If provided, the external name is forwarded to Audience services and will be displayed if the audience is ever shared.

3. Under Inputs, check all the Platforms and Feeds whose data you want to use to define the audience.
4. Click the Create button. The screen refreshes with the new Audience added to the list of available of audiences and the Audience Details screen shown. Note that this screen shows a single Workspace Audience. Clicking the Multiple Workspace Audience selection from the left-side, shows a dialog asking if you would like to switch to the Multiple Audience Workspace screen.

Specify Audience Criteria

Now that you have created an audience, it’s time to add to the audience definition. Follow these steps to add criteria to your audience definition:

1. Click Add Criteria
2. Select the type of data to be used in the audience definition. If your audience is built from both platform and feed data you will need to specify where the data should be drawn from.
3. Specify additional qualifying parameters (i.e. attribute value, recency, frequency, platform version, build version, etc.) and click Done.
4. Optionally add additional criteria to the audience by adding and/or/exclusive criteria to the definition.

5. Click one of the following buttons once you have completed the definition of your audience:

   • Save as Draft - to keep the draft of your Audience to work on later
   • Activate to begin populating the audience with users and make it available for connecting to outputs

String Matching Criteria

When building audiences based on string attributes, several matching rules can be applied. All matches are case insensitive.

• Contains / Does Not Contain - Will match substrings. For example, “blue”, will match “blue” or “blue shirt”.
• Exact Match / Does Not Match - Entire string must match, no substrings. For example, “blue”, will match “blue”, but not “blue shirt”.
• Pattern - Wildcard style matching. * represents any number of characters, ? represents any single character. For example, “bl?e” or “b*e” would both match “blue”.

Date and Time Matching Criteria

There are two ways to build time-based criteria for audiences: by recency, and by date. Recency criteria define a period in time in relation to ‘now’, when the audience is actually being calculated, for example within the last 7 days. Date criteria are based on fixed calendar dates which do not move in relation to when the audience is calculated. For example, after 09/12/18.

Keep in mind that audiences defined using fixed calendar dates will have a shorter useful lifespan, as the audience builder only uses data from within a set range (last 30 days for most customers).

Recency-based criteria

Recency-based criteria select events occurring between two moments in time, relative to ‘now’. A ‘day’ represents 24 hours, and not a calendar day. For example, consider the following criteria:

If this audience is calculated at 1:00pm on September 9th 2018, then the earliest qualifying event would occur at 1:00pm on September 3rd, and the latest qualifying event would occur at 1:00pm on September 5th.

Date-based criteria

Date-based criteria are concerned with calendar dates in UTC time and are not defined in relation to when the audience is calculated.

• Before/After date criteria are NOT inclusive of the given date. For example, Before September 9th 2018 means that the latest qualifying event would occur at 11:59pm on Sepember 8th 2018 UTC. After September 9th 2018 means that the earliest qualifying event would occur at 12:00am on Sepember 10th 2018 UTC.
• On Date criteria cover from 12:00am to 11:59pm UTC on a given calendar day.
• Between Dates criteria are inclusive of the given dates. For example, Between September 7th 2018 and September 9th 2018 means that the earliest qualifying event occurs at 12:00am UTC on September 7th, and the latest qualifying event occurs at 11:59pm UTC on September 9th.

Setup an Audience Output

The next step is to connect the audience to an output service that can use the data. See our Integrations directory for a full list of Output options.

To add an audience output:

1. Find the integration you want in the Directory. You can filter the Directory to show only partners with an Audience Configuration.

   

   Click the card for your chosen partner.

2. Click + Add {partner} to Setup and, from the popup dialog, select Output Audience.

   

3. Complete the Configuration Settings dialog. Each partner will require slightly different information. Some require an API Key/Secret/Token, others require you to log in from mParticle using Oauth. See the Integrations Center for details for your integration. Give the configuration a name and click Save.

   .

   You can update your configurations at any time by navigating to Setup > Outputs, and selecting Audience Configurations.

Connect an Audience

Once you have set up your Output configuration, you can connect the Audience you have defined in mParticle.

1. From the Audiences page, select the Connect tab and click Connect Output.

2. Select an Output and complete the Connections Settings dialog. This will be different for every integration. See the Integrations Center for details for your integration.
3. Make sure the Status switch is set to Sending and click Add connection.

Any users that fit your audience criteria will begin to be available in the output platform. Some integrations take longer than others for this to happen. See the documentation for your specific integration for details.

Audience Data Format

When mParticle forwards an audience to an Output, we are only sending identities. mParticle is capable of collecting many types of identities for both devices and users, but most Audience partners will only accept the limited set of identity types that they actually use. For example, a partner that handles email marketing may only accept email addresses, a push messaging partner may only accept push tokens, and a mobile advertising platform may only accept device advertising identifiers (IDFA for iOS and GAID for Android).

When building your audiences in mParticle, you don’t have to worry too much about this. You can simply define your matching criteria, and mParticle will forward to each Output as many available identities for each matching user as that partner accepts.

Example

You define a set of audience criteria in the mParticle Audience Builder. mParticle finds 100 matching profiles.

All profiles include one Apple Advertising ID (IDFA), but only 65 include one email address.

You create connections to two Outputs: Partner A accepts IDFA and GAID identity types. Partner B accepts only the email identity type.

It’s not necessary for you to know which profiles have which identity types. mParticle simply forwards the 100 available IDFAs to Partner A, and the 65 available email addresses to Partner B.

User Profiles and Identities

mParticle creates audiences by comparing your matching criteria with each user profile. If a profile fits the criteria, each accepted identity included in the profile is forwarded to any connected Outputs.

User Profiles can contain data — including identities — collected from multiple workspaces. Even if your matching criteria only concerns data from a single workspace, once a matching user profile is found, all accepted identities are forwarded to the Output, even if the identities were collected in a different workspace.

Example

You have created 2 workspaces in your account to track activity for two related apps, App A and App B. User John Smith signs up for both apps, using the email address john.smith@example.com. However, he uses his iPad for App A and his iPhone for App B. This means that there are two different IDFA identities associated with John Smith’s profile. (note: read our IDSync documentation to understand more about how profiles with multiple identities are managed).

You create an audience in the App A workspace, and your criteria match John Smith’s user profile. When you connect that audience to an Output that accepts IDFAs, mParticle will forward both of John Smith’s IDFAs.

Audience A/B Testing

Audience A/B Testing allows you to split an audience into two or more variations and create connections for each variation independently, to help you to compare the performance of different messaging platforms. For example, if you have an audience of low engagement users that you want to reengage with your app, you might devise a test like this:

• Send 40% of the audience to Messaging Platform A
• Send 40% of the audience to Messaging Platform B
• Keep a control group of 20% who are not targeted with any messaging

You can then compare the engagement outcomes for each group and apply the most successful strategy to the entire audience.

Tests can be run for as long as required and deleted at any time. Creating a test does not affect Audience sharing. If you create a test using a P2P shared audience, your variations will be visible only to you.

Create a Test

1. From the Audience details page, select the A/B Test tab. If no test is set up for this audience, you will see only one ‘Control’ variation containing 100% of the users in the audience. Begin setting up the test by clicking Add A/B Test Variation.

2. Enter the percentage of users you want your variation to contain. You can also provide a custom name for your variation.
3. Create as many variations as you need for your test, up to a maximum of 5. The total of all your variations must always add up to 100%. You will notice that the ‘Control’ variation adjusts itself to 100 - [sum of all created variations]. If you try to assign a percentage to a variation that would cause the total to exceed 100, you will see an error message.

4. When you are satisfied with your variations, click Save.

Creating Connections

Once you have defined your variations, you can connect each variation, including the ‘Control’ variation, to any output. There is also an option to connect your full audience to any output. From the Connect tab, select the variation you want to connect and follow the standard connection flow.

In the Audiences summary screen, audiences with an active A/B test will be marked with a % symbol.

Note that whenever the Audience Name is used in forwarding the audience to downstream partners, variant audiences will be named using the format [Audience External Name] - [Variant Name].

Ending a Test

When you are ready to end a test, navigate to the A/B Test tab and click Delete Test

Deleting a test will delete all variations and any connections you have set up for each variation.

Download an Audience

You can download a calculated audience as a CSV file. This is useful if you want to troubleshoot your audience criteria, or if you want to share your audience data with a partner without an official mParticle Audience integration.

Initiate a download

You can initiate an Audience download, either from the main Audiences page:

or from the Audience Details tab of an individual audience page:

If the Audience includes A/B Testing Variants, you can select which variants you want to download.

You also need to select the identity types you want.

Download the file

The download takes some time to prepare. When your download is ready, you will receive an email with download link.

Download format

The download will be a ZIP file which, when extracted, will contain a CSV file for each audience or variant, plus a manifest.json file, with metadata about the csv files.

CSV format

Audience CSV files have a row for each identity in the audience. Remember that a single user profile can have multiple identities and, therefore, multiple rows.

The four columns show a unix timestamp for when the audience membership was retrieved, the mParticle ID of the profile, the identity type, and the value:

mpid, scanned_timestamp_ms, identity_value, identity_type
-1327484737295091692, 1538596779, h.jekyll.md, customer_id
5991422180106081928, 1538596729, m.hyde@example.com, email
3269816782460039080, 1580148438137, 74587f4b-3ed5-492f-a0f5-9a6c4578673d, ios_idfv

Manifest Example

The Manifest file will be in JSON format. See the following example for included fields:

{
  "archive_name": "mParticleAudiences_204223Jan022019_9dd9.zip",
  "id": "9dd9b6dc-f0ec-4acf-8b18-f3a357afe1c3",
  "audience_ids": [
    8754
  ],
  "included_identities": [
    "customer_id",
    "email"
  ],
  "manifest_generated": "2019-01-02T21:06:20.0216776Z",
  "min_timestamp_ms": 1546463100276,
  "max_timestamp_ms": 1546463100276,
  "total_rows": 18,
  "rows_by_identity": {
    "customer_id": 15,
    "email": 3
  },
  "files": [
    {
      "file_name": "8754_PotentialParisians_172136Nov292018.csv",
      "min_timestamp_ms": 1546463100276,
      "max_timestamp_ms": 1546463100276,
      "total_users": 15,
      "total_rows": 18,
      "rows_by_identity": {
        "customer_id": 15,
        "email": 3
      }
    }
  ]
}

Bulk Audience Connections

If you have defined a large number of audience that you want to send to an Output, you can establish the connections for many audiences at once, rather than doing them one at a time.

1. Navigate to Setup > Outputs and select Audience Configurations.
2. Select Connect Audiences to the right of the Audience Configuration you want to connect audiences to.

3. Select the audiences you want to connect and click Next.

4. Choose your settings. The same settings will apply to all audiences. Click Connect.

You will see a status message showing all successful audience connections. If any audiences cannot be connected, error details will be shown.

Audience Tags

As you continue to add audiences, you can use tags to help keep them organized. A tag is simply a label you can use to sort and search for audiences. For example, if you give all of your retargeting audiences a tag named ‘Retargeting’, you can easily find them all by filtering for the tag. You can add/remove tags for an audience directly from the Audience Manager, or in the Audience Settings. If you select more than one tag, the Audience Manager will show only audiences with both tags.

There is no limit to the number of tags you can create, but each tag name is limited to 18 characters or less.

If you clone an audience, it’s tags will be cloned, also.

Audience Faults

If mParticle encounters errors forwarding an audience to an output, it will mark the connection as faulted. Audience Faults are visible from the Audience Manager, the Audience Connection screen, and the Audience tab on the Setup > Outputs page.

While an Audience is faulted, mParticle will stop trying to forward audiences until the fault is resolved.

Click the fault icon to view a detailed error message.

If you can’t determine the cause of the fault, the most common causes of faults include:

• Authentication

  • Some integrations use OAuth tokens and require you to sign into your account in the Configuration Settings. These tokens eventually expire. You may need to go to Settings > Outputs and login again.
  • Your username, password, API Key, API Secret, etc, may be incorrect. Check any API credentials.
• Permissions - Some integrations require the creation of an API User, whose credentials are used to access the partner’s API. If the user whose credentials you provided in the Configuration Settings does not have permission to update audiences, you will see a fault.
• Rate Limiting - Many mParticle partners have limits on how often their API can be invoked within a given time frame. If this is exceeded, they return a ‘Too Many Requests’ error. If mParticle receives this error, we perform a number of retries in an ‘exponential backoff’ pattern - leaving more time before each successive retry. If the retries are exhausted before a ‘success’ response is received, the audience will be marked as faulted and mParticle will cease forwarding data. If your error message contains the text ‘Too Many Requests’ or the code ‘429’, the fault was caused by rate limiting. Contact the partner to clarify your account’s API limits. It may be possible to increase your usage limit.

When you believe you have resolved the issue, open the fault notification and click Resume to resume sending data.

Audience Sharing

Audience Sharing lets mParticle clients share audience data with each other.

There are two basic use cases for Audience Sharing:

1. Sharing an audience with a media platform to efficiently target campaigns.

   mPTravel wants to run a retargeting campaign for their web app on the mPMovies media platform. Since both are mParticle clients, mPTravel can share the retargeting Audience they have created with mPMovies, who can then use that audience to determine which users to target with ads for mPTravel.

2. Mutually sharing audiences with a related app to allow both parties to expand their user base.

   mPTravel and mPRestaurants both target users interested in travel and entertainment. Since they are both mParticle customers, they agree to share audiences with each other, so that each can target the other’s users.

Any Audience Sharing arrangement has two parties:

• The Initiator offers to share one or more of the audiences they have created in mParticle.
• The Receiver gains access to the shared audience in their own mParticle dashboard. In order to receive audiences, you must opt in.

Either party can end the arrangement at any time.

Opt In to Receive Audiences

To be able to receive audiences, navigate to Audiences in the Dashboard, click P2P Audiences, and turn on the Receiving switch.

You will be prompted to accept the sharing terms and conditions, and upload a PNG file of your company logo.

Share an Audience

To share an audience, from the Audience page, under P2P Audiences > Shared, and click Share Audience.

Select the audiences you want to share and the mParticle customers you want to receive them. Only activated audiences can be shared.

The Receiver must accept the audiences before sharing begins. Until the audience is accepted, it will appear as ‘pending’ in your Shared audience tab.

Your Shared tab will show an up-to-date view of each audience you’ve shared, and which mParticle customers they are shared with.

Receive an Audience

If another mParticle customer has shared an audience with you, you will see a notification on the Audience page, under P2P Audiences > Received, showing that you have audiences pending. Click it to accept or reject the audiences.

Once you have accepted an audience, you can connect it to any of your audience services, just like an audience you have created yourself.

Updates to Shared Audiences

Once an Audience is shared, any users added, deleted or updated will be reflected for all parties that share the audience.

Stop Sharing

Once a particular audience is being shared, the sharing arrangement can end in several ways.

1. The Initiator deletes the audience.
2. The Initiator chooses to ‘unshare’ the audience.
3. The Receiver removes the audience from their ‘Shared Audiences’ tab.
4. The Receiver opts out of Audience Sharing.

If any of the above occur, the shared audience will no longer be available to the Receiver.

Canceling a sharing arrangement cannot be undone. If you wish to resume it, the Initiator must resend the audience to the receiver.

Lifetime Audiences

Lifetime Audiences are a paid premium feature. Contact your mParticle representative if you’re interested in using Lifetime Audiences.

mParticle’s new Lifetime Audiences feature lets you define and build audiences based on long-term historical data. Lifetime audiences differ from our standard audiences, now known as “Real-time” audiences, in a few key ways:

• Real-time audiences are based only on recently received data. For most customers, real-time audiences draw on the most recent 30 days of data. Lifetime audiences uses any data that we have saved, according to your retention policies.
• Real-time audiences are constantly calculated and updated on an ongoing basis, and changes to the audiences are often forwarded to Audience partners in near real-time. Lifetime audiences are calculated only once and, given the volume of data involved, take some time to complete. Forwarding a Lifetime audience to an audience partner also happens only once. You can manually set the audience to be calculated or sent again.
• Since Lifetime audiences use huge amounts of data, your account is limited to a set amount of calculations per year. A single calculation can include multiple audiences as long as they are calculated together.
• While Lifetime audiences support all of the same Audience partners as Real-time audiences, with the same connection settings, the workflow of calculating and sending a Lifetime audience has a few optional steps: to allow you to make the most of your calculations, you can calculate and send audiences in bulk.

Workflow

1 - Create a New Lifetime Audience

Lifetime Audiences are managed separately from Real-time audiences. Choose Audiences > Lifetime from the left navigation menu, and click + New Lifetime Audience.

2 - Define date range and inputs

Just as with Real-time audiences, you can define which inputs you want to calculate the audience from. For Lifetime audiences you also need to define a date range. You can choose All available data or define any period within the available range. When you’re ready, click Create. The start and end dates are inclusive and it uses the UTC timezone.

3 - Define Audience Criteria

Define your audience, using any number of criteria. This step works identically to Real-time audiences. When your definition is ready, click Save as Draft.

4 - Calculate one or more audiences

From the In Progress tab of the Lifetime Audiences page, click Calculate at the top of the page, or within the actions menu on a single lifetime audience.

Select any additional DRAFT audiences from the list to add them to the calculation. When you’re ready click **Start Calculation.

5 - Set up one or more connections

At first your audience will show as Calculating in the list view. While you wait for the calculation to complete, you can set up one or more audience connections. Calculation can take many hours for large amounts of data. You can track it’s progress via a popup in the Size column.

The Connections screen functions identically to Real-time audiences. Add and configure one or more connections. The only difference is that when you save the connection, no data is forwarded until you explicitly ‘send’ the audience.

6 - Send your calculated audience

Once your audience is completely calculated, you can see it in the Ready tab. Click Send next to an Audience to go back to the Connections screen.

From the Connections screen click Send. You can also adjust your output connections here as needed.

Select one or more audience Outputs and click Send.

This will forward all members of the audience to the Output.

Calculated audience will remain in the Ready tab for 30 days, after which they will need to be recalculated and can be found in the Archive tab. Once an audience is in the archive tab, you can clone and recalculate it. Remember that the audience will not be updated in real time. If you want to update the audience, you must run the calculation again.

User Attribute Sharing

mParticle’s Audience User Attribute Sharing feature allows you to include user attributes along with identities when you forward an audience to a supported Partner.

Set up User Attribute Sharing

1 - Create the Connection

Create the Audience Connection in the usual way. For affected partners, you will see the following notification:

If you want to forward User Attributes to this partner, make sure you set the Status to Inactive as you create the connection. This will make sure you do not begin forwarding data until you have selected the user attributes to forward.

2 - Select User Attributes

From the connection screen, select the User Attributes you want to include. By default, all attributes are disabled. It may take up to 15 minutes before attributes begin to be forwarded.

3 - Enable the Connection

Once you have selected the User Attributes you want to forward, Save and Activate the Audience, open the Settings and set the Status to Active to begin forwarding identities.

Data Processing Notes

mParticle’s User Profile stores user attributes across platforms, workspaces and accounts. This means that, if your audience output uses device IDs, and if you are tracking a User across multiple platforms (mobile and web, for example) you may be able to forward user attributes that were not collected on the targeted mobile devices.

If you select a workspace-level attribute, and the same attribute name is used across multiple workspaces in the account, then mParticle will only use values from the workspace you created the audience in.