Exchange

Design Acoustic Exchange Endpoints

Prerequisites

You must complete a design and approval process in order to appear in as an endpoint.

In , an endpoint represents a product or business solution that is part of the Partner ecosystem. provides marketers with new ways to match and combine the capabilities and outputs of these products to solve business problems. As a result, appearing as an endpoint in increases a product’s value to a marketer.

To use a product from the Partner ecosystem in their user account, marketers must register the product as an endpoint in their account. To be able to register a product as an endpoint, users must have an open account or valid license to the product and be able to provide valid access credentials. This is how encourages marketers to patronize members of the Partner ecosystem.

In , endpoints are based on a set of metadata that is referred to as an application. An application serves as a blueprint that defines how your product or solution appears in , what it provides or accepts, and the authentication that it requires to interact with .

To help build your application, provides the Integration Manager. The Integration Manager provides a single, intuitive interface to define your data syndications and data center deployments, and also guides you through testing, validation, and promotion as a publicly available endpoint.

The initial partner provisioning and application design takes place in the Pilot environment. When your application is ready to go to market and approves your solution for , your application can move to the Production environment so that it is available to users.

Step-by-step

1. Access the Exchange integration manager

You must have an partner account to access the Integration Manager. The link to the Integration Manager is accessible only through the interface.

  1. Log in to .
  2. Click the navigation menu and select Integration Manager. Integration Manager opens with the My Applications page. The page lists the applications that were created previously.
  3. Create a new application or edit one of the applications in the list. If you create a new application, you must create the application with a unique name before you can proceed to edit the application.
  4. Optional: Integration Manager provides a read-only summary view of your application.
    • Use the summary to quickly view your progress towards defining how the application exchanges data with , how it describes the data, where the application is deployed, and the event types and features that it supports. You can view the list of event types and features, organized by event type or by the features that contain event types.
    • Summary displays the unique Application ID that the Integration Manager assigns to the application. This is the only place where this value displays.
    • When you open the application for editing, the Integration Manager always opens the application in the Summary view.
    • After you finish editing the application, review the Summary for completeness before you proceed to the Implementation phase.

2. Edit the application

Describe the application.
Provide a name and description for the application. displays the name and description to users in the endpoint registration wizard.

Your application forms the basis for the endpoint that users register for use in their user account. users rely on the description that you provide to understand how the endpoint that is based on your application can help them solve business problems. Describe your application clearly and concisely.

Your application is represented in the user interface among all of the applications that are available in the partner ecosystem. Being added to the list of endpoints gives you an opportunity to be seen by users who might not yet own your product or solution. A clear description can improve your chances of wider adoption among new users.

  1. Specify syndication types.
    Syndication refers to the exchange of event or audience data through . Specify the types of data that your application can provide or receive and how it moves the data to or from .

Depending on the capabilities of your product or business solution, your application might support some or all of the following data syndication methods.

Event publisher
Event consumer
Audience publisher
Audience consumer

With the exception of event publishers, supports applications that can push data to or pull data from . Event publishers can only push event data to . never attempts to pull event data from an event publisher.

The combination of the type of data being exchanged and the method used to connect to determines the specific public APIs that you must call or implement. The Integration Manager lists the required APIs in the Implementation phase, based on the selections that you make when you specify syndication types.

The distinction between exchanging data as PUSH or PULL depends on how the data moves between an endpoint and . The way that data flows between endpoints and determines how the APIs are called or implemented by the endpoint.

recognizes the following syndication types. Depending on the types of data exchanges that your product or solution supports, you can select more than one data syndication type.

  • Event publisher: PUSH. All endpoints publish event data to as a PUSH-type event publisher. Publishing events to also requires an API call to .
  • Event consumer: PUSH. An endpoint that receives event data that sends as soon as it is available is considered a PUSH-type event consumer.
  • Event consumer: PULL. An endpoint that receives event data only when it specifically requests the data from is considered a PULL-type event consumer.
  • Audience producer: PULL. calls APIs that are hosted and implemented by the source endpoint. When the source endpoint indicates that data is available, pulls audience data from the source endpoint.
  • Audience producer: PUSH. The source endpoint calls APIs that are hosted by . When the source endpoint determines that it can make audience data available, the source endpoint pushes data to .
  • Audience consumer: PULL. The destination endpoint calls APIs that are hosted by . When the destination endpoint is ready to accept audience data, it pulls data from .
  • Audience consumer: PUSH. calls APIs that are hosted and implemented by the destination endpoint. pushes audience data to the endpoint when the data is shared by an audience source. Often, cloud-based business applications (also called SaaS applications) connect to as a push-type audience consumer.

When users share audience data, can modify a destination audience in several ways. Audience consumer endpoints must specify the methods that they support.

When business users share audiences, the user interface presents an audience sharing wizard that gives the user the following options to add source audience data to a destination audience.

  • Add new records. adds audience data to the specified destination audience, either as a new audience or by adding the records to existing records in the destination audience.
  • Replace existing records. replaces all existing data in the destination audience with new audience data from the source audience.
  • Remove existing records. removes existing records that match the shared records. matches records based on the value of the identifier specified in the record.

The destination audience is a segment of a database that is maintained in your business systems. As an audience consumer, you must indicate the degree to which you allow to modify records on the database by indicating which of the audience delivery options you support. Use the Integration Manager to make that choice.

When you edit your application in the Integration Manager, the Specify syndication types section provides options to indicate how you want to consume audience data and metadata. In the Audience Consumer quadrant, you specify support for the Add, Replace, or Remove options to update destination audience records. You can select any or all of the options, depending on how much database control you allow.

The options that you select in the Integration Manager determine the options that enables for business users in the audience sharing wizard. For example, if you want to allow users to only add or delete audience records (not update), select only the Add and Remove options in Integration Manager. In the audience sharing wizard, disables the Replace option.

The Integration Manager also gives you an option to specify the default audience sharing action that enables for business users. The Add option is preselected in the Integration Manager, but you can change this selection.

When users create a new destination audience, always enables the Add option.

3. Specify database description.

In , a database definition specifies identifiers and attributes that are expected in the audience and event data that you exchange through . calls this the marketing database definition.

When users share audiences, they can map identifier and attribute names between source and destination endpoints. In the Specify database definition section of the Integration Manager, you define the identifiers and attributes that users see when they share an audience.

The identifiers and attributes that you define in the Specify database definition section display on the Source to destination mapping screen of the Share audience wizard in . Users must map an identifier that is defined in the source audience to a corresponding identifier in the destination audience. For example, emailAddress in the source might map to email in the destination.

users have the option to map one or more audience attributes in the source audience to corresponding attributes in the destination audience. For example, zip code in the source might map to postal code in the destination.

Using the Integration Manager to define the marketing database for your endpoints enables you to save time and to maintain consistency across endpoints. However, if you need to vary the definition for the different endpoints that you create, you can use the following APIs, to set the definitions individually.

PUT /v1/endpoint/application
PUT /v1/endpoint/{applicationid}/{deploymentid}

4. Add features.

In , a feature serves as a way to group related event types that your application provides. Grouping event types by feature is optional.

Each feature can contain different combinations of event types. An application can contain multiple features. An application can also support event types outside of features.

Because each feature is associated with an application, it is possible to define events and event attributes for all endpoints that are based on the application. Changes or additions that you define for the feature propagate to all endpoints that contain the feature.

You can enable or disable metadata that you define in a feature for individual user accounts. For example, you can define product options as features and enable the feature only for your customers who pay a premium for the various options.

5. Add event types

If your endpoint provides or accepts event data, your application must specify the various types of event data that your product or solution can manage.

supports a diverse taxonomy of event types. The taxonomy is organized around several categories. Each category contains several related event types.

Each event type, including custom event types, defines various attributes. Each attribute provides a value that can be used to describe the event or the individual who initiated the event. The event taxonomy recognizes the following types of attributes:

Recommended attributes. recommends certain attributes for use with a particular event type, based on general business practice and the collective experience of users. Each event type contains one or more recommended attributes. For example, the attribute subjectLine is a recommended attribute for the Email Open event type.
General attributes. A general attribute describes a characteristic that is not typically associated with a particular event type. For example, the general attribute deviceType might be useful for several different types of events.
Custom attributes. If the recommended or general event types in the taxonomy do not meet your needs, you can define a custom event that accepts data that your business systems can provide or accept. A custom attribute is available only in the event type in which you create it.

You can change the attributes associated with an event type.
You can modify the event types that you add to the application by removing recommended attributes that you do not use, adding attributes from the list of general attributes, or creating custom attributes. The changes apply only in the application in which you make the modification.

If you do not find an event type in the event taxonomy that meets your needs, you can create a custom event type. A custom event type is available only in the application in which you define the custom event type.

Creating custom event types

If you do not find the type of event that you need, you can create a custom event type. A custom event type is available only in the application in which you define the custom event type. Because custom event types are available to only one application instead of many, other ecosystem members are less likely to replicate it for use in their applications. In turn, this reduces the likelihood that marketers will include your endpoint in their data syndications because there are no other endpoints that accept your custom event data.

  1. In the Add event types section of the Integration Manager, click Add a new event type.
  2. Click the link to custom event type.
  3. Define the new event type. You must enter a name and a unique event code. Entering a description is optional, but recommended, so that users who register endpoints based on the application can see what the event type provides.
    The other fields are optional.

    • Namespace. Enter a different namespace if you define a custom event with a code that duplicates an event code that is already registered with If Namespace is empty, assumes a default value.
    • Scope. recognizes two types of events.
    • Individual. Events initiated by a single individual who can be identified by a unique identifier that is included in the event payload that the event publisher sends to .
    • Aggregate. Events that are initiated by or affect multiple individuals. Aggregate events do not contain a unique identifier in the event payload.
    • Registration type. You can choose either Publish or Subscribe.
    • PUBLISH: Identifies an event that the registering endpoint publishes to .
    • SUBSCRIBE: Identifies an event that the registering endpoint receives from .
  4. Optional: Add features to the event type. (optional)

  5. Add attributes to the event
  6. Click Apply to create the custom event type

Creating custom attributes

If you do not find the type of attribute that you need in the taxonomy, you can create a custom attribute. You create a custom attribute by modifying the definition of an event. The custom attribute is available only for the event in which you define the custom attribute.

  1. On the Add event types screen, select an event.
  2. In the Attributes section of the event definition, click + Add other attribute.
  3. Click the Create a custom attribute link at the top of the Add attribute screen.
  4. On the Attribute details window, you must enter a Code, Type, and Display name. Entering a description is optional, but recommended, to make it easier for users to understand what the attribute provides.
  5. Click Create. The new custom attribute appears in a separate section of the list of attributes that are associated with the event.

Specify deployments
A deployment in defines where and how to access the software that supports the product or solution that is provided by the partner and that is represented by an endpoint.

applications are not software that is hosted by . Business solutions that are represented in as endpoints are actually hosted on servers and data centers outside of . To enable to connect to endpoints automatically, you must define how and where you have deployed the software that provides or receives data that passes through .

can connect to endpoints that are deployed on multiple servers or data centers. You must define each deployment separately.

You must define a unique deployment ID and a name for the deployment.

Depending on the types of data that you plan to exchange, you must provide the specific URLs to where to find or deliver the data. The Integration Manager displays fields to enter source and destination URLs based on the data syndication choices that you make in the Specify syndication types section.

By default, the Integration Manager defines a single deployment in every new application. You can use this default deployment if your product or solution is deployed on a single data center.

If your product or solution is deployed on multiple data centers, you must define additional deployments.

If your product or solution is installed on a local network, you do not need to define a deployment. This type of product deployment is sometimes called an On Premise installation.

The default deployment is provisioned to use the Instructions only endpoint registration method. You can change the registration method to Direct connect when you specify the provisioning method for the application.

Specify provisioning method

For each application deployment, you must define how business users register your business solution or product as an endpoint in their account and how authenticates with your operational systems.

Specifying the provisioning method indicates to how it should provision the user accounts of users who register your product or solution as an endpoint in their account. When you specify the provisioning method, you define the following provisioning requirements.

Specify a provisioning type to indicate how users must submit endpoint registration requests.

Specify the authentication method that must use when it communicates on behalf of the user with the operational systems that support your product or solution systems.

Specify if you want to notify you when users subscribe to events that involve endpoints based on your application. This option applies only if you are a publisher or consumer of events.

The Integration Manager changes the provisioning options available to you based on your choice of provisioning type.

Endpoint registration method

Specify how users register your endpoint by specifying a provisioning type.

users that want to register your product or solution as an endpoint in their account must already be registered users of your product or solution. Endpoint registration requires the user to provide with the access credentials that they use to access your systems. uses these user credentials to authenticate with your operational systems on behalf of the user to perform actions that the user requests in the user interface.

As part of the Click-to-Connect endpoint registration approach, supports two methods that users can use to register endpoints and provide their authentication credentials.

Direct connect
Instructions only
also supports registering an endpoint as a Custom Endpoint. Registering as a custom endpoint is not considered a click-to-connect registration. does not recommend this registration method for new integrations. Registering as a custom endpoint requires various API calls and extensive communication between the endpoint provider, the user, and the provisioning team.

Direct connect registration

provides fields that allow the user to provide user credentials and other information, based on requirements that you defined in your application. passes the information to you as part of the registration request.

In the Integration Manager, you can enter static values that apply to all users who register your product as an endpoint. You can also select an option to prompt the user to enter information in the endpoint registration wizard. For example, if you require a user name and password, you can configure Direct connect to prompt users for their unique credentials. You can also define extra fields to enable users to send additional information to your systems, if you require it.

You must provide a URL to receive the endpoint registration request.

Direct connect endpoint registration requests include authentication information in the request header. You must specify the type of authentication that you require.

Instructions only registration
displays registration instructions that you provide. Typically, the instructions include guidance for a separate call to your account provisioning system.

In your instructions, describe the steps that the user must take to provide their credentials. Provide all required links and list the user information that you require.

Instructions-only registration does not require you to specify an authentication method because there is no direct communication with your systems as part of the registration request.

Authentication requirements

Specify the type of authentication that you require for Direct connect registration requests and other direct communication with your product or solution.

always includes authentication information for Direct connect endpoint registration requests. If you specify Direct connect registration, you must also specify your preferred authentication method. However, Integration Manager does not provide this option if you specify Instructions only registration.

If you request that notify you when users subscribe to events that you either produce or consume, you have the option to require that include authentication information in the header of the notification. This is optional. You must explicitly request additional authentication for subscription notifications. Additional authentication for subscription notifications is available only if you also specify Direct connect endpoint registration.

You can request that add authentication information for all other direct communications with your product, not limited to endpoint registration requests and subscription notifications. This option is available only if you also specify Direct connect endpoint registration.

supports the following authentication methods:

  • API Key: You specify a key value when you register for subscription notification. When reports a subscription change in an HTTP call, adds the specified key in the HTTP header. For example, Authorization : Bearer <API key>.
  • HTTP Basic: You specify a username and password when you register for subscription notification. When reports a subscription change, submits the credentials encoded in the HTTP header in RFC 2617 format. For example, Authorization : Basic <encoded user ID and password>.
  • OAuth: You specify a client ID and client secret when you register for subscription notification. When reports a subscription change, includes these values in the OAuth parameters that it adds to the header of the HTTP call.
  • OAuth with a refresh token only: You specify a client ID and client secret during account provisioning, separately from registration for subscription notification. When reports a subscription change, includes a refresh token, but not the client ID or client secret, in the OAuth authorization parameters in the HTTP header.
  • HMAC-SHA1: You must register the endpoint with the following attributes:
{
    "attributes":{
        "DestinationEndpoint.AuthType":"HMAC-SHA1",
        "DestinationEndpoint.AuthType.HMAC-SHA1.AuthHeader":"XXXX:%s",
        "DestinationEndpoint.AuthType.HMAC-SHA1.Key":"YYYY"
    }
}

Where:

  • DestinationEndpoint.AuthType allows Exchange to identify this endpoint as using HMAC-SHA1 authentication.
  • DestinationEndpoint.AuthType.HMAC-SHA1.AuthHeader builds the authorization header value. The generated signature will replace the % s in the value.
  • DestinationEndpoint.AuthType.HMAC-SHA1.Key is used to generate the signature. Exchange then generates the HMAC-SHA1 signature using javax.crypto.Mac. and encodes it with Base64.
    Then, the designated URL is called with a header Authorization. The header includes the AuthHeader attribute and the generated signature values. For example, Authorization: XXXX:YYYY.

Subscription notifications

can notify you when users change their event and audience syndications, or if they remove your endpoint from their user account.

Subscription notification is optional. Over time, has released several versions of subscription notifications. supports the earlier notification versions to support applications that Partners have previously built and deployed. However, if you are building a new application, or updating an existing application, use the latest available version of subscription notifications.

You can request notifications in the Specify the provisioning method section of the Edit application phase in Integration Manager. The section provides the following notification options, depending on the notifications version that your application uses.

  • Publisher only (version 1.1) sends notifications only if your application publishes events.
  • Publisher and Consumer (version 1.2): sends notifications if your application can publish and subscribe to events. can also include additional fields in the notification that identify the endpoint and the endpoint provider that is either producing or consuming the subscribed event.
  • Publisher, Consumer, and Endpoint (version 1.3): sends notifications as in version 1.2 and also notifies you when an user who has registered your endpoint removes your endpoint from their user account.

If you request subscription notifications, you must provide a subscription notification URL.

For added security when communicates with your operational systems, you can request that include authentication information in the header of the notification. This is optional. Specify by checking the option to add authentication for all outbound calls, including notifications.

The option to include authentication information is available for notifications only if you specify Direct connect as the endpoint registration method and the notification uses the same authentication method that that you select for Direct connect registration.

Call Exchange public APIs

In the Implementation section, the Integration Manager specifies the various APIs that you must either call or implement to connect the application that you have designed to .

Based on the syndication type and provisioning method that you specify in the design of your application, Integration Manager presents the lists of APIs that you need to call or implement. In some cases, you call APIs that are hosted by . In other cases, you implement APIs that calls.

Test application

In the test phase of the application development, you perform the steps that users take to register and use an endpoint that is based on your application.

The steps to test include the following. Depending on the type of endpoint your application is designed to support, you complete some or all of the following scenarios.

  • Register an endpoint. Test the provisioning method that you specified, either Instructions only (follow the instructions that you wrote) or Direct connect.
  • Event publisher: Subscribe to events and examine the results on an event consumer endpoint.
  • Event consumer: Subscribe to events and examine the events that you receive from an event producer endpoint.
  • Audience publisher: Share audiences. Examine how the audience arrives at an audience destination endpoint.
  • Audience consumer: Share audiences. Examine the audience that you receive from an audience producer endpoint.

provides Test Drive so that you can test the performance of your application. The Partner tools tab in Test drive includes a section that provides a variety of tools that you can use to test the behavior of endpoints that you create with your application. In Test Drive, you can simulate the behavior of producer and destination endpoints.

The Integration Manager provides a direct link to Test Drive on the Test your application page.

Validate application

To make your application available to users, must review and approve the application. Demonstrating your application is part of a larger validation process that includes several steps.

Integration manager lists the major steps that you must complete.

  • Complete a questionnaire that provides.
  • Describe a typical end-to-end use case that includes your business solution.
  • Meet with the Business Partner ecosystem team.
  • Demonstrate your application and supporting materials.

You must coordinate with the provisioning team to arrange for demonstrations and approvals.

will either approve promoting the application to the Production environment or request adjustments and further testing to resolve issues that were discovered during the validation process.

Promote application to Exchange production

The final step towards making your application available to users for registration as a endpoint involves moving your application from the Pilot environment to Production.

Until you promote your application, only you can register endpoints that are based on the application in the production environment. Your application is not visible to other users in Production. In Integration Manager, the visibility of your application is marked PRIVATE and the application approval status is marked PENDING. The link to make the application public is disabled and remains so until explicitly approves your application for promotion.

You decide exactly when to promote your application and make it public. At a time of your choosing, go to the Promote section in Integration Manager to submit the authentication key. When you submit the authentication key, your application becomes visible to users, who can begin registering your product or solution as endpoints that are based on the public application.

Changes to your application in Exchange Production

You cannot modify your application in the Production environment.

If you must make changes to your application after you promote it to Production, you must make the changes in your Pilot account and then promote the application again to Production.

You do not need to complete the validation process again to promote your application after the initial approval by . The Promote link remains active in Integration Manager after approves your application.

Selectively promote applications

You can create multiple applications in the Pilot environment. When you promote to Production, you can specify which of the applications are promoted to Production.

By default, every application that you create in Integration Manager deploys to Production when you promote to Production. However, you can specify individual deployments that do not deploy to Production when you promote to Production.

You control the production deployment of your applications in the Specify deployments section of the Edit application phase in Integration Manager. The Specify deployments section provides the following options:

  • Will deploy to Production The deployment is promoted to Production when you promote.
  • Will not deploy to Production The deployment is not promoted to Production if you promote.
    If you select Will deploy to Production, you cannot modify the application in Production after you promote. If you select Will not deploy to Production, you can continue to make changes to the application.

Accept endpoint registration requests from users

When your application is available to the public, users access your solution or product by registering your application as an endpoint in their account. You must process the registration requests.

To enable users to register endpoints in their account, provides an endpoint registration wizard in the user interface. Users access the registration wizard through the Register new endpoint link on the Endpoints tab in .

Although each registration request creates an endpoint registration that is unique to the user that requests it, all of the endpoint registrations for your product or solution are based on the same application. This one-to-many relationship makes it possible for you to update your application and quickly propagate the changes and updates to all users who register your endpoint.

  1. Select an application to register as an endpoint. The wizard lists all applications that are available for registration, including yours. Users learn about your application by reviewing a brief description that you defined as part of your application.
  2. Enter user credentials.
    If you implemented the Direct Connect registration method (and configured the application to prompt the user), the wizard prompts the user to provide the information that you require to access your user authentication systems.
    If you implement Instructions only, the wizard displays the instructions that you provided as part of your application definition.
  3. Submit the registration request. When an user requests an endpoint registration in the user interface, generates a unique authentication key. The authentication key must be in the authorization bearer of each API call, including registration requests.

Example

When the user submits the registration request, generates a unique authentication key that is specific to the user account and the request to register your application as an endpoint in that account. makes an HTTPS POST call to your provisioning system that includes the authentication key in the request header. Your provisioning system must be able to accept and process the call. The call provides registration information that resembles the following example.

Authentication: {<authentication credentials as defined for the  application>}
{
 "onboardingType" : "<DIRECTCONNECT | INSTRUCTIONSONLY>",
 "authKey" : "{<endpoint-level authentication key>}"
 "endpointId" : {<endpoint id>},
 "extraFields" : [ {extra name-value pairs that users can populate} ],
}

After you validate the request and completing other account provisioning tasks that your systems require, you make an API call back to to complete the registration.

The Implementation page in the Integration Manager describes the required API calls, based on the provisioning method that you specify in your application design. Confirming in advance that this process works for users is part of the testing phase that you perform prior to being approved by during the validation phase.

Updated 2 months ago


Design Acoustic Exchange Endpoints


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.