Acoustic Exchange Toolkit Overview and Requirements

The Acoustic Exchange Toolkit provides a way for locally installed applications, also called On Prem applications, to interact with Acoustic Exchange.

To download the Acoustic Exchange Toolkit, go to https://github.com/acoustic-exchange/toolkit-1.3

Exchange creates a structure that supports dynamic relationships between independent software applications that register with Exchange. Each Acoustic Exchange participating application can provide different types of marketing data and different ways to identify individual customers. The Acoustic Exchange Toolkit installs behind your corporate firewall to securely connect your local applications and databases to Exchange APIs and the ecosystem.

You can use the Exchange Toolkit to perform the following actions:

A. Upload audience data from a local application to Exchange. The application appears in Exchange as an audience source endpoint (audience producer).
B. Download event data from Exchange to a local application. The application appears in Exchange as an event subscriber (event consumer) endpoint.
C. Download audience data from Exchange to a local application. The application appears in Exchange as an audience destination (audience consumer).

When to use the Exchange toolkit

Exchange users can apply the Exchange Toolkit to integrate their business solution with Exchange when the solution includes software that an Exchange customer installs in their local environment.

Installing the Toolkit is an alternative to opening your corporate firewalls to allow Exchange to pull data from a data source application or to push data to a data consumer application. The Toolkit installs behind your corporate firewall to communicate securely with Exchange over HTTPS.

Audience producers

Use the Exchange toolkit if a locally installed business solution can provide audience data as a file that can be uploaded to Exchange. For example, owners of HCL Campaign can run flowcharts that generate output as a CSV file. The toolkit enables the flowchart output to appear in Acoustic Exchange as an available audience. You can schedule the Exchange Toolkit to run periodically so that Exchange users always have access to updated audience data.

Audience consumers

If a locally installed application is a destination for audience data, use the Exchange Toolkit to provide data when it is available in Exchange. You can configure the toolkit to run as a scheduled job to automatically check for new audience data.

Event consumers

If a locally installed business solution accepts event data as an event subscriber, use the Toolkit to download the event data and add it to a local database. The Toolkit provides a sample mapping file that you can use to specify how the event data is stored in the database. For example, you might use the imported event data for custom reporting, analysis, and re-targeting.

General requirements for the Toolkit

Installing and operating the Toolkit requires access to the Exchange user interface, Exchange authentication keys, and administrative access to various systems that are related to the applications that register with Exchange.

Before you begin, confirm that you have established the required access privileges and logins.

If you don't have access to Exchange, contact Acoustic Support.

To establish access to resources that are associated with the locally installed data producer or consumer application, contact the local system.

Exchange access requirements

To access Exchange, we can create and provision an Exchange account on your behalf. Exchange depends on authentication keys to ensure that you can access only the endpoints that are registered for your account.

To request that Exchange to create and provision your Acoustic Exchange account, contact Acoustic Support.

Your fully provisioned account includes the following elements.

  • Exchange user account, including credentials to log in to the Exchange UI.
  • An endpoint-level Exchange authentication key.
  • A URL to call external Exchange APIs. Contact Acoustic Support for the address that your account requires.

Exchange authentication key requirements
The Toolkit calls various Exchange APIs. Each call must include an endpoint-level authentication key that is specific to your account.

You must provide the authentication key in the configuration properties for your installation of the Toolkit.

You can find your endpoint-level authentication key in the Endpoint details menu on the Endpoints tab in the Exchange user UI. You must have a valid login to Exchange to access the Endpoints tab.

Local access requirements

Installing and operating the Acoustic Exchange Toolkit requires access to various systems in your local network environment. Establishing this access typically requires network or database administrative privileges.

Before you begin, confirm that you have established the following access privileges and logins.

  • Administrative access to install and configure files on the server where you install the Toolkit. Contact your local system administrator for the required address and privileges.
  • Administrative access to the database where you want to import event data. Contact your database administrator for the required address and privileges.

Resources and support for the Acoustic Exchange Toolkit

Acoustic Exchange provides various resources to support the Acoustic Exchange Toolkit. You can take advantage of installed, online, and educational resources. Acoustic Exchange developer center is the home for the binary source files that are required to install the Acoustic Exchange Toolkit.

Acoustic Exchange product documentation is located in the Acoustic Help Center.

Logging for the Acoustic Exchange Toolkit
You can access the log files for the Acoustic Exchange Toolkit in the %CU_HOME%/logs folder.

Event files that are processed successfully are stored by default in the %CU_HOME%/AppData/eventsDownload folder.

Event files that the Acoustic Exchange Toolkit is not able to process are stored in the dataError directory. If you encounter problems during event data import, review the condition and structure of the files in the %CU_HOME%/AppData/downloads/dataError folder to determine a course of action.