Offline Match Integration
You can use offline match integration to activate your offline data in the Oracle Data Cloud platform. With offline match, you can onboard data from a data warehouse, a customer relationship management (CRM) database, or an email-based offline source into your Oracle Data Cloud platform. You can then target, optimize, analyze, and model your users based on their offline attributes.
Offline match integration enables you to:
- Expand your first-party data set: Add new first-party categories to your taxonomy based on your user’s offline attributes.
- Rapidly activate offline data: Within 24 to 48 hours of uploading your offline file, you can target, optimize, and analyze your users across multiple media execution platforms based on their offline attributes.
- Extend reach using look-alikes: Use built-in analytics and modeling to find high-value users that behave like your top-performing offline users.
Data Providers Onboarding EU Data. To onboard data for user profiles located in the European Union (EU), you must have signed Oracle's General Data Protection Regulation (GDPR) Consent agreement. Contact your Oracle Account Representative to obtain and sign the agreement.
Offline onboarding
To ingest your offline data:
- Send your online match keys (for example, hashed email addresses used to log into your website) to the platform via an ID swap.
- Create an offline file that contains the same match keys and your users’ offline attributes.
- Classify your offline data.
- Send your offline file to the platform.
- Monitor your offline data ingest.
After you send your offline file, the platform will use your match keys and classification rules to map your users’ offline attributes into categories in your private taxonomy. Your offline data will be onboarded and ready for activation within 24 hours. The following diagram illustrates how your offline data is ingested into the Oracle Data Cloud platform:
Maximize your offline onboard
To onboard the highest possible amount of your offline data, we recommend that you do an offline onboard with a third-party match partner and a direct onboard with the Oracle Data Cloud platform through our online-to-offline matching solution: match multiplier.
- Third-party match integration: The Oracle Data Cloud platform has direct integrations with the following third-party match partners: , LiveRamp, i-Behavior, and Neustar. The third-party match partner will be able to match a portion of your offline file.
- New third-party offline match partners: If you are using an offline match vendor that does not have an ID swap configured with the Oracle Data Cloud platform, have your offline match vendor perform a direct integration by sending match keys to the platform.
- Third-party match partners: If you have not set up an ID swap, follow the steps in sending your match keys. Send your offline file to the platform to complete the offline match integration for platform clients.
- First party-match integration: Match multiplier will provide you with incremental matches on top of those provided by the third-party match partner.
Sending your match keys to the Oracle Data Cloud platform
A match key is any unique user ID (UUID) that you can use to identify your users in both the online and offline spaces.
Important: No personally identifiable information (PII) may be sent to the platform or stored in the Oracle Data Cloud platform. All IDs derived from PII must be hashed in the browser or on your servers before being sent to the Oracle Data Cloud platform.
Some of the UUIDs that can be used as match keys include:
- Oracle hashed IDs (oHashes): SHA-256 hashed email addresses or phone numbers that have been automatically generated from raw personally identifiable information (PII) using Oracle Data Cloud code
- Encrypted hashed UUIDs: Encrypted hashed email addresses, phone numbers, physical addresses, and client account numbers
- Encrypted Oracle Data Cloud UUIDs (BKUUIDs): Encrypted versions of the 16-character alphanumeric IDs used in the Oracle Data Cloud platform to anonymously and uniquely identify users. You may have access to encrypted BKUUIDs if you ID swap with the platform to receive data using server data transfer (SDT).
- IP addresses: Collect the user's IP address from the IP header and send it as a match key.
To send your online match keys to the platform, you need to place a Oracle Data Cloud core tag or an ID swap tag (a 1x1 image pixel) on your site. When the platform receives your match keys, it will synchronize them to the network of user profiles that are linked together in the Oracle ID Graph (OIDG), which is used to manage IDs and user attributes for all Oracle Data Cloud customers.
The Oracle Data Cloud core tag is the standard implementation for integrating with the platform. It contains HTML code and built-in JavaScript functions for sending match keys and user attributes to the platform. It can be deployed directly on your site or in a tag management system. The ID swap tag is typically used in environments that require pixels for making tag calls, such as in display media.
After you deploy the Oracle Data Cloud core tag or ID swap tag on your site and your offline configuration is complete, your Solutions Consultant will provide you with an SFTP directory, user name, and password for uploading your offline files.
Creating your offline files
To send your offline data to the Oracle Data Cloud platform, create the following files:
- Offline file: Contains your match keys and offline user attributes. You must completely upload this file before uploading the corresponding trigger file.
- Trigger file: Contains the name, size, and SHA-256 checksum of your offline file. It is used to validate the transfer of your offline data.
Creating the offline file
An offline file is a compressed, tab-separated value (TSV) file that contains the offline user attributes that you want to onboard into your DMP. Each line in the offline file represents a unique user. The match keys for the user are included in separate columns; another column contains a pipe-delimited list of key-value pairs for the user’s offline attributes.
Important: Do not repeat match keys in the offline file or the offline user attributes of the earlier match key instance will be overwritten by the more recent instance.
A key typically represents a distinct user attribute, such as bk111 for gender, that corresponds to a field in your CRM database. Use different keys to represent different user attributes.
The format of the keys should be a 2-character company name followed by a 3-digit category identifier, such as BK112 for age.
The value may be expressed as a human readable name or as a numerical code. The value itself must not contain any pipe characters (|) because they are used as delimiters between values in the offline file.
Sample offline file showing five lines with two tab-separated columns: match keys and pipe-delimited user attributes:
awytM3DD bk112=25|bk111=M|bk115=23d5zYU7i bk112=22|bk111=F|bk115=1yE8Sy49V bk112=36|bk111=F|bk115=16xkDV7yl bk112=42|bk111=F|bk115=3Dh77UNpg bk112=37|bk111=M|bk115=2
Using IP address-based matching
IP address-based matching provides a useful, universal, match key across an array of connected devices, such as desktop, mobile, and connected TV. Multiple devices in a home or office network may be accessing the internet using the same public IP address, so IP matching allows you to match attributes across multiple devices and derive location-, environment-, and behavioral-based attributes.
Onboarding IP-based data requires an additional match key to be stored and processed as follows:
- Collection: The IP address is automatically passed in the header of your tag. It can be collected without having to implement any additional tags or code on your site.
- Storage and data onboarding: You can send an offline file to the platform that includes raw IP addresses and phints. The raw IP addresses are read from the file, encoded, and stored in the Oracle Data Cloud offline database. When it receives a tag call, the platform checks whether the IP address passed into the IP header matches the encoded one in the offline database. If there is a match, the offline data is onboarded and linked to the user's Oracle Data Cloud cookie ID (BKUUID) and the IP address. In cases where multiple IP addresses are collected for a user, lookups are performed for each IP—but only the most recently retained IP is matched.
- Delivery: The Oracle Data Cloud platform may deliver user data to media execution platforms that is linked to raw IP addresses. For a given BKUUID, up to the last 40 hashed IP addresses may be linked.
- Privacy: You can send any IP address for ingestion using a privacy-safe implementation that supports matching, storing, and delivery. Oracle adheres to standard data retention policies when storing this data within a user cookie and will reasonably ensure that partners receiving the data will propagate Oracle retention and opt-out policies. Internationally, IP addresses may be considered PII, so some clients may not want to participate in data delivery.
- Reporting: You can use the inventory trend report to review the matched inventory for billing purposes. If you use multiple match partners, contact your Customer Success Manager or Solutions Consultant to discuss special exclusions that can be configured for you.
To use IP addresses as the match key, add them to the offline file. If you previously sent offline files to the platform, notify your Customer Success Manager or Solutions Consultant that you are going to be passing IP addresses in your offline file. Oracle will update your offline onboard configuration so the system knows to look for IP addresses in your offline file.
Create an offline file that contains IP addresses and corresponding attributes. The following sample offline file contents show two tab-separated columns: IP addresses and pipe-delimited user attributes.
100.87.5.202 bk112=25|bk111=M|bk115=2148.87.67.202 bk112=37|bk111=M|bk115=2
Using oHashes as match keys
You can convert your users' email addresses and phone numbers into anonymous SHA-256 hashed IDs called "oHashes" and then include them in your offline file as a match key.
If you previously sent offline files that used UUIDs and you now want to use oHashes for match keys, include both your UUID and oHash in separate fields.
To use oHashes for the match key in your offline file:
- Notify your Customer Success Manager or Solutions Consultant that you are going to be passing oHashes in the offline file and which oHash you will be passing: SHA-256 email (
e_id_s) or SHA-256 phone (p_id_s). Your offline files may only include a single oHash type. Oracle will update your offline onboard configuration so the system knows to look for oHashes in your offline file. - Use Python, Java, or Ruby
- Format an offline file containing oHashes and the pipe-separated list of key-value pairs representing offline user attributes. The following example demonstrates a line of an offline file that uses oHashes as the match key:
j3qfe13d964235c175626e16e3e4c3eb0de71a4d17cad39733dc5e65a585127c bk112=25|bk111=M|bk115=2
Offline file format
The following table lists the required format, name, type, and size of the offline file:
| Requirement | Example | Description |
|---|---|---|
| File contents | awytM3DD bk112=25|bk111=M|bk115=2
|
The offline file must be a plain text file that contains one line per user with each line including the last terminated by a LF end-of-line character. Each line must include the following tab-delimited fields:
|
| File name | Partner_siteID_YYYY-MM-DD | The offline file must include your partner name, the site ID of the container, and the date. If you are sending multiple files, use a timestamp instead of the date. The file name must not contain spaces. Third-party offline match partners must include the client’s name in the file name, for example: partner_client_siteID_YYYY-MM-DD. |
| Maximum line size | 256 data items; 32KB. | |
| Character encoding | UTF-8 | |
| File type | .bz2 (or .gz) | The file must be compressed using bzip2 or gzip compression and can have the following file extensions: .bz2 or .gz. Uncompressed files will be rejected and deleted from the file share. |
| Minimum size | >50 MB | If you plan to send multiple small files, combine them into one larger file. For example, combine ten 20 MB files into one 200 MB. The ideal size is about 1 GB. 50 MB is acceptable if you only have that much data, but at least 100 MB is recommended. |
| Maximum size | ≤ 50 GB | The maximum file size is 50 GB, but you can split a large file into multiple smaller files. |
Sending updated offline files
You can continuously send updated offline files to the Oracle Data Cloud platform to onboard new users and new offline attributes for existing users.
Important: Include all attributes when sending offline files.
To onboard new offline attributes for existing users, add the new attributes to the existing pipe-delimited list of attributes for the users in your offline file. You must preserve all existing offline attributes for users in your offline file, because the current offline user attributes saved in the platform are overwritten with the attributes listed in your new offline file.
Creating the trigger file
A trigger file specifies the size, name, checksum, and optionally the number of records in your offline file. It is used to verify that all the data in your offline file was successfully transferred, without any corruption. If validation is successful, the platform will begin onboarding your offline; if validation fails, your account manager will contact you and explain the errors.
Do not upload the trigger file until its corresponding offline data file has been completely uploaded.
Trigger file format
The following table lists the required format, name, type, and size of the trigger file:
| Requirement | Example | Description |
|---|---|---|
| Format | FILE=partner_siteID_YYYY-MM-DD.gz
|
The file contains the following row-delimited fields:
|
| Name | PartnerName_SiteId_YYYY-MM-DD.gz.trigger
|
(Required) The trigger file must have the same name as the offline file, but with the .trigger file extension appended. The file name must not contain spaces. You can optionally use the FILE row to specify a different file name if you cannot use the same name as the offline file (not recommended). |
| Type | plain text | Do not compress the trigger file. |
Calculating the offline file size
You can use any tool that calculates the size of a file in bytes. Operating system include utilities for this purpose. For example, on UNIX platforms, you can enter the following at the command line:$ ls -l fileName
The command returns information about the file, including its size. For example, if the following information is returned, the file size is 367 bytes.
-rw-rw-r-- 1 user user 367 Feb 6 16:00 a.gz,
Calculating the offline file SHA-256 checksum
You can use any tool that is based on SHA-256 to calculate the checksum of the offline file you are uploading. Most operating systems include built in command-line utilities for this purpose. For example, on Linux you can enter the following at the command line:
$sha256sum fileName
Classify your offline data
To import your offline user attributes into the Oracle Data Cloud platform:
- Create a data map that outlines the keys and values you are passing to the platform.
- Create categories and classification rules that map the user attributes in your offline file to your taxonomy in your DMP.
Creating a data map
Create a data map to organize your offline user attributes and facilitate the classification process.
The data map outlines how you want to organize your offline user attributes in your taxonomy. It also functions as a checklist that you can use to ensure that you’ve created all the necessary categories and classification rules for ingesting your offline data. If you are using Oracle services to classify your offline data, the data map is required and should:
- Define the set of attribute keys used in your offline file.
- Define the possible set of values for each attribute key and associate them with human readable category names.
- Define the hierarchical relationships, if any, between a set of attribute keys.
For example, consider an auto shopping site that collects the makes and models of cars that users have shown an intent to purchase. The key-value pair for the Make node would have the following syntax: MA100=VALUE. Key-value pairs for this node might be as follows:
- MA100=Honda
- MA100=Acura
- MA100=Toyota
The key-value pair for the Model node would have the following syntax:MA110=[VALUE]. Based on the previous example Make nodes, example key-value pairs for the Model node could be as follows:
- MA110=Accord
- MA110=Civic
- MA110=TL
- MA110=TSX
- MA110=Corolla
- MA110=Camry
If the values for the makes were encoded (for example, you pass 23098, 21409, 57983 instead of Honda, Acura, and Toyota), the platform needs human readable category names for these encoded values. For example, the following translations could be used:
- MA100=23098 ->Honda
- MA100=21409 ->Acura
- MA100=57983 ->Toyota
The following data map could then be created for this site:
| Key | Key translation | Value | Category name |
|---|---|---|---|
| MA100 | Make | Honda | Honda |
| MA100 | Make | 21409 | Acura |
| MA100 | Make | 57983 | Toyota |
| MA110 | Make>Model | Accord | Honda>Accord |
| MA110 | Make>Model | 89065 | Honda>Civic |
| MA110 | Make>Model | TL | Acura>TL |
| MA110 | Make>Model | TSX | Acura>TSX |
| MA110 | Make>Model | Corolla | Toyota>Corolla |
| MA110 | Make>Model | Camry | Toyota>Camry |
Creating categories and classification rules
A category is a collection of users that have the same attribute (for example, smartphone users). Classification rules map the user attributes extracted from your offline file to categories in your DMP taxonomy.
Consider a user that has purchased a smartphone from a brick and mortar store. The offline file could have a "purchase=smartphone" attribute for this user. When this offline attribute is imported into the Oracle Data Cloud platform, it can be mapped to a "Past Purchases > Smartphone" category in your taxonomy via a classification rule that states "if purchase is smartphone, then the add the user to the Smartphone category.
The Oracle Data Cloud platform UI includes the Taxonomy Manager for creating your categories and rules. Alternatively, you can use the category and rule APIs to programmatically create categories and rules. To have the Oracle Data Cloud platform build your taxonomy, contact your Customer Success Manager or Solutions Consultant.
Upload your offline file
After you create your offline files and the platform has classified your offline data, you can upload your offline file and corresponding trigger file to the Oracle SFTP servers. Use the SFTP directory, user name, and password provided by Oracle to upload your offline files.
To upload your offline file:
- Upload a small test file with a minimum of 1,000 records so that Oracle Data Cloud can verify your file’s format and provide you with any required changes. After your sample file is approved, you can upload your complete offline file.
- Upload your offline file (or files if you had to create separate smaller offline files).
- After the offline file upload is completed, upload the trigger file. The file is then sent to the platform’s offline match rules-based classification system and your account manager is notified.
- The Oracle Data Cloud platform validates your offline file and begins onboarding your data. The match keys in the offline file (the same keys you sent to the platform in your ID swaps) are used to link your users’ online profiles (BKUUIDs) with their offline attributes. Your users’ offline attributes are then mapped to categories in your private taxonomy using classification rules written by Oracle Data Cloud. Your offline data will be ready for activation within 24 to 48 hours.
- Use the account activity journal to track the progress of your offline onboard. It will list the following events:
Step Event Journal message Verification Offline File Verified Displays the file name, status, file size, number of records, and checksum. Offline File Message Displays any messages regarding errors with missing fields or if the size of the file does not match the size specified in the trigger file.
Ingest Ingest Starts Displays the file name. - Your processed offline files are archived and kept for 90 days.
Monitoring offline data ingest
After the platform onboards your offline file, user data should begin flowing into the categories in your taxonomy. To verify that your data is being collected and classified correctly and that your offline file is generating the expected amount of inventory:
- Check if your inventory is growing. Use the inventory trend report to verify that the amount of inventory per category is increasing daily.
- Check your 30-day inventory. Use the Audience Builder in the Oracle Data Cloud platform to view the estimated number of unique users in your categories based on current configurations.
- You can use the categories API to programmatically check your inventory of your unique users.