Mobile Direct Ingest
Direct ingest enables mobile data providers to transfer mobile user attributes to the platform based on mobile advertising IDs (also known as device IDs when derived from mobile apps) and makes the collected mobile user categories rapidly available for purchase in the Oracle Data Marketplace.
With direct ingest, you send an offline file to the Oracle CX Advertising platform (formally known as the Oracle Data Cloud platform) with your mobile IDs and associated mobile user attributes. The platform then maps your mobile user attributes into categories within your taxonomy and simulates tag calls on the mobile users in the offline file to instantly build inventory in your new mobile categories. The following diagram illustrates the direct ingest process:
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. If you have not signed the agreement, you can only create containers that are configured for non-EU countries. This means that a blacklist must include the EU region or countries and a whitelist may not; otherwise, the Containers UI/API will display an error. By default, new containers will blacklist the EU. Contact your Oracle account representative to obtain and sign the agreement.
Create a site ID
Site IDs are used to manage your data in the Oracle CX Advertising platform. Classification rules use the site ID to map your mobile user attributes to categories in the taxonomy. To format your offline file correctly, you need a site ID.
Site IDs are generated when you create containers. You can create containers in the UI or with the containers API.
Contact Oracle CX Advertising
Contact your Customer Success Manager to request direct ingest access for MAIDs. You will need to provide your partner name, partner ID, the site ID, and which ID type for which you are onboarding (ADID or IDFA). You must also specify a method for classifying user country locations.
The recommended practice is to include a Country column in the offline file where you specify countries. If you do not or cannot provide country data, the platform uses the country information in the user profile. If no profile or no country exists, the results depend on whether you are a DMP client or a data provider.
- DMP Clients.The country is set to unspecified. In this case, you cannot use country filtering in Audience Builder to target these users.
- Data Providers: Data cannot be onboarded.
Creating the offline file
An offline file contains the mobile user attributes that you want to send to the Oracle CX Advertising platform. It must be a compressed plain text file that contains one line per user. Each line represents a unique user and must include the following tab-delimited fields:
- Device ID: Each offline file may only contain a single device ID type for the user. If you are sending a single user's attributes on IDFA and ADID devices, you must include them two separate offline files. Do not repeat device IDs within a single file. Otherwise, the mobile user attributes of the earlier ingest key instance will be overwritten by the more recent instance. Each device ID can have a maximum of 40 bytes of data.
- Country code: ISO 3166-1 alpha-2 country code of the user. This determines into which countries users are classified. This enables country filtering to be used in Audience Builder to target these users. If you do not include a country column in your offline files, you must have specified a default country into which all users are classified.
- Key-value pairs (KVPs): Pipe-delimited KVPs for mobile attributes and optional semicolon-separated app IDs of the user's apps.
Each line, including the last one, must be terminated by an LF (Unix style end-of-line characters).
The following sample demonstrates the format of an offline file that contains a set of US mobile users, their demographics (bk112 represents age, bk111 is gender, and bk115 is children), and the Android apps they used ("MyApp.com", "YourApp.com):
awytM3DD US BK112=25|BK111=M|BK115=2|appid_android=com.myapp;com.yourapp
3d5zYU7i US bk112=22|bk111=F|bk115=1|appid_android=com.myapp
yE8Sy49V US bk112=36|bk111=F|bk115=1|appid_android=com.yourapp
6xkDV7yl US bk112=42|bk111=F|bk115=3|appid_android=com.myapp;com.yourapp
Offline file requirements
| Requirement | Example | Description | |
|---|---|---|---|
| Device types | adid |
The platform supports the use of the following device ID types:
|
|
| Country codes | US | The two-letter ISO 3166-1 alpha-2 country code of the user. | |
| Mobile attributes | BK111 | The keys for mobile attributes should use a 2-character company name and an arbitrary 3-digit category format. To create a key for a given attribute, you should abbreviate your company name to two letters and then append an arbitrary three-digit number to your company name. | |
| App IDs | appid_ios=184882215;489801252 |
(Optional) A semicolon-separated list of the user's app IDs:
|
|
| File name | ExampleCompany_15415_adid_2017-04-26.gz |
The file name of the offline file must include the following underscore-separated parts in the specified order:
The file name may not contain spaces. |
|
| Mamimum line size | 256 data items; 32KB. | ||
| Character encoding | UTF-8 | ||
| Compression | .gz | The file must be compressed using .bz2 or .bzip2 compression and can have the following file extensions: .bz2, .bzip2, .gz, or .gzip. | |
| 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. |
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 Oracle CX Advertising platform begins onboarding your offline file. If validation fails, you will receive an automated notification with the error details.
The following example illustrates a plain text trigger file that contains the following row-delimited fields:
FILE=BlueKai_15415_idfa_2017-04-26.gz
SIZE=367
MD5SUM=a10edbbb8f28f8e98ee6b649ea2556f4
Trigger file requirements
| Requirement | Example | Description |
|---|---|---|
| FILE | FILE=BlueKai_15415_idfa_2017-04-26.gz | The file name of the offline file to be uploaded, where FILE is the key and the file name is the value. This row is optional if the trigger file name is identical to its offline file but with the .trigger file extension. This row is required if your offline file has a different name than its trigger file or if you are triggering multiple offline files (not recommended). |
| SIZE | SIZE=367 | (Recommended) The size of the offline file in bytes, where SIZE is the key and the value is expressed as an integer
For details, see calculating the offline file size. |
| SHA256SUM | SHA256SUM=a10edbbb8f28f8e98ee6b649ea2556f4 |
MD5 hashes are also supported, but for security reasons Oracle recommends that you not use MD5. |
| File name | BlueKai_15415_idfa_2017-04-26.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 | Uncompressed plain text | |
| Character encoding | UTF-8 |
Classifying your mobile data
Create a data map that outlines the phints (key-value pairs representing user attributes) you will pass in your offline file and send it to your account manager. The Oracle CX Advertising platform uses your data map to create classification rules that map your phints to categories in your taxonomy.
Your data map must include the following information:
- The set of keys used in your phints
- The possible set of values for each key, and associate them with human readable category names, if necessary
- The hierarchical relationships, if any, between a set of keys
For example, consider an auto shopping site that collects the makes and models of cars for which users have demonstrated intent to purchase. The key-value pair for the make node would have the following syntax:MA100=[VALUE]. The example key-value pairs for this node could 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 Oracle CX Advertising platform would need 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 example site:
| Key | Key translation | Value | Value translation (category) |
|---|---|---|---|
| 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 |
Uploading your offline file
After you have created your offline file and trigger file, you can upload them to the Oracle CX Advertising SFTP servers. The platform provides you with a directory, user name, and password for securely uploading your offline files to the Oracle upload server (sftp.bluekai.com).
The platform validates your offline file and then begins onboarding your data. Your users’ mobile attributes are mapped to categories in your private taxonomy via classification rules written by Oracle CX Advertising. Tag calls are simulated on the users to build inventory in the mobile categories. Your offline data will data will be completely onboarded and ready for activation within 24 hours.
Important: Each time you upload a file it simulates a user being seen online and resets the expiration of the user's mobile ID.
To upload your offline file:
- Email a spreadsheet sample of your offline file (minimum of 100 records) to your account manager. This enables us to verify that your offline file is configured and named correctly.
- Upload a small test file with a minimum of 1,000 records so that Oracle CX Advertising can verify your file’s format and provide you with any required changes. When Oracle approves your sample file, you may begin uploading your complete offline file.
- Upload your offline file.
- After the offline file has been completely uploaded, upload the trigger file. A script will automatically be called to download the file into the Oracle CX Advertising platform offline match rules-based classification system. An event will be added to your account activity journal in the platform confirming that the upload was successful.
- Use the account activity journal to track the progress of your offline onboard.
The account activity journal lists 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 Pre-processing Processing starts Displays the file name Processing ends Displays the file name, status, and duration Ingest Ingest starts Displays the file name Ingest ends Displays the file name, status, and duration Transfer to data centers (DC) DC storage starts Displays the file name and data center DC storage ends Displays the file name, data center, status, and duration - Your offline data is parsed and saved in your profile store.
- Your processed offline files are archived and then removed from the Oracle CX Advertising upload server 30 minutes after the processing is complete. Archives are kept for 90 days.
Delivering mobile data to data buyers
After BlueKai ingests your mobile user attributes, they can be delivered to Mobile data buyers. Mobile data buyers can use your data to offer marketers and advertisers the ability to target Mobile app users based on their online behavior. For more information on how your mobile user data is delivered to data buyers, see accepting mobile advertising IDs in your media platform.
FAQs
The following FAQs address how to ensure you are getting accurate inventory numbers (data buyers) and your data is being classified correctly (data providers).
As a data buyer who is creating audiences, how do I ensure that I am getting inventory that is accurate?
The Oracle CX Advertising platform onboards mobile device IDs through direct ingest and displays the inventory within the platform UI. The default settings includes an aggregate of all devices and ID types. To view desktop or mobile only inventory, see the ID sources section of the audience builder documentation. For more details on accepting device IDs, see accepting mobile advertising IDs in your media platform.
As a data provider onboarding data with direct ingest, how can I ensure that my mobile data is accurately classified?
Create a site ID specifically configured for onboarding mobile data with direct ingest. This ensures that mobile inventory is not commingled with desktop inventory.