Destination configuration

Overview

This configuration allows you to indicate essential information like your destination name, category, description, and more. The settings in this configuration also determine how Experience Platform users authenticate to your destination, how it appears in the Experience Platform user interface and the identities that can be exported to your destination.

This configuration also connects the other configurations required for your destination to work - destination server and audience metadata - to this one. Read how you can reference the two configurations in a section further below.

You can configure the functionality described in this document by using the /authoring/destinations API endpoint. Read Destinations API endpoint operations for a complete list of operations you can perform on the endpoint.

Example configuration

Below is an example configuration of a fictional destination, Moviestar, which has endpoints in four locations on the globe. The destination belongs to the mobile destinations category. The sections further below break down how this configuration is constructed.


{
   "name":"Moviestar",
   "description":"Moviestar is a fictional destination, used for this example.",
   "status":"TEST",
   "customerAuthenticationConfigurations":[
      {
         "authType":"BEARER"
      }
   ],
   "customerDataFields":[
      {
         "name":"endpointsInstance",
         "type":"string",
         "title":"Select Endpoint",
         "description":"Moviestar manages several instances across the globe for REST endpoints that our customers are provisioned for. Select your endpoint in the dropdown list.",
         "isRequired":true,
         "enum":[
            "US",
            "EU",
            "APAC",
            "NZ"
         ]
      },
      {
         "name":"customerID",
         "type":"string",
         "title":"Moviestar Customer ID",
         "description":"Your customer ID in the Moviestar destination (e.g. abcdef).",
         "isRequired":true,
         "pattern":"^[A-Za-z]+$"
      }
   ],
   "uiAttributes":{
      "documentationLink":"http://www.adobe.com/go/destinations-moviestar-en",
      "category":"mobile",
      "connectionType":"Server-to-server",
      "frequency":"Streaming"
   },
   "identityNamespaces":{
      "external_id":{
         "acceptsAttributes":true,
         "acceptsCustomNamespaces":true,
         "acceptedGlobalNamespaces":{
            "Email":{
               
            }
         }
      },
      "another_id":{
         "acceptsAttributes":true,
         "acceptsCustomNamespaces":true
      }
   },
   "schemaConfig":{
      "profileRequired":false,
      "segmentRequired":true,
      "identityRequired":true
   },
   "destinationDelivery":[
      {
         "authenticationRule":"CUSTOMER_AUTHENTICATION",
         "destinationServerId":"9c77000a-4559-40ae-9119-a04324a3ecd4"
      }
   ],
   "segmentMappingConfig":{
      "mapExperiencePlatformSegmentName":false,
      "mapExperiencePlatformSegmentId":false,
      "mapUserInput":false,
      "audienceTemplateId":"cbf90a70-96b4-437b-86be-522fbdaabe9c"
   },
   "aggregation":{
      "aggregationType":"CONFIGURABLE_AGGREGATION",
      "configurableAggregation":{
         "splitUserById":true,
         "maxBatchAgeInSecs":0,
         "maxNumEventsInBatch":0,
         "aggregationKey":{
            "includeSegmentId":true,
            "includeSegmentStatus":true,
            "includeIdentity":true,
            "oneIdentityPerGroup":false,
            "groups":[
               {
                  "namespaces":[
                     "IDFA",
                     "GAID"
                  ]
               },
               {
                  "namespaces":[
                     "EMAIL"
                  ]
               }
            ]
         }
      }
   },
   "backfillHistoricalProfileData":true
}

Parameter Type Description
name String Indicates the title of your destination in the Experience Platform catalog.
description String Provide a description for your destination card in the Experience Platform destinations catalog. Aim for no more than 4-5 sentences.
status String Indicates the lifecycle status of the destination card. Accepted values are TEST, PUBLISHED, and DELETED. Use TEST when you first configure your destination.

Customer authentication configurations

This section in the destinations configuration generates the Configure new destination page in the Experience Platform user interface, where users connect Experience Platform to the accounts they have with your destination. Depending on which authentication option you indicate in the authType field, the Experience Platform page is generated for the users as follows:

Bearer authentication

When you configure the bearer authentication type, users are required to input the bearer token that they obtain from your destination.

UI render with bearer authentication

OAuth 2 authentication

Users select Connect to destination to trigger the OAuth 2 authentication flow to your destination, as shown in the example below for the Twitter Tailored Audiences destination. For detailed information on configuring OAuth 2 authentication to your destination endpoint, read the dedicated Destination SDK OAuth 2 authentication page.

UI render with OAuth 2 authentication

Parameter Type Description
customerAuthenticationConfigurations String Indicates the configuration used to authenticate Experience Platform customers to your server. See authType below for accepted values.
authType String Accepted values are OAUTH2, BEARER.

Customer data fields

This section allows partners to introduce custom fields. In the example configuration above, customerDataFields requires users to select an endpoint in the authentication flow and indicate their customer ID with the destination. The configuration is reflected in the authentication flow as shown below:

Custom field authentication flow

Parameter Type Description
name String Provide a name for the custom field you are introducing.
type String Indicates what type of custom field you are introducing. Accepted values are string, object, integer.
title String Indicates the name of the field, as it is seen by customers in the Experience Platform user interface.
description String Provide a description for the custom field.
isRequired Boolean Indicates if this field is required in the destination setup workflow.
enum String Renders the custom field as a dropdown menu and lists the options available to the user.
pattern String Enforces a pattern for the custom field, if needed. Use regular expressions to enforce a pattern. For example, if your customer IDs don’t include numbers or underscores, enter ^[A-Za-z]+$ in this field.

UI attributes

This section refers to the UI elements in the configuration above that Adobe should use for your destination in the Adobe Experience Platform user interface. See below:

Parameter Type Description
documentationLink String Refers to the documentation page in the Destinations Catalog for your destination. Use http://www.adobe.com/go/destinations-YOURDESTINATION-en, where YOURDESTINATION is the name of your destination. For a destination called Moviestar, you would use http://www.adobe.com/go/destinations-moviestar-en
category String Refers to the category assigned to your destination in Adobe Experience Platform. For more information, read Destination Categories. Use one of the following values: adobeSolutions, advertising, analytics, cdp, cloudStorage, crm, customerSuccess, database, dmp, ecommerce, email, emailMarketing, enrichment, livechat, marketingAutomation, mobile, personalization, protocols, social, streaming, subscriptions, surveys, tagManagers, voc, warehouses, payments.
connectionType String Server-to-server is currently the only available option.
frequency String Streaming is currently the only available option.

Schema configuration in the mapping step

Enable mapping step

Use the parameters in schemaConfig to enable the mapping step of the destination activation workflow. By using the parameters described below, you can determine if Experience Platform users can map profile attributes and/or identities to the desired schema on your destination’s side.

Parameter Type Description
profileFields Array Not shown in example configuration above. When you add predefined profileFields, Experience Platform users have the option of mapping Platform attributes to the predefined attributes on your destination’s side.
profileRequired Boolean Use true if users should be able to map profile attributes from Experience Platform to custom attributes on your destination’s side, as shown in the example configuration above.
segmentRequired Boolean Always use segmentRequired:true.
identityRequired Boolean Use true if users should be able to map identity namespaces from Experience Platform to your desired schema.

Identities and attributes

The parameters in this section determine which identities your destination accepts. This configuration also populates the target identities and attributes in the mapping step of the Experience Platform user interface, where users map identities and attributes from their XDM schemas to the schema in your destination.

You must indicate which Platform identities customers are able to export to your destination. Some examples are Experience Cloud ID, hashed email, device ID (IDFA, GAID). These values are Platform identity namespaces that customers can map to identity namespaces from your destination. You can also indicate if customers can map custom namespaces to identities supported by your destination.

Identity namespaces do not require a 1-to-1 correspondence between Platform and your destination.
For instance, customers could map a Platform IDFA namespace to an IDFA namespace from your destination, or they can map the same Platform IDFA namespace to a Customer ID namespace in your destination.

Read more in the Identity Namespace overview.

Render target identities in the UI

Parameter Type Description
acceptsAttributes Boolean Indicates if your destination accepts standard profile attributes. Usually, these attributes are highlighted in partners’ documentation.
acceptsCustomNamespaces Boolean Indicates if customers can set up custom namespaces in your destination.
allowedAttributesTransformation String Not shown in example configuration. Used, for example, when the Platform customer has plain email addresses as an attribute and your platform only accepts hashed emails. In this object, you can the transformation that needs to be applied (for example, transform the email to lowercase, then hash). For an example, see requiredTransformation in the destination configuration API reference.
acceptedGlobalNamespaces - Used for cases when your platform accepts standard identity namespaces (for example, IDFA), so you can restrict Platform users to only selecting these identity namespaces.

Destination delivery

Parameter Type Description
authenticationRule String Indicates how Platform customers connect to your destination. Accepted values are CUSTOMER_AUTHENTICATION, PLATFORM_AUTHENTICATION, NONE.
  • Use CUSTOMER_AUTHENTICATION if Platform customers log into your system via a username and password, a bearer token, or another method of authentication. For example, you would select this option if you also selected authType: OAUTH2 or authType:BEARER in customerAuthenticationConfigurations.
  • Use PLATFORM_AUTHENTICATION if there is a global authentication system between Adobe and your destination and the Platform customer does not need to provide any authentication credentials to connect to your destination. In this case, you must create a credentials object using the Credentials configuration.
  • Use NONE if no authentication is required to send data to your destination platform.
destinationServerId String The instanceId of the destination server configuration used for this destination.

Segment mapping configuration

Segment mapping configuration section

This section of the destination configuration relates to how segment metadata like segment names or IDs should be shared between Experience Platform and your destination.

Through the audienceTemplateId, this section also ties together this configuration with the audience metadata configuration.

The parameters shown in the configuration above are described in the destinations endpoint API reference.

Aggregation policy

Aggregation policy in the configuration template

This section allows you to set the aggregation policies that Experience Platform should use when exporting data to your destination.

An aggregation policy determines how the exported profiles are combined in the data exports. Available options are:

  • Best effort aggregation
  • Configurable aggregation (shown in the configuration above)

Read the section on using templating and the aggregation key examples to understand how to include the aggregation policy in your message transformation template based on your selected aggregation policy.

Best effort aggregation

TIP

Use this option if your API endpoint accepts fewer than 100 profiles per API call.

This option works best for destinations which prefer fewer profiles per request and would rather take more requests with less data than fewer requests with more data.

Use the maxUsersPerRequest parameter to specify the maximum number of profiles that your destination can take in a request.

Configurable aggregation

This option works best if you’d rather take large batches, with thousands of profiles on the same call. This option also allows you to aggregate the exported profiles based on complex aggregation rules.

This option allows you to:

  • Set the maximum time and maximum number of profiles to aggregate before an API call is made to your destination.
  • Aggregate the exported profiles mapped to the destination based on:
    • Segment ID;
    • Segment status;
    • Identity or groups of identities.

For detailed explanations of the aggregation parameters, refer to the Destinations API endpoint operations reference page, where each parameter is described.

Historical profile qualifications

You can use the backfillHistoricalProfileData parameter in the destinations configuration to determine if historical profile qualifications should be exported to your destination.

Parameter Type Description
backfillHistoricalProfileData Boolean Controls whether historical profile data is exported when segments are activated to the destination.
  • true: Platform sends the historical user profiles that qualified for the segment before the segment is activated.
  • false: Platform only includes user profiles that qualify for the segment after the segment is activated.

How this configuration connects all necessary information for your destination

Some of your destination settings must be configured through the destination server or the audience metadata configuration. The destination configuration described here connects all these settings by referencing the two other configurations as follows:

  • Use the destinationServerId to reference the destination server and template configuration set up for your destination.
  • Use the audienceMetadataId to reference the audience metadata configuration set up for your destination.

On this page