OpenAudience™ Match Sync Onboard
Last updated on October 19, 2020
contents
- Overview
- OpenAudience™ Match Sync Process
- File Guidelines
- Uploading Your Data Files
- Safe Data Handling
- OA Match Synch Sample File
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:
- The Marketer loads the Match Table file into a dedicated GCS or S3 bucket.
- OpenX matches Marketer Match Table file with OpenAudience™ Match table using supported match keys (see below).
- Marketer/OpenAudience™ Match Sync Table is established and refreshed regularly with new matched users and screens.
- 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.
| Data | Data 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 Key | • Mobile/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.
| Identifier | Formatting |
|---|---|
| Hashed Identifiers | • Prior 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 Identifiers | For 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 Name | Column Header | Field Guidelines | Hashing Requirements? |
|---|---|---|---|
| Partner User ID | partner_userid | Partner 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 Cookie | ox_cookie | OX 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 Identifier | idfa/gaid | Mobile Advertiser Device ID (Apple or Android). Do not alter or hash. Example: 00cb00da0-00b0-0000-0a00-00f0c000k80l | No |
| Hashed Email | email | Email 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: [email protected]>hash([email protected]) | Yes Sha-256 preferred Sha-1 accepted MD5 accepted |
| Phone | phone | Include 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 Name | fn | First 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 Name | mn | First 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 Name | ln | Convert 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 |
| Gender | gender | m or f | No |
| Address | address | Only 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 Address | address_full | Street 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 Combined | citystatezip | Combined 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 |
| City | city | Use full city names. City is all lowercase and spaces removed. Examples: S. San Francisco > southsanfranciscoCut & Shoot > cutandshootWinchester-on-the-Severn > winchesteronthesevern | No |
| State | state | Use 2-digit abbreviations. State is all lowercase and spaces removed. Example: California > ca | No |
| Postal Code | postalCode | Use a five-digit format Example: 94305 | No |
| Zip9 (Zip+4) | zip9 | Use 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 |
| Zip11 | zip11 | Use the eleven-digit format. Remove any punctuation. Currently not standard match key, can be included for testing purposes | Yes Sha-256 only |
| Country | country | Use ISA two-letter country code format. Example: US not USA | No |
| IP Address | ip_address | The IP address of the user’s screen. Example: 191.100.3.5Currently 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 Birth | birthyear | Use four digits: YYYY Example: 1976Currently not standard match key, can be included for testing purposes. | No |
| Month of Birth | birthmonth | Use 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:
- OpenX provides you with your own GCS bucket, a secure, private location for your files.
- OpenX will ask for the gmail address(es) of users that will have access to drop the files to the GCS bucket.
- Load files into the GCS bucket, split into 1GB increments.
- If possible, include an empty file indicating that the upload is complete.
- 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:
- 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.
- 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:
- List the Amazon S3 bucket
- Get the location of the bucket
- Read the objects in the bucket
- Additional Documentation
- S3 Bucket Location (for example,
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.