Create and upload audience data as an audience source endpoint

Prerequisites

Use the Acoustic Exchange Toolkit to make audience data generated in a locally installed application available for syndication by Exchange users. The process involves updating toolkit configurations, generating or updating audience data in the source application, and running scripts to identify and upload the audience data to Exchange.

Using the Acoustic Exchange Toolkit to make audience data available in Acoustic Exchange involves the following steps.

• Create an audience file in the audience producer application. Create the file as a CSV file.
• Register the CSV file as an available audience in Exchange. Run audienceRegister.bat/sh as a scheduled job.
• Upload the available audience to Exchange so that Exchange users can share the data with a destination endpoint. Run the audienceUpload.bat/sh script as a scheduled job.

Step-by-step

Registering audience data with Exchange

Registering an audience with Exchange enables the Exchange Toolkit to recognize changes in the audience data that is available from the audience source. Run the audienceRegister script to register the description of the audience with Exchange.

A. During routine business operations, marketers update existing audiences and create new audiences. The audience data must be saved in a CSV file and saved in a specific directory that is identified in the toolkit configuration properties. Specify the folder with the ubx.audience.producer.audiencePublishFolder property in config.properties.

B. Run the audienceRegister script to examine the directory that you have reserved for audience data. The script looks for new CSV files. The audienceRegister script ignores files that do not follow the required naming convention. If you do not save audience data to this directory as UBXSegment_.csv, the Exchange Toolkit does not upload the new audience data to Exchange. Run the audienceRegister as a scheduled job so that you can regularly monitor the audience source directory for new audience data. Doing so helps to ensure that you are working with the most current data available.

The script scans the folder that is reserved for published CSV files to determine if new CSV files are present. If a CSV file with the name format in UBXSegment_< AudienceName>.csv is found, the script parses the file name to get the audience name. It reads the first line of the CSV file and uses the column headers as the audience attributes.

C. The script checks the audience name against the list of current audiences in Exchange. The script calls GET /v1/endpoint?segment=true&source=true&loadSegments=true&endpointId={endpointid} to get a list of existing audiences for the endpoint. If the audience name matches an existing audience name, it updates the audience. Otherwise, the audienceRegister script creates a new audience.

D. After the script processes all CSV files, it calls the Exchange API to update or add the audiences. The API call must specify the endpoint ID of the endpoint that acts as the source of the audience data.

To update audiences, the script calls PUT /v1/endpoint/{endpointid}/segments
To register a new audience, the script calls POST /v1/endpoint/{endpointid}/segments
After it completes the API calls, the script creates the published folder as a sub-folder to the directory for audience data that you specified with the ubx.audience.producer.audiencePublishFolder configuration property. The script moves the processed CSV files to the published folder.

The script examines CSV files that have been added or updated in the folder that you specify with the ubx.audience.producer.audiencePublishFolder configuration property.

Procedure

Run %CU_HOME%\bin\audienceRegister.bat as a scheduled job. For Linux or UNIX, run %CU_HOME%/bin/audienceRegister.sh.

Optional parameter

-c Specify this path if you did not install the bin directory in the default installation location.

The script creates the published folder as a sub-folder to the directory for audience data that you specified with the ubx.audience.producer.audiencePublishFolder configuration property. The script moves the processed CSV files to the published folder.

Exchange users must request an audience through the Exchange user interface. Upon receipt of the user request, Exchange begins the process that is required to share the audience data between the source and destination endpoints.

Audience sharing by Exchange users

Exchange users make selections in the Exchange user interface to initiate the actual exchange of audience data between an audience source endpoint and an audience destination endpoint. The process is called audience sharing.

Exchange users select audiences in the Exchange user interface and indicate when they want the data to be sent from the source to the destination. They can request that the audience source endpoint send the data immediately, at a future time, or on a recurring basis.

When an Exchange user requests audience data from your endpoint, Exchange creates a job to provide the data through Exchange to the destination that the user specifies. New and updated audiences appear in Exchange as Waiting for data.

To ensure that the latest audience data is displayed and made available when Exchange users request it, you must schedule the audience upload script to run repeatedly to make API calls to Exchange to detect when Exchange has created an audience upload job.

Upload audience data to Exchange

As an audience source endpoint, run the audience upload script repeatedly to respond to audience sharing requests from Exchange users and to get the corresponding audience upload job that is waiting for audience data from you.

When Exchange users share an audience through the Audiences tab in the Exchange user interface, Exchange creates the job that it will use to receive the data from the source endpoint. As the audience source endpoint, you must make API calls to 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.

A. The audienceUpload script calls GET /v1/jobs/SEGMENT_EXPORT?endpointId={endpointId}&status={status} with the status set to WAITING_TO_RECIEVE_DATA to get a list of jobs that are available to receive uploaded audience data.

B. If a job is returned, the segment upload script uses the audience name to locate the CSV file that provides the audience data. If the required CSV file exists, the script calls POST /v1/jobs/{jobid}/data to upload data to the job.

If the CSV file does not exist, the script reports an error and tries again on the next round. The script ignores the job if the CSV file is still not found after the period of time that you specify in the ubx.audience.producer.jobWaitingForDataTimeoutInMinutes configuration property.

Run the audienceUpload script as a scheduled job to make audience data available to Exchange users for download to an audience destination endpoint.

Procedure

Specify timeout for missing audience data. Enter a value, in minutes, for the following configuration property in config.properties.ubx.audience.producer.jobWaitingForDataTimeoutInMinutes
Default: 1440 minutes (24 hours)
Run %CU_HOME%\bin\audienceUpload.bat as a scheduled job. For Linux or UNIX, run %CU_HOME%/bin/audienceUpload.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.

The Exchange scheduler creates a job to export the audience. On the Audiences tab in Exchange, users can see the job listed as Waiting for data.

The audience data is uploaded to the destination endpoint through Exchange, where Exchange users can use the data for various analytical and retargeting activities.

Archiving the local copy of the audience data after upload

After the upload script finishes, the Exchange Toolkit can either move the CSV file to a new location or leave it in place for possible reuse.

The Exchange Toolkit creates the Published folder and the Delivered folder to store the CSV files that are created to provide audience data for upload to Exchange.

By default, after it uploads the audience data to Exchange, the Exchange Toolkit moves the CSV file to the Delivered folder. However, you can change a configuration setting to keep the CSV file in the Published folder.

Procedure

In configuration.properties, indicate where to locate the CSV file after uploading data to Exchange by setting the following property.

To move the CSV file that defines the audience data to the Delivered folder, set ubx.audience.producer.moveFileToDeliveredFolder to true. This is the default behavior.
The script calls DELETE /v1/endpoint/{endpointid}/segments/{segmented} to delete the audience data after copying the CSV file to the Delivered folder.

To keep the CSV file in the Published folder and available for reuse, set the property value to false. Keeping the CSV file in the Published folder allows you to reuse the audience data.