Send feedback on this topic

Containers API

You can implement the Oracle Data Cloud containers web service to create and manage the individual sites in the Oracle Data Cloud platform. Creating a container generates a site ID, which is a unique ID for managing a site. Your DMP can have multiple containers, and each container will be associated with a unique site ID. The container and site ID are used for ingesting data into the Oracle Data Cloud platform and delivering data back to your site.

Note: Users no longer create campaigns in the Oracle Data Cloud platform UI. The campaign workflow is now part of the audience workflow. The platform still uses campaigns to manage audience data delivery however. They are created automatically when a UI user delivers an audience. In the APIs, you create and use campaigns as before.

In this topic  

Explore the API

The embedded I/O doc below enables you to explore the API. The I/O  doc explains the parameters for each method and provides templates for your calls. You cannot make live API calls from the tool, however.

Open the link below in a new tab to see the I/O doc in a three-pane format.

containers2.docs.apiary.io/

For help with this API, contact My Oracle Support (MOS).

Service URI

The URI for the containers API is:

services.bluekai.com/Services/WS/sites

Related API calls

Here are the API calls you will typically make after you use the containers API:

Post-containers API call Use Case
Categories API Independently add first-party categories to your private taxonomy that represent the user attributes being collected with your container
Rules API Independently create classification rules that map the user attributes collected by your container with your categories.
Schedules Specify where, when, and for whom third-party tags are fired from a container.

Use cases

Using the container and site ID for data ingest

You can use a container and its site ID to transfer user data into the Oracle Data Cloud platform.

A site ID is a unique identifier that enables your site to be managed in the Oracle Data Cloud platform.

You can create a container with the containers API and then use the container tool in the platform UI to add the JavaScript and HTML tag code. The code collects data from your site and transfers it to the platform. The data may be classification attributes or unique user IDs (UUIDs) that are used for ID swapping. The container is required for all data ingest methods:

Data Providers Onboarding EU Data. To ingest 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, but you make a Containers API POST or PUT request with the container configured for one or more EU countries, the Containers API will return an error and your container will not be created. Contact your Oracle Account Representative to obtain and sign the agreement.

Using the container and site ID for data delivery

You can use your site ID to deliver user data.

You can create a container with the containers API, insert the generated site ID into your regex pixel if you are delivering data via Server Data Transfer, and then use the pixel URL API to associate your campaigns with a destination.

You can also use a container with a JSON Return tag type to deliver your campaign data directly to the Web page that is hosting the tag.

GET response summary

The containers API GET request returns a container or a list of containers.

Property Type Description
allowed_buyers object If transaction_scope is set to "permissioned", this object lists the id and name of the buyers that may win on this site; otherwise, this is an empty list.
  • id (integer): The unique ID assigned to the partner's DMP
  • name (string): The name associated with the partner's DMP
analytics_only boolean Indicates whether the site is used for analytics only (true) or just for data collection (false)
country_list_type enum Indicates whether the countries in the blocked_countries list are in a WHITELIST or BLACKLIST. The default is BLACKLIST.

blocked_countries list A list of the two-letter ISO 3166-1 alpha-2 country code of the countries for which data collection is whitelisted or blacklisted based on users' IP addresses. Netherlands (NL) is blocked by default for new containers. If you use a whitelist, this field must contain at least one country.

In the future, this field will be renamed to country_list to better reflect its functionality.

created_at date A timestamp indicating when the site was created.
data_transfer_boost_enabled boolean Specifies whether the container tag is re-fired every n seconds after the initial page load while the user is still on the page (true). This enables you to increase the number of third-party pixels that can be fired from the container, while exceeding the auction slot limit, but without affecting the performance of your page. The container tag can be re-fired a maximum of 15 times. The frequency in which the container tag is re-fired is based on the data transfer interval.

For example, if you set the default auction limit to 10, enable data transfer boost, set the data transfer interval to 7 seconds, and you add 30 third-party pixels to the container, the following will occur:
  1. When the page is initially loaded, the first 10 third-party pixels are fired.
  2. After the platform receives a DomReady event indicating that the page has completed loading, a 7-second countdown begins.
  3. If the user is still on the page after the countdown, the next 10 third-party pixels are fired. The next 7-second countdown begins.
  4. If the user is still on the page, the last 10 third-party pixels are fired.
By default, data transfer boost is enabled for new containers (true).
data_transfer_boost_interval int Specifies how frequently (in seconds) the container tag is re-fired if you set the data_transfer_boost_enabled flag to true
data_transfer_limit_range int The maximum number of slots available in the container for firing image tags. For data providers, this is the number of slots available for selling data or executing an ID swap. For DMP clients, this is the number of slots available for delivering first-party data to partners.
group_id integer The unique ID assigned to the site's group. A group contains both the desktop and mobile versions of the site.
id integer The site ID generated when the container was created. This is a unique identifier used to manage your individual Web sites (for example, if you have separate Web sites for different countries).
name string The name of your site
partner object An object containing your partner-based id and name.
  • id (integer): The unique ID assigned to your Oracle Data Cloud platform instance.
  • name (string): The name associated with your Oracle Data Cloud platform instance.
private_data boolean Indicates whether the data collected from your site is private use and cannot be sold to any partner that you have not whitelisted (1), or it can be sold to any partner in the public Oracle Data Marketplace (0)
redirect_domains array Specifies a list of valid URL strings used to whitelist domains to which the site can redirect. Oracle Data Cloud domain calls (tags.bluekai.com) that include redir key-value pair parameters are evaluated against this site domain whitelist before they are permitted to redirect.
Example: "redirect_domains" : ["www.google.com", "www.facebook.com"]
transaction_scope string Indicates which of your whitelisted buyers can win on this site. This may be one of the following values:
  • all: All of your whitelisted buyers can win on this site.
  • permissioned: Only the buyers specified in the allowed_buyers parameter can win on your site.
  • self: Only your campaigns can win on your site.
  • none: No campaigns can win on this site. This includes campaigns in your own partner seat. This is useful for onboarding offline data or other scenarios where the site needs to be used exclusively for a specific purpose.
type string The type of site, which may be either 0 for desktop or 1 for mobile
updated_at date A timestamp indicating when the site was last modified

Updating the tag redirect domains whitelist

The redirect_domains property includes the container's tag redirect domains whitelist. You can modify the attached sample_containers_redir.py Python script to update the container's whitelist by replacing the following placeholders with the correct values for your use case:

The curly braces ({}) in the script indicate placeholder values that you need to replace.

The script makes a GET request to the containers API to pull your site details and then makes a PUT request to update the site with the redirect domains that you entered.

Updating blocked countries

You can update the countries from which data collection is blocked using the containers API. To do this, make a PUT request with the site ID to be updated in the URL, and the country_list_type set to WHITELIST or BLACKLIST depending on the desired configuration, and the list of two-letter ISO 3166-1 alpha-2 country codes to be blocked in the blocked_countries field within the JSON body. The following code example demonstrates how to create a container that blocks data collection in the EU (note that curly braces {} indicate placeholders for values you need to fill in):

Related

Creating containers

Sample Python script for updating the tag redirect domains whitelist