Integrate with Acoustic Exchange

Prerequisites

Exchange is a cloud-based service from Acoustic that provides a framework that enables various solutions and applications to exchange data about customer characteristics and actions. By blending data contributions from multiple Exchange partners, marketers can use Exchange to build a view of their customers that is richer, better targeted, and more comprehensive than any single application can provide. Exchange makes such a view possible by bringing various market participants together.

People act in the marketplace. For example, they act on social media, abandon shopping carts, open email, and visit brick and mortar storefronts.

Exchange partners enable, monitor, and analyze the marketplace transactions.
Partners represent themselves in Exchange as endpoints and make their data contributions available to marketers through the marketer’s Exchange user account.

Marketers blend data from various partner endpoints to create a view of their target market. Exchange calls this data syndication.

As a Business Partner that participates in Exchange, you can expand your exposure to marketers who are actively looking to connect to new types and sources of business information. Your value to these individuals is enhanced because they can now use Exchange to combine your marketing data with data from applications and other Business Partner applications.

Applications and solutions from Business Partners integrate with Exchange after completing a thorough development and validation process. The process requires that Acoustic Exchange approve the way in which the product or solution designs and supports the integration. Products that successfully integrate with Exchange are considered part of the Exchange Partner ecosystem.

To assist companies that want to join the Exchange Partner ecosystem, Exchange provides the Exchange Integration Manager. The Integration Manager is a graphical interface that guides you through the integration process.

Exchange makes the Integration Manager available only to products and solutions from Exchange Business Partners. You must have a valid Exchange partner account to begin the integration. Contact the Exchange Partner team at [email protected] to begin the process of integrating with Exchange as a business partner.

Step-by-step
##Understand the Exchange structure and operation
Products and solutions from Exchange and selected business partners are represented in Exchange as data sources and data destinations. Exchange provides a user interface where marketers can quickly select the sources and destinations that they want to connect.

When Exchange products and business partners integrate with Exchange as part of the Exchange partner ecosystem, they declare whether they can exchange event data, audience data, or both. They also declare themselves as sources or destinations for event and audience data.

When a product or solution has completed the provisioning and validation process that is required to integrate with Exchange, it appears in the Exchange user interface as an endpoint. The product or solution is considered the endpoint provider. Marketers must register the endpoint to begin working with the product or solution in their Exchange account. The registration process establishes the authentication that is required to allow Exchange to communicate with the endpoint provider in response to the marketer requests.

To address various use cases, marketers use the Exchange user interface to select a data provider, specify the data to exchange, and designate where to deliver the data. Exchange refers to this process as data syndication. Through Exchange, marketers can syndicate event and audience data between registered endpoints without the need for custom software integrations.

Exchange applications and business partners use the Exchange Integration Manager to complete a development and validation process to become available to marketers as endpoints in Exchange.

Exchange users register the endpoints that they want to use in Exchange.
Exchange users syndicate event and audience data to solve business problems. Exchange receives data from various provider endpoints. The incoming data can include characteristics that Exchange can use to identify individual customers. For example, email address is a typical identifier. Within each Exchange user account, Exchange attempts to correlate the incoming identifiers with identifiers that have been observed previously in account.
After it analyzes identity information in the incoming data, Exchange forwards the information to applications that Exchange users designate as destinations for the data. Users can configure Exchange to provide data from multiple providers to a single data recipient, or from a single provider to multiple data recipients.

Exchange posts data to each destination to a URL that is specified when the Exchange partner registers with Exchange. The receiving endpoints must provide an interface to receive the data. Where possible, the Exchange Identity Service discovers and joins identity data within a user account to create a view of a customer in multiple contexts.

Register endpoints

In Exchange, an endpoint is a representation of a business application or solution that provides or receives data through Exchange.

Products and solutions that are created and supported by Exchange or business partners can be Exchange endpoints through the Exchange partner provisioning and validation process. Appearing in Exchange as an endpoint makes it possible for marketers and business users to register the endpoint for use in their Exchange account. By registering your Exchange endpoint in their Exchange account, users indicate that they explicitly allow Acoustic Exchange to interact with your product or solution on their behalf.

The Exchange partner provisioning process includes evaluation and approval by Exchange of your product or solution as it appears in Exchange as an endpoint. Exchange provides the Integration Manager as a graphical interface to guide you through the process. During partner provisioning, you can use the Exchange Integration Manager to define how your solution appears in Exchange.

Endpoint registration by Exchange users

Exchange enables your organization and business solution for use by Exchange users only at the explicit request of each Exchange customer account. Exchange users make such a request by registering your business solution as an Exchange endpoint for their Exchange account. Endpoint registration requires that users submit the access credentials that they use to access your product or solution. Exchange provides a wizard to guide users through the process of registering your endpoint.

When a user registers an endpoint, the endpoint registration wizard either prompts users for their credentials or provides alternative submission instructions. Exchange supports various authentication standards and provides different ways to submit user credentials. Your Exchange application definition specifies the submission method and authentication requirements. The credential submission process is called Click to Connect because, from the user’s point of view, they register with just a few clicks.

When the user registers an endpoint, Exchange generates a unique authentication key that is specific to the user’s Exchange account. Exchange submits the user credentials and the authentication key to authenticate with your authorization systems.

Exchange users register each endpoint separately to ensure that only endpoints that they explicitly authorize can publish to their secure Exchange account. When the registration process is complete, the name and description of the endpoint appears in the Exchange user interface as an option that the Exchange user can select for data syndication.

Authenticate your endpoints.

All calls to the public Exchange APIs must contain an authentication key that Exchange uses to verify that the endpoint is authorized to interact with Exchange on behalf of a specific Exchange user account.

A unique authentication key is generated when Exchange users register your business solution as an endpoint in their Exchange account. Each authentication key is unique to each Exchange user account and each registration request.

Depending on how you make your solution available in Exchange, the authentication key is generated automatically, by the Acoustic Exchange account provisioning team, or by the Exchange user. The method used to generate the authentication key determines how you receive the key.

After you receive the authentication key, you must include the key in the authorization header of every API call that you make to Exchange in response to actions and requests by the Exchange user.
The Exchange users can define multiple endpoints for their Exchange accounts. Each endpoint requires a new authentication key.

Register your endpoints by type.

When you make your application or business solution available in Acoustic Exchange, you specify the type of data that the endpoint can provide and whether the endpoint is a source of data, a destination for data, or both. Acoustic Exchange users can register four types of endpoints.

Event source
Event destination
Audience source
Audience destination

When you complete partner provisioning to make your solution available as an endpoint, you indicate the type of endpoint. Acoustic Exchange uses information that you provide to present the endpoint as an option in the Acoustic Exchange user interface.

Users select endpoints

In Acoustic Exchange, users select endpoints to add to their working environment by registering endpoints with Acoustic Exchange. On the Endpoints tab, Acoustic Exchange provides a wizard to guide users through the registration process.

The endpoint registration wizard lists and describes the endpoints that are available for registration. The wizard lists your solution as an available endpoint if you provision your endpoint by creating an Exchange application in the Exchange Integration Manager during the partner provisioning and approval process. In the Integration Manager, you describe the endpoint, indicate where it is deployed, and specify how Exchange users submit access credentials during endpoint registration.

The wizard presents users with two ways to provide their access credentials.

Instructions only. Users contact you to submit the credentials by following instructions that you provide to Exchange. The registration wizard displays the exact instructions that you provide in the API call.
Direct connect. Users enter credentials directly through the endpoint wizard. The wizard displays entry fields based on properties that you specify in the call to the onboarding API.
During the registration process, Exchange generates an authentication key in response to the user request. The method that is used to generate the key depends on how you integrate with Exchange during partner provisioning.

Exchange recognizes the key as authorization to allow actions by you on behalf of the Exchange user. Your solution appears to the Exchange user as Pending until you and Exchange complete the endpoint registration process. When endpoint registration is complete, your endpoint appears on the Endpoint tab as Active and Exchange users can begin to use your solution to address their business needs thorough Exchange.
If you do not use the Integration Manager to integrate with Exchange, users must register your endpoint as a custom endpoint. Registering a custom endpoint requires that the Exchange user manually generate an authentication key and submit the key to you. You must provide the means for users to submit the key and you must contact the Exchange account provisioning team to create and maintain a separate endpoint for each user account.

Endpoint registration: Instructions only

The endpoint registration wizard can provide Acoustic Exchange users with instructions for how to submit the access credentials that your endpoint requires.

When an Exchange user registers your endpoint, Exchange generates the authentication key that is required to complete the registration process. The user must provide to key to you so that you can authenticate with Exchange on behalf of the user. If you want users to contact you so that they can submit their access credentials and the authentication key, you must provide the exact instructions the users need to follow. The endpoint registration wizard displays the instructions that you provide in the API request to the Exchange onboarding API.

Endpoint registration: Direct connect

The endpoint registration wizard can display entry fields that enable Exchange users to enter the access credentials and other information that the endpoint requires.

To simplify the endpoint registration process for Exchange users, you can specify Direct connect as the method to register your endpoint in Exchange. When you use Direct connect registration, the endpoint registration wizard displays entry fields where users can enter the required endpoint access information. Exchange submits the endpoint registration request automatically, using authentication that you specify. There is no requirement for the Exchange user to contact your support team to complete the registration.

You specify how Exchange users provide their access credentials in the Integration Manager as part of the provisioning process that enables your solution as an Exchange endpoint. In the Integration Manager, specify Direct connect as the method to register your endpoint. You must implement the systems that are required to accept and store the credentials that Exchange users enter. The Integration Manager indicates the Exchange APIs that are required.

Endpoint registration: Custom endpoint
The endpoint registration wizard gives Acoustic Exchange users an option to register an endpoint as a custom endpoint. Registering a custom endpoint requires specific manual actions by the user, the endpoint provider, and the Acoustic Exchange account provisioning team.

When the user registers a custom endpoint, the user manually generates an authentication key in the wizard. The user must contact you to submit the authentication key that identifies the user’s Acoustic Exchange user account. You must provide the means to submit the authentication key. You must also contact the Acoustic Exchange account provisioning team to provision the user account.

Custom endpoints are created and maintained individually. You must make any changes or updates to the endpoint configuration separately for each Acoustic Exchange user that registers the custom endpoint.

Designate events

An event is a specific activity or interaction that a business application can detect at a specific time and that can be associated with a customer identifier. The application publishes the event to Acoustic Exchange through a REST API call that includes descriptive attributes in a JSON payload. Each type of event is registered with Acoustic Exchange so that subscribing applications can readily interpret the event data.

Acoustic Exchange recognizes various common events that occur in different channels. For example, for commercial web sites, Acoustic Exchange recognizes Cart Abandonment as a distinct type of event. For mobile engagements, Acoustic Exchange recognizes when an individual installs a mobile app on a mobile phone. For email communications, an event is generated when the recipient clicks a link in the email message.

When you register an event, you can define one or more attributes that describe the event activity. You must also specify at least one attribute that can be used to identify the individual that initiated the event. For example, for an email link click event, you might define an attribute that provides the email address of the individual who clicked the link.

Events also include a timestamp to indicate when the event was observed.

Each event is assigned an event code. Acoustic Exchange uses the event code to identify the specific event.

Event publishers

Endpoints that provide events to Acoustic Exchange are referred to as event publishers. Endpoints publish events to Acoustic Exchange with the v1/event API.

When you use the endpoint API to register an endpoint with Acoustic Exchange, you must indicate if the endpoint serves as an event publisher. After you register the endpoint, the Acoustic Exchange user interface identifies the endpoint as an event publisher so that Acoustic Exchange users can more easily identify where to find event providers.

Each event publisher can provide one or more types of events. When you use the v1/eventtype API to register an event with Acoustic Exchange, you specify a name and description for the event. The name and description display in the Acoustic Exchange user interface.

Acoustic Exchange users select publishers from a list of event publishers. For each event publisher, the user can select one or more types of events.

Event subscribers

Endpoints that receive event data are referred to as event subscribers. Acoustic Exchange provides events to subscribers as a POST from the event API.

When you use the endpoint API to register an endpoint with Acoustic Exchange, you must indicate whether the endpoint serves as an event subscriber. After you register the endpoint, the Acoustic Exchange user interface identifies the endpoint as an event subscriber. This label helps Acoustic Exchange users to more easily identify which endpoints support receiving event notifications from event publishers.

Define audiences

Acoustic Exchange defines an audience as a collection of IDs that describe a group of individuals that marketers can target with products, services, or other marketing treatments. The IDs can be associated with various descriptive attributes that business users can use to better define the audience and target their marketing efforts.

Typically, the audience is generated by segmenting one or more customer databases according to various business rules and selection logic. Acoustic Exchange provides a means to share the IDs and attributes between Acoustic Exchange endpoints as a bulk exchange of data.

When Acoustic Exchange users share data between endpoint applications, Acoustic Exchange provides a way to map identifier and attribute names between the two applications.

Audience sources

Acoustic Exchange endpoints that provide audience data are referred to as audience sources.
When you register an audience source endpoint on behalf of an Acoustic Exchange user account, you must indicate that the endpoint provides audience data. You also specify at least one unique identifier that can be used to identify individual members of the audience. You can also specify other descriptive attributes that the audience contains.

After you complete endpoint registration, the endpoint appears in the Acoustic Exchange interface and is identified as an audience source. The identifiers and attributes are also available in the Acoustic Exchange interface. When users share audiences, they can use the Acoustic Exchange interface to map identifiers and attributes in the source audience to corresponding attributes in the destination audience.

Audience destinations

Acoustic Exchange endpoints that consume audience data are referred to as audience destinations.
When you register an audience destination endpoint on behalf of an Acoustic Exchange user account, you must indicate that the endpoint consumes audience data. You specify the identifiers and attributes that the destination audience contains.

The identifiers and attributes appear in the Acoustic Exchange interface so that users can map the names between the source audience and the destination audience.

Connect endpoints to Acoustic Exchange with public REST APIs

Acoustic Exchange provides a collection of public REST APIs that endpoints call to connect to Acoustic Exchange as producers and consumers of event and audience data.
The APIs include various properties to provide customer identifiers and event attributes as part of the API call.

Acoustic Exchange endpoints call the Acoustic Exchange public APIs over SSL.

Calls to Acoustic Exchange public APIs must contain a valid authentication key that Acoustic Exchange provides to Acoustic Exchange users for each endpoint that they register. The authentication key identifies the Acoustic Exchange endpoint and a specific Acoustic Exchange user account that is associated with the endpoint.

All data exchanges through Acoustic Exchange occur on behalf of a specific Acoustic Exchange user and user account. Including an authentication key with each API call ensures that the data is directed to the correct destination and that customer identifiers are attributed to the correct Acoustic Exchange account. Acoustic Exchange does not share identifier data across Acoustic Exchange accounts.

The authentication key must appear in the HTTP header of the API call. Acoustic Exchange rejects any API call that does not specify an authentication key that Acoustic Exchange can associate with a valid Acoustic Exchange account.

For a complete description of the Acoustic Exchange public APIs, see

Setup user authentication

Access to Acoustic Exchange user accounts requires entering a user name and password that Acoustic Exchange creates for each Acoustic Exchange user account. You must contact support to create an Acoustic Exchange account.

As an endpoint provider, you receive a Acoustic Exchange account in the Acoustic Exchange pilot environment that you can use for endpoint testing before going live in the Acoustic Exchange Production environment. Acoustic Exchange provides the URL and credentials to access the pilot environment.

Acoustic Exchange users receive Acoustic Exchange account credentials that include a URL and credentials for the Acoustic Exchange production environment. As an endpoint provider, you can request a user account for testing purposes.