Importing and using external audiences

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:

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.

Create an identity namespace for the external audience

The first step for using external audiences is creating an identity namespace. Identity namespaces allow 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.

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.

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.

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.

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.

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

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

Set up and import audience data

With the dataset enabled, data can now be sent into 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.

Audience metadata structure

After creating a connection, you can now ingest your data to 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"
        }
    }
}

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.

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

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.

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

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.

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

Set up and import external audience membership data

With the dataset enabled, data can now be sent into 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.

Segment membership structure

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

A sample of the external audience membership payload 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 Membership"
        }
    },
    "body": {
        "xdmMeta": {
            "schemaRef": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
                "contentType": "application/vnd.adobe.xed-full+json;version=1"
            }
        },
        "xdmEntity": {
            "_id": "{UNIQUE_ID}",
            "description": "Sample description",
            "{TENANT_NAME}": {
                "identities": {
                    "{SCHEMA_IDENTITY}": "sample-id"
                }
            },
            "personId" : "sample-name",
            "segmentMembership": {
                "{IDENTITY_NAMESPACE}": {
                    "{EXTERNAL_IDENTITY}": {
                        "status": "realized",
                        "lastQualificationTime": "2022-03-14T:00:00:00Z"
                    }
                }
            }
        }
    }
}