Cloud object store endpoints now include functionality where you can upload a CSV or JSON with "cart purchase+cart purchase item(s)" OR and "cart abandonment+cart abandonment item(s)" events.
Configure your mapping file (optional)
Acoustic Exchange can consume TSV, CSV, or batch JSON files. Other files in your specified cloud storage location are ignored. For Acoustic Exchange to be able to read and share the contents of those files, you must create a mapping file to map the data to a naming convention and syntax that Acoustic Exchange can read. There can only be one mapping file per bucket. However, if you need to change the type of data Acoustic Exchange pulls from your bucket, you can edit the mapping file at any time.
Note: If you do not create a mapping file, then you can upload batch event JSON files only. The events in the JSON file must be recognized Acoustic Exchange events.
Create your mapping file
Your mapping file must be in XML format and you must host it in your specified cloud storage location (for example, your Amazon S3 bucket), the same location as the data files that you want to share with Acoustic Exchange. When you create the mapping file, make sure to name it something memorable or significant. You will need the mapping file name during the endpoint registration process.
When you create a mapping file to map event data from a CSV file, it can look similar to this example:
<?xml version="1.0" encoding="UTF-8"?>
<UBX_EVENT_MAPPING dataFileFormat="CSV" sourceEvent="offerAccepted">
<UBX_EVENT sourceEvent="offerAccepted">
<code>offerAccepted</code>
<channel>Paid Media / AdTech</channel>
<timestamp sourceIndex="1" sourceType="timestamp" sourceFormat="yyyy-MM-dd HH:mm:ss"></timestamp>
<attributes>
<attribute>
<name>eventName</name>
<value>Accepted Offer</value>
<type>String</type>
</attribute>
<attribute sourceIndex="3">
<name>USERAGENT_TYPE</name>
<type>String</type>
</attribute>
<attribute sourceIndex="4">
<name>USERAGENT_FAMILY</name>
<type>String</type>
</attribute>
<attribute sourceIndex="5">
<name>USERAGENT_DEVICETYPE</name>
<type>String</type>
</attribute>
<attribute sourceIndex="6">
<name>USERAGENT_OS</name>
<type>String</type>
</attribute>
<attribute sourceIndex="7">
<name>LANGUAGE</name>
<type>String</type>
</attribute>
<attribute sourceIndex="8">
<name>GEO_CITY</name>
<type>String</type>
</attribute>
<attribute sourceIndex="9">
<name>GEO_CITYCONF</name>
<type>String</type>
</attribute>
<attribute sourceIndex="10">
<name>GEO_POSTAL</name>
<type>String</type>
</attribute>
<attribute sourceIndex="11">
<name>GEO_POSTALCONF</name>
<type>String</type>
</attribute>
<attribute sourceIndex="12">
<name>GEO_AREACODE</name>
<type>String</type>
</attribute>
<attribute sourceIndex="13">
<name>GEO_REGION</name>
<type>String</type>
</attribute>
<attribute sourceIndex="14">
<name>GEO_COUNTRY</name>
<type>String</type>
</attribute>
<attribute sourceIndex="15">
<name>GEO_GMTOFFSET</name>
<type>String</type>
</attribute>
<attribute sourceIndex="16">
<name>GEO_DMA</name>
<type>String</type>
</attribute>
<attribute sourceIndex="17">
<name>QUERYSTRING</name>
<type>String</type>
</attribute>
</attributes>
<identifiers>
<identifier sourceIndex="2">
<name>USERID</name>
<type>String</type>
</identifier>
</identifiers>
</UBX_EVENT>
</UBX_EVENT_MAPPING>
In the root element <UBX_EVENT_MAPPING>
, you define the input data file format and where the source event type can be found. Because the event mapping is based on the source event type, Acoustic Exchange needs to know where to get the source event type. If the data file format is UBXEventBatchJSON
(Batch event JSON payloads), then Acoustic Exchange reads the JSON field. If the data file format is TSV or CSV, the source event type can come from bucket name, file name, column name or column index.
Each <UBX_EVENT>
element represents the mapping from a source event type to an Acoustic Exchange event. It contains an <attributes>
block which represents mapping for the attributes and an <identifiers>
block which represents mapping for the identifiers.
Table 1. <UBX_EVENT_MAPPING>
Attribute | Description |
Accepted Value |
Example |
dataFileFormat |
Defines the input data file format. |
UBXEventBatchJSON TSV CSV |
<UBX_EVENT_MAPPING dataFileFormat="CSV"> |
dataFileHeader |
Defines whether the CSV or TSV file contains a column header. | True | False | dataFileHeader=”true” |
memberEventColumn | Defines where Acoustic Exchange can get the member event information. (Optional) |
|
memberEventColumn="{COLUMN_INDEX}" |
memberEventColumnIndex | Defines the index number of the column for the member event information. (Required if memberEventColumn is set to {COLUMN_INDEX}) | <Number> | memberEventColumnIndex="4" |
memberEventColumnName | Defines the name of the column for the member event information. (Required if memberEventColumn is set to {COLUMN_NAME}) | <String> | memberEventColumnName="memberFlag" |
memberEventColumnValue | Defines the value of the column for the member event information to indicate it's a member event. (Required if memberEventColumn is set) | <String> | memberEventColumnValue="M" |
sourceEvent |
Defines where Acoustic Exchange can get the event type in the source data. |
|
sourceEvent="{FILE_NAME}" |
sourceEventColumnIndex |
Defines the index number of the column for the source. | <Number> | memberEventColumnIndex=”3” |
sourceEventColumnName |
Defines the name of the column for the source event type value. | <String> | memberEventColumnName=”event” |
Table 2. <UBX_EVENT>
Attribute | Description | Accepted Value | Example |
sourceEvent |
Defines the source event name. This attribute looks up the event that is being mapped for the source event. | <String> | <UBX_EVENT sourceEvent="offerAccepted"> |
Table 3. <UBX_EVENT>
child notes
Attribute | Description | Accepted Value | Example |
<code> |
Defines the Acoustic Exchange event code. | <String> | <code>adImpression</code> |
<channel> |
Defines the Acoustic Exchange event channel | <String> |
|
<timestamp> |
Defines the mapping of the timestamp value. It converts the timestamp from the source format into format consumable by Acoustic Exchange. | Attributes:
|
<timestamp sourceIndex="1" sourceType="timestamp" sourceFormat="yyyy-MM-dd HH:mm:ss"></timestamp> |
<attributes> |
Defines the attribute mapping. It contains a list of <attribute> blocks. Each represents the mapping from a source attribute to an Acoustic Exchange attribute. |
Attributes:
Elements:
Entry: sourceValue defines the source value;
The node value defines the Exchange value. |
Maps the source attribute aa.productId to the Exchange attribute productid :
|
<identifiers> |
Defines the identifier mapping. It contains a list of <identifier> blocks. Each represents the mapping from a source identifier to an Acoustic Exchange identifier. |
Attributes
Element
Entry
The node value defines the Acoustic Exchange value. |
Maps from source identifier cid to the Exchange identifier connected_id :
|
Aggregated Events
For Exchange, aggregated events, such as cart purchase and cart abandonment events, are required to be sent with their corresponding item events (e.g. cart purchase item and cart abandonment item events) in a single event batch. Since in TSV/CSV files, one line represents a single event, we need a way to group multiple lines together to support the aggregated events. Such event groups can appear anywhere in the data file, however, events that belong to the same group must be together (sequential lines). Within the group, the first line should be the aggregated event, followed by the member (item) events. The member event line should have a dedicated column (defined by mapping header attribute memberEventColumn) to indicate this line is a member event (when the column value equals to what's defined by mapping header attribute memberEventColumnValue).
For example, in the following TSV file. we use the column "memberFlag" to indicate the member event line. The line is considered a member event line when the value is set to "M".
Identifier column | Other attributes column | sourceEventType | memberflag | |
1 | productView | |||
2 | abandonment | |||
3 | abandonmentItem | M | ||
4 | abandonmentItem | M | ||
5 | abandonmentItem | M | ||
6 | abandonment | |||
7 | abandonmentItem | M | ||
8 | pageView | |||
9 | productView | |||
10 | abandonment | |||
11 | abandonmentItem | M |
In the mapping file, we set the following in the <UBX_EVENT_MAPPING> element:
<UBX_EVENT_MAPPING dataFileFormat="TSV" sourceEvent="{COLUMN_NAME}" sourceEventColumnName="sourceEventType" memberEventColumn="{COLUMN_NAME}" memberEventColumnName="memberFlag" memberEventColumnValue="M" dataFileHeader="true">
When this data file is processed, line 2-5, line 6-7, line 10-11, each will be grouped together in separated event batches.