Link Search Menu Expand Document

PDF

OpenAudience™ Match Sync Onboard

OpenAudience

Marketers

Last updated on October 19, 2020


contents


Overview

An OpenAudience™ Match Sync enables Marketers to easily onboard their 1p audiences directly to OpenAudience™ for distribution on the OpenX Exchange, without having to go through a 3rd Party onboard platform.

After an OpenAudience™ Match Sync is established, Marketers can push 1p audience files to OpenAudience™ directly via the OA Direct Audience process, using a common identifier for matched users. The OpenAudience™ Match Sync can be refreshed regularly to ensure 1P audiences are kept up to date.

Once onboarded, Marketers can take advantage of 3000+ OpenAudience™ segments across Demographic, Contextual, Transaction and Behavioral categories to further customize and expand their 1P audiences before activation on the OpenX Exchange.


OpenAudience™ Match Sync Process

The OpenAudience™ match synch process is as follows:

  1. The Marketer loads the Match Table file into a dedicated GCS or S3 bucket.
  2. OpenX matches Marketer Match Table file with OpenAudience™ Match table using supported match keys (see below).
  3. Marketer/OpenAudience™ Match Sync Table is established and refreshed regularly with new matched users and screens.
  4. OpenAudience™ Match Sync Table used for direct onboarding of Marketer’s 1P audience files via OA Direct Audience process, to activate 1P Audiences on OpenX Exchange.

File Guidelines

Before uploading your data files, follow these guidelines for file content and format.


Protecting Users and Observing Privacy Laws

Make sure that your data does not include:

  • users outside of the United States
  • users under the age of 13 or any users from properties directed to children (as defined by the Children’s Online Privacy Protection Act)
  • users under the age of 16 located in California

Hashing is required for all data fields that identify a specific individual (personally identifiable information or “PII”).


Match Table Data Requirements

To create an OA Match Table Sync between your Match Table and OpenAudience™, every data row for a user should include, at minimum, a unique Partner User Id, and at least one Non-PII Match Key or at least one Hashed PII Match Key.

DataData Requirements
Partner User ID• Required field, should be first column of your Match Table file.
• External unique identifier, consistent across rows if a given user has multiple rows of data.
• Used as match key to onboard 1p audience files, after the OA Match Table Sync is established.
Non-PII Match KeyMobile/Tablet Advertiser ID (IDFA for iOS devices, GAID for Android devices, other operating systems not currently supported).
ConnectedTV/OTT Advertiser ID (IDFA for iOS devices, GAID for Android devices, other operating systems not currently supported).
OX Cookie (Note: Only if synched with OpenX Ad Exchange).
   Please notify your OpenX account manager to help enable the cookie synch between OpenX and your platform.
Hashed PII Match Key• Hashed email address
• Hashed phone number
• As many of the following as available:
   • Hashed first name
   • Hashed last name
   • Hashed address (street only)
   • Hashed full address (street and secondary, such as suite number)
   • Hashed city, state, and zip

Hashing and Primary Match Key Data Formatting

A hash function protects user privacy by making fields unreadable and irreversible while still allowing matching to occur. Prior to hashing a field, normalize it using the general rules below and the examples shown in Supported Data Fields.

IdentifierFormatting
Hashed IdentifiersPrior to Hashing:
   • Make all letters lower case
   • Trim & remove all spaces
For Phones: United States/domestic phone numbers should include 11 digits, including country code. Remove any additional hyphens & punctuation (-).
For Addresses: Follow CASS rules, using abbreviations for street suffix and secondary address designator.
• For Email Hashing:
   • Unsalted SHA-256 hashing preferred
   • Unsalted MD5 and Unsalted SHA1 hashing supported
Non-Hashed IdentifiersFor Mobile Advertiser Device Identifier (IDFA/GAID) only: Make all letters lower case and do not remove hyphens.

Note: OpenX does not match on hashed MAIDs/devices.

Data Format Requirements

Prior to uploading ensure that your Match Table file follows the guidelines below:

  • Ensure to include a header row with the exact header names as shown in the Supported Data Fields table below and linked OA Match Sync Sample File.
  • Ensure each data field is formatted and hashed (if required) correctly following guidelines specified.

Supported Data Fields

The following table lists the required names and guidelines for supported fields.

To see exactly how each field should be formatted, see OA Match Sync Sample File.

Click to expand supported data fields
Field NameColumn HeaderField GuidelinesHashing Requirements?
Partner User IDpartner_useridPartner provided unique user id.

Shared identifier between partner and OA platform, used as match key to onboard partner first party audience files for activation post universe match table sync.

Example: agencyid12345abcd
No
OpenX Synced Cookieox_cookieOX synched cookie from OpenX/Partner cookie sync.

Do not alter or hash before returning in the match file.

Example: 0bb00e00-0000-0c0a-0f00-0d0000aadd6d
No
Mobile or ConnectedTV Advertiser Device Identifieridfa/gaidMobile Advertiser Device ID (Apple or Android).

Do not alter or hash.

Example: 00cb00da0-00b0-0000-0a00-00f0c000k80l
No
Hashed EmailemailEmail must be lowercase with all leading and trailing whitespace removed prior to hashing.

If multiple emails per user, ensure each row has the same unique partner user id.

Example: MyIdentity@Doman.com>hash(myidentity@domain.com)
Yes

Sha-256 preferred

Sha-1 accepted
MD5 accepted
PhonephoneInclude only one primary phone number per user. United States/domestic phone numbers should include 11 digits, including country code. Remove any additional hyphens and punctuation.

Example: US: 1-415-100-1000 > hash(14151001000)
Yes

Sha-256 only
First NamefnFirst initial is acceptable.
Convert accented letters.

Examples: Ë = e, á = a.

Remove hyphens.

Do not combine first, middle, and last names in one field. First Name is all lower case.

Examples:
John > hash(john)
J.P. > hash(jp)
John-Paul > hash(johnpaul)
NOËL = hash(noel)
Yes

Sha-256 only
Middle NamemnFirst initial is acceptable.
Convert accented letters. Examples: Ë = e, á = a.

Remove hyphens.

Do not combine first, middle, and last names in one field. Middle Name is all lower case.

Examples:
P. > Hash(p)
Paul > hash(paul)
Yes

Sha-256 only
Last NamelnConvert accented letters. Example: Ë = e, á = a.

Remove hyphens.

Do not combine first, middle, and last names in one field. Last Name is all lower case.

Examples:
Smith > hash(smith)
Hyde-Smith > hash(hydesmith)
Smith, Jr. > hash(smith)
Yes

Sha-256 only
Gendergenderm or fNo
AddressaddressOnly street number, street name, street directional, street suffix, street post directional. Address is all lowercase and spaces removed.

Use standard CASS abbreviations for street post-directional. See the last column in https://pe.usps.com/text/pub28/28apc_002.htm

Examples:
100 Main Street > hash(100mainst)
100 South Main Street > hash(100smainst)
100-A S. Main St. > hash(100asmainst)
1001/2 Main Street Southwest > hash(10012mainstsw)
456B 7th Street > hash(456b7thst)
456B Seventh Street > hash(456bseventhst)
P.O Box 12345 > hash(pobox12345)
RR 1 Box 1.23 > hash(rr1box123)
123 South Main Street, Suite 200 > hash(123smainst)
Yes

Sha-256 only
Full Addressaddress_fullStreet number, street name, street directional, street suffix, street post directional PLUS secondary address, if available. Full Address is all lowercase and spaces removed.

Use standard CASS abbreviations for street post-directional. See the last column in https://pe.usps.com/text/pub28/28apc_002.htm.

Use standard CASS abbreviations for secondary unit designators. See https://pe.usps.com/text/pub28/28apc_003.htm.

Examples:
123 South Main Street, Suite 200 > hash(123smainstste100)
123 Main Str SW, Apartment 155 > hash(123mainstswapt155)

Note: If no secondary address is available, fill in the same content as the address field. Do not leave blank.
Yes

Sha-256 only
City/State/Zip CombinedcitystatezipCombined city state and zip with no punctuation. City is fully-expanded, two-letter state code, five-digit zip code. City/State/Zip is all lowercase and spaces removed.

Examples:
Akron, Ohio 34567 → hash(akronoh34567)
St. Louis, Missouri 76234-3423 > hash(saintlouismo76234)
Minneapolis-St. Paul, MN 01234-5678 > hash(minneapolissaintpaulmn01234)
Yes

Sha-256 only
CitycityUse full city names. City is all lowercase and spaces removed.

Examples:
S. San Francisco > southsanfrancisco
Cut & Shoot > cutandshoot
Winchester-on-the-Severn > winchesteronthesevern
No
StatestateUse 2-digit abbreviations. State is all lowercase and spaces removed.

Example: California > ca
No
Postal CodepostalCodeUse a five-digit format

Example: 94305
No
Zip9 (Zip+4)zip9Use a nine-digit format. Include five-digit zip code if no zip9 is available. Remove any punctuation.

Examples:
94305-1212 >hash(943051212)
02456 > hash(02456)
Yes

Sha-256 only
Zip11zip11Use the eleven-digit format. Remove any punctuation.

Currently not standard match key, can be included for testing purposes
Yes

Sha-256 only
CountrycountryUse ISA two-letter country code format.

Example: US not USA
No
IP Addressip_addressThe IP address of the user’s screen.

Example: 191.100.3.5

Currently not standard match key, can be included for testing purposes.

Example: 191.100.3.5 > hash(191.100.3.5)
Yes

Sha-256 only
Year of BirthbirthyearUse four digits: YYYY

Example: 1976

Currently not standard match key, can be included for testing purposes.
No
Month of BirthbirthmonthUse two-digits: MM

Currently not standard match key, can be included for testing purposes.
No

Column Delimiter, New lines, and Encoding

  • OpenX accepts files with a comma, tab, or pipe delimiter. Use the .csv extension in the file name.
  • Indicate new lines with LF (Unix) or CR+LF (Windows). OpenX does not accept any other line endings, such as Carriage Return (CR).

    NOTE

    To avoid issues with exporting from earlier versions of Excel for Mac, use the Windows CSM format when available.

  • OpenX supports UTF-8 and UTF-16 encoding. Files without a byte-order mark (BOM) are assumed to be UTF-8.
  • If you zip the file please use the gzip format.

Uploading Your Data Files

You can upload data files to GCS or S3 buckets.


Uploading Files to a GCS Bucket

To upload your files to a GCS bucket:

  1. OpenX provides you with your own GCS bucket, a secure, private location for your files.
  2. OpenX will ask for the gmail address(es) of users that will have access to drop the files to the GCS bucket.
  3. Load files into the GCS bucket, split into 1GB increments.
  4. If possible, include an empty file indicating that the upload is complete.
  5. Alert your OpenX contact that the file has been loaded to your GCS Bucket.

Uploading Files to an S3 Bucket

To upload your files to an S3 bucket:

  1. OpenX is also able to pick up files from your S3 bucket and transfer them to Google Cloud Storage.
    • The S3 bucket is scanned daily for any file changes and downloads new files.
  2. Please generate and provide OpenX with the following items:
    • S3 Bucket Location (for example, s3://client/)
    • Access key ID
    • Secret access key:
    • The AMS IAM user must have the following permissions:

Safe Data Handling

Your data files always remain in your own GCS bucket, separate from all other partners’ data and only accessible to entrusted members of your organization who have your GCS bucket account credentials. OpenX will generate an OpenX ID unique to your organization for each recognized user. You are responsible for maintaining the security and confidentiality of your GCS bucket account credentials. If you believe credentials have been compromised, please notify OpenX immediately.


OA Match Synch Sample File

Use the following sample file to ensure that your Match Table file follows data format requirements.

You can also download this spreadsheet as .xlsx.