Download audience data for an audience destination endpoint

Prerequisites

Using the Acoustic Exchange Toolkit to download audience data from Acoustic Exchange involves download available audience data from Acoustic Exchange to a locally installed application. Acoustic Exchange users request the audience download in the Acoustic Exchange user interface. Upon receipt of the request, Acoustic Exchange creates the audience download job. Run the audienceDownload.bat/sh script repeatedly as a scheduled task to detect new download jobs as Acoustic Exchange creates them. You can also run the script manually.

When Acoustic Exchange users share an audience through the Audiences tab in the Acoustic Exchange user interface, Acoustic Exchange creates the job that it will use to receive the data from the source endpoint. As the audience destination endpoint, you make API calls to Acoustic Exchange to determine when such jobs have been created. Since users can request that audience source share audience data immediately, good practice demands that you schedule the audience upload script to make the API calls frequently, to avoid delays in responding to the user requests.

The following diagram illustrates the overall workflow for using the Acoustic Exchange Toolkit to pull audience data down from Exchange.

A. To determine if audience download jobs exist, run the audienceDownload.bat/sh script as a scheduled job. The script calls GET /v1/jobs/SEGMENT_EXPORT?endpointId={endpointId}&status={status} with the status, READY_FOR_DOWNLOAD, to get a list of jobs that have new audience data available.

B. If a job is ready to download audience data, the audience download script calls GET /v1/jobs/{jobid}/segmentDataFiles/{filepath} to download the data.

C. The script stores the data as a CSV file in a specified local directory. Specify the directory as a configuration property. The script creates the CSV file with the name format: .csv.

When the download finishes, the download script calls PUT /v1/jobs/{jobid}/status/{status} with the job status: COMPLETE.

Step-by-step

Downloading audience data from Exchange

1. Run the audienceDownload script as a scheduled job to make audience data available to Acoustic Exchange users for download to an audience destination endpoint. Audience downloads happen only in response to requests from Acoustic Exchange users in the Acoustic Exchange user interface.

Indicate whether or not to archive previously downloaded audience data before downloading the new data. Indicate your choice as the value for the following configuration property in config.properties.
ubx.audience.consumer.archiveDownloadedAudiences=true|false

Default: true

When true, Acoustic Exchange saves any previously downloaded data files to a folder named archive as a sub-folder to the folder that you specified with the ubx.audience.consumer.audienceDownloadFolder configuration property. To establish a unique file name for the archived audience, the Acoustic Exchange Toolkit adds the current timestamp to the original audience file name.

2. Run %CU_HOME%\bin\audienceDownload.bat as a scheduled job. For Linux or UNIX, run %CU_HOME%/bin/audienceDownload.sh
   Optional parameter

-c Use this option to define alternate configurations. When you specify this option, properties in the alternate configuration file override the toolkit default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file.