Importing and using external audiences

Last update: April 1, 2025

CREATED FOR:

  • User
IMPORTANT
This documentation contains information from a previous version of the Audiences documentation, and as a result, is out of date.

Adobe Experience Platform supports the ability to import external audience, which can subsequently be used as components for a new audience. This document provides a tutorial for setting up Experience Platform to import and use external audiences.

Getting started

This tutorial requires a working understanding of the various Adobe Experience Platform services involved in creating audiences. Before beginning this tutorial, please review the documentation for the following services:

  • Segmentation Service: Allows you to build audiences from Real-Time Customer Profile data.
  • Real-Time Customer Profile: Provides a unified, real-time consumer profile based on aggregated data from multiple sources.
  • Experience Data Model (XDM): The standardized framework by which Experience Platform organizes customer experience data. To best make use of Segmentation, please ensure your data is ingested as profiles and events according to the best practices for data modeling.
  • Datasets: The storage and management construct for data persistence in Experience Platform.
  • Streaming ingestion: How Experience Platform ingests and stores data from client- and server-side devices in real time.

Audiences vs segment definitions

Before you start importing and using external audiences, it is important to understand the difference between audiences and segment definitions.

Audiences refer to the group of profiles that you are trying to filter towards. When using segment definitions, you can create an audience by creating a segment definition that filters your profiles to the subset that meets the segment qualification criteria.

Segment definitions includes information such as the name, description, expression (if applicable), the creation date, the last modified date, and an ID. The ID links the segment metadata to the individual profiles that meet the segment qualification and are part of the resulting audience.

AudiencesSegment definition
The group of profiles that you are trying to find. When using segment definitions, this means that it’ll be the group of profiles that meet segment qualification.The group of rules used to segment the audience you’re looking for.

Create an identity namespace for the external audience

The first step for using external audiences is creating an identity namespace. Identity namespaces allow Experience Platform to associate where an audience originates from.

To create an identity namespace, follow the instructions in the identity namespace guide. When creating your identity namespace, add the source details to the identity namespace, and mark its Type as a Non-people identifier.

The Non-person identifier is highlighted on the Create identity namespace modal.

Create a schema for the segment metadata

After creating an identity namespace, you need to create a new schema for the segment you will create.

To begin composing a schema, first select Schemas on the left navigation bar, followed by the Create schema in the top right corner of the Schemas workspace. From here, select Browse to see a full selection of the available Schema types.

Both Create schema and Browse are highlighted.

Since you are creating a segment definition, which is a pre-defined class, select Use existing class. Now, select the Segment definition class, followed by Assign class.

The segment definition class is highlighted.

Now that your schema has been created, you will need to specify which field will contain the segment ID. This field should be marked as the primary identity and assigned to the namespaces you previously created.

The checkboxes to mark the selected field as the primary identity are highlighted in the Schema Editor.

After marking the _id field as the primary identity, select the title of the schema, followed by the toggle labelled Profile. Select Enable to enable the schema for Real-Time Customer Profile.

The toggle to enable the schema for Profile is highlighted in the Schema Editor.

Now, this schema is enabled for Profile, with the primary identification assigned to the non-person identity namespace you created. As a result, this means that segment metadata imported into Experience Platform using this schema will be ingested into Profile without being merged with other people-related Profile data.

Create a dataset for the schema

After configuring the schema, you will need to create a dataset for the segment metadata.

To create a dataset, follow the instructions in the dataset user guide. You should follow the Create dataset from schema option, using the schema you previously created.

The schema that you want to base your dataset on is highlighted.

After creating the dataset, continue following the instructions in the dataset user guide to enable this dataset for Real-Time Customer Profile.

The toggle to enable the schema for Profile is highlighted in the Dataset activity page.

Set up and import audience data

With the dataset enabled, data can now be sent into Experience Platform either through the UI or using the Experience Platform APIs. You can ingest this data either through a batch or streaming connection.

Ingest data using a batch connection

To create a batch connection, you can follow the instructions in the generic local file upload UI guide. For a full list of available sources that you can use ingest data with, please read the sources overview.

Ingest data using a streaming connection

To create a streaming connection, you can follow the instructions in either the API tutorial or the UI tutorial.

Once you have created your streaming connection, you will have access to your unique streaming endpoint which you can send your data to. To learn how to send data to these endpoints, please read the tutorial on streaming record data.

The streaming endpoint for the streaming connection is highlighted in the source details page.

Audience metadata structure

After creating a connection, you can now ingest your data to Experience Platform.

A sample of the external audience payload’s metadata can be seen below:

{
    "header": {
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version=1"
        },
        "imsOrgId": "{ORG_ID}",
        "datasetId": "{DATASET_ID}",
        "source": {
            "name": "Sample External Audience"
        }
    },
    "body": {
        "xdmMeta": {
            "schemaRef": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
                "contentType": "application/vnd.adobe.xed-full+json;version=1"
            }
        },
        "xdmEntity": {
            "_id": "{SEGMENT_ID}",
            "description": "Sample description",
            "identityMap": {
                "{IDENTITY_NAMESPACE}": [{
                    "id": "{}"
                }]
            },
            "segmentName" : "{SEGMENT_NAME}",
            "segmentStatus": "ACTIVE",
            "version": "1.0"
        }
    }
}
PropertyDescription
schemaRefThe schema must refer to the previously created schema for the segment metadata.
datasetIdThe dataset ID must refer to the previously created dataset for the schema you just created.
xdmEntity._idThe ID must refer to the same segment ID you are using as your external audience.
xdmEntity.identityMapThis section must contain the identity label used when creating the previously created namespace.
{IDENTITY_NAMESPACE}This is the label of the previously created identity namespace. So, for example, if you called your identity namespace “externalAudience”, you would use that as the key of the array.
segmentNameThe name of the segment that you want the external audience to be segmented by.

Building segments using imported audiences

Once the imported audiences have been set up, they can be used as part of the segmentation process. To find external audiences, go to the Segment Builder, and select Audiences tab in the Fields section.

The external audiences selector in the Segment Builder is highlighted.

Next steps

Now that you can use external audiences in your segments, you can use the Segment Builder to create segments. To learn how to create segments, please read the tutorial on creating segments.

Appendix

In addition to using imported external audience metadata and using them for creating segments, you can also import external segment memberships to Experience Platform.

Set up an external segment membership destination schema

To begin composing a schema, first select Schemas on the left navigation bar, followed by the Create schema in the top right corner of the Schemas workspace. From here, select XDM Individual Profile.

The XDM Individual Profile area is highlighted.

Now that the schema has been created, you will need to add the segment membership field group as part of the schema. To do this, select Segment Membership Details, followed by Add field groups.

The Segment Membership Details field group is highlighted.

Additionally, ensure the schema is marked for Profile. In order to do this, you will need to mark a field as the primary identity.

The toggle to enable the schema for Profile is highlighted in the Schema Editor.

Set up the dataset

After creating your schema, you will need to create a dataset.

To create a dataset, follow the instructions in the dataset user guide. You should follow the Create dataset from schema option, using the schema you previously created.

The schema that you are using to create the database is highlighted.

After creating the dataset, continue following the instructions in the dataset user guide to enable this dataset for Real-Time Customer Profile.

The toggle to enable the schema for Profile is highlighted in the create datasets workflow.