DocumentationAudience ManagerAudience Manager User Guide

Data Files for Audience Optimization Reports and Actionable Log Files

Last update: Mon Sep 12 2022 00:00:00 GMT+0000 (Coordinated Universal Time)

A data file contains impression, click, or conversion data. When formatted properly, you can import this data into Audience Manager to view it in the Audience Optimization Reports and create traits using the data via Actionable Log Files. Format your data files according to these specifications in this section.

Overview

A properly named and formatted data file lets you import impression, click, or conversion data into the Audience Optimization Reports. This is useful when working with a partner who is not integrated with Audience Manager and you want to work with their data in that report suite. This process requires separate files for impression, click, and conversion data. Do not mix these events in a single file.

A data file must be accompanied by a metadata file. The metadata file contents match data file information to related, human-readable labels in the report menus. For more information, see Overview and Mappings for Metadata Files.

Naming Conventions for Data Files

The following syntax defines the structure of a well-formed data file name. Note, italics indicates a variable placeholder that changes depending on the file contents.

Syntax:

event type_yyyymmdd

In a file name:

  • The event type indicates the file contains impressions, clicks, or conversions. Create a separate file for each event type.
  • An underscore separates the event type and a year-month-date timestamp.
  • Before uploading, compress your files using gzip and save them with the .gz file extension.

Given these requirements, name your data files based on their contents like this:

  • Impression data:

    code language-none 
    impressions_yyyymmdd.gz

  • Click data:

    code language-none 
    clicks_yyyymmdd.gz

  • Conversion data:

    code language-none 
    conversions_yyyymmdd.gz

Content Format for Data Files

The following syntax defines the content structure in well-formed data file. Note, italics indicates a variable placeholder and is replaced with an label in an actual data file.

Syntax:

header label 1 | header label 2 … header label n | version

In the file contents:

  • The header labels must appear in the order as shown in the table below. Impressions and clicks use the same labels. Conversion files contain extra headers.

  • If you don’t have data for a particular column, populate that field with a -1.

  • Files must end with a version number. The current version is 1.1.

  • Separate file headers and contents with the non-printing ASCII 001 character. If you cannot use ASCII 001, then separate the headers and data with a tab delimiter. As these are non-printing characters, the syntax example above shows a pipe "|" for display purposes only.

Field Labels

The table below lists and describes the column headers for your data file. Headers are case-sensitive and must appear as ordered in the table. All data types are integers (INT) unless indicated otherwise.

Label
Description
Time-Stamp
A UTC date and time for the impression, click, or conversion event. Use the yyyy-MM-dd HH:mm:ss format.
User-ID
Your ID for a site visitor, also known as the data provider unique user ID or DPUUID.
Advertiser-ID
The data source ID or integration code for your advertiser.
BU-ID
Business unit ID.
Campaign-ID
Campaign ID.
Creative-ID
Creative ID.
Site-ID
Site ID.
Placement-ID
Numeric placement ID from the ad server.
Insertion-Order-ID
Insertion Order ID.
Tactic-ID
Tactic ID.
Vertical-ID
ID for an industry vertical or category.
Quantity

The number of items sold in a conversion event.

For conversion data files only.

Revenue

Purchase or other conversion amount. Data type: Float.

For conversion data files only.

Other-Data

URL of the conversion landing page. Data type: String.

For conversion data files only.

Event-Type

Conversion type. Indicates whether a conversion is matched or not. Options include:

  • 0: Impression
  • 1: Click
  • -1: Unattributed or unknown

For conversion data files only.

Version
A required version number that appears at the end of every row in an impression, click, or conversion data file. The current version is 1.1.

Delivery Methods for Data Files

Upload your impression, click, or conversion data files to an Amazon S3 directory for your Audience Manager account. Refer to this section for information about delivery/directory paths, file processing times, and updates.

IMPORTANT
Contact your Audience Manager consultant or Customer Care to get started and set up an Amazon S3 directory for your data files.

Delivery Path Syntax and Examples

Data is stored in a separate namespace for each customer in an Amazon S3 directory. The file path follows the syntax shown below. Note, italics indicates a variable placeholder. Other elements are constants or keys and do not change.

Syntax:

…/log_ingestion/pid= AAM ID/dpid= d_src/logs/ file type_yyyymmdd

The following table defines each of these elements in a file delivery path.

File Parameter
Description
.../log_ingestion/
This is the start of the directory storage path. You'll receive the full path when everything is set up.
pid=AAM ID
This key-value pair contains your Audience Manager customer ID.
dpid=d_src
This key-value pair contains the data source ID passed in on an event call. It identifies the agency the data comes from and ties that data to a supporting metadata file.
logs
A higher level directory for data files.
file type_yyyymmdd
A file type name that indicates what sort of data it contains and a delivery timestamp.

Sample Upload Path and File Name

When you upload a file, the path will look similar to this:

.../log_ingestion/pid=1234/dpid=567/logs/impressions_20150902

File Processing Times and Updates

Data files are processed four times a day, at regular intervals.

To update your data, send in a file that contains all of the impressions, clicks, or conversions for a particular day. In this case, a day is the 24-hour period from one midnight to the next. As a best practice, you may want to use UTC time to define your day interval.

Next Steps

Review the requirements for naming and creating metadata files. To get started, see Overview and Mappings for Metadata Files.

de293fbf-b489-49b0-8daa-51ed303af695