Oracle Data Cloud Core Tag Implementation

You can implement the Oracle Data Cloud CoreTag on your desktop and mobile sites to extract online user attributes and import them into the Oracle Data Cloud platform. The Oracle Data Cloud core tag is an iframe that references the bk-coretag.js file, which is a small JavaScript file stored on third-party content delivery networks (CDNs) to facilitate quick access and low latency. The bk-coretag.js file includes a library of JavaScript helper functions for setting the source of the iframe and generating the explicit key-value pairs that pass your user attributes to the Oracle Data Cloud platform.

Note: Oracle Data Cloud tags and code include references to BlueKai and bk. These references are the result of legacy naming policies.

When the Oracle Data Cloud core tag is called and the platform receives your online user attributes, classification rules map the collected data into categories (groups of users with the same attribute) in your taxonomy. The following diagram illustrates how the Oracle Data Cloud core tag extracts your online user attributes and imports them into your taxonomy:

CoreTag process diagram

Important! The Oracle Data Cloud no longer creates insecure (http) tags. You should always use the secure https://tags.bkrtx.com/js/bk-coretag.js URL.

In this topic

Using the Oracle Data Cloud core tag for ID swaps

An ID swap is the transfer of unique user IDs (UUIDs) between you and the Oracle Data Cloud platform. When a user visits your site, the Oracle Data Cloud core tag can send your UUIDs to the platform so they can be synchronized to the network of user profiles that are linked together in the Oracle ID Graph. This synchronization enables you to use offline ingest and server data transfer (SDT). The Oracle Data Cloud core tag has built-in functions that accept two types of UUIDs: Oracle hashed IDs (oHashes) and anonymous IDs.

  • oHashes (recommended): If you are operating in a known ID space, where you can identify the user based on their login credentials or contact information they have entered into a form, you can use the Oracle Data Cloud core tag to hash raw personally identifiable information (PII) and send the hashes to the platform. The Oracle Data Cloud core tag includes addEmailHash and addPhoneHash functions that take the raw email addresses and phone numbers entered in your site (from your login screen or forms) and normalize them, encrypt them using SHA-256 hashes, and send the SHA-256 hashes to the platform. The platform generates both hashes to enable you to implement either hash in your system. The oHashes that you and other partners provide are added to the Oracle ID graph, which manages oHashes for all Oracle Data Cloud platform customers. Providing oHashes enables you to onboard offline data with increased match rates and to integrate your Responsys and Eloqua email data with your DMP.
    The following diagram illustrates how the Oracle Data Cloud core tag creates oHashes and sends them to the platform:
    CoreTag oHash diagram
    The following code example demonstrates how to create oHashes in the Oracle Data Cloud core tag:

    //pass SHA-256 hashed oHashes for ID swaps using the following syntax:
    //bk_addEMailHash(“user@example.com”);
    //bk_addPhoneHash(“<Country Code><Number>”);
    bk_addEMailHash(“joecool@example.com”);
    bk_addPhoneHash(“14085551212”);

    Warning: You may only pass personally identifiable information (PII) in the bk_addEmailHash and bk_addPhoneHash functions in the Oracle Data Cloud core tag. Do not pass PII into any other fields or functions. Passing PII violates your Oracle contract and Oracle's privacy policy.

    If you want to generate oHashes using client-side or server-side code instead of using the Oracle Data Cloud core tag, you can use the JavaScript, Python, JAVA, or Ruby oHash code samples that you can implement on your web site or server. For details, see sending oHashes to the platform.

  • Anonymous UUIDs: If you anonymously identify your site visitors with a cookie ID, account ID hash, or other identifier, you can use the bk_addPageCtx function in the Oracle Data Cloud core tag to pass your UUIDs to the platform. The following diagram illustrates how the Oracle Data Cloud core tag can be used to pass UUIDs to the platform:

    The following code example demonstrates how to pass anonymous UUIDs in the Oracle Data Cloud core tag:

    //pass UUIDs for ID swaps using the following syntax:
    //bk_addPageCtx('id, 'Value');
    bk_addPageCtx("id", "5Gya3quS");

    Warning: The Oracle Data Cloud platform uses client-side cookies to store transferred information. No PII may be sent to or stored in the Oracle Data Cloud platform.

To implement the Oracle Data Cloud core tag:

  1. Create a container.
  2. Scope the data to be extracted from your site.
  3. Configure the Oracle Data Cloud core tag.
  4. Deploy the Oracle Data Cloud core tag.
  5. Classify the data collected by your Oracle Data Cloud core tag.
  6. Monitor data ingest.

Creating a container

To create your container and generate site IDs, use the container tool in the platform UI or use the containers API.

A container manages the collection and classification of user data extracted from your site. It includes JavaScript and HTML code that collects explicitly defined data from your sites and then transfers that data to partners by scheduling third-party tags and pixels on your site.

Each container includes a unique site ID that associates your desktop and mobile sites with your DMP. For example, when your site calls the Oracle Data Cloud core tag to import user attributes into the Oracle Data Cloud platform, the site ID enables the platform to recognize the incoming data as yours, and the data extracted from your site to be mapped to the appropriate categories in your taxonomy via classification rules.

Typically, you use a separate site ID for each of your desktop sites, mobile sites, and mobile apps; therefore, if you are collecting data from all three of these assets, you need to create at least two containers: one for your desktop and mobile site and a second for your mobile app. Each of your mobile apps should have a separate site ID.

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.

Scoping your data

You need to identify the data you want to extract from your site and pass into your container. Typically, you will extract the following technical elements from your page to represent human readable user attributes to be mapped into categories in your taxonomy:

  • HTML DOM properties and page keywords: The container includes JavaScript code that automatically collects properties such as document.location, document,referrer, document.title.
  • Native variables: Properties that exist in your rendered HTML pages, such as product SKU numbers.
  • Other data: Data such as form fields and shopping cart items that do not natively exist in the DOM.

If you purchased consulting services, your Solutions Consultant (SC) will work with you to understand your business goals for the DMP, and then scope your sites and design a data collection strategy based on your objectives. Your SC will help you identify the native variables on your site that should be collected. They will also identify traffic, conversion, and other analytics variables. Your SC will also show you how to collect data from your forms and your shopping cart.

Configuring the Oracle Data Cloud core tag

Configuring the Oracle Data Cloud core tag entails generating the tag code you will deploy on your site. To do this, you can use the code generator included with the container tool in the Oracle Data Cloud platform, or you can copy the provided desktop and mobile code templates below, paste them into a text file, and then configure the tag code accordingly. If you are using the Oracle Data Cloud core tag for ID swapping, make sure you add code for passing your UUIDs into the bk_addPageCtx function.

CoreTags for desktop sites

<!-- Begin BlueKai desktop CoreTag -->
<iframe name="__bkframe" height="0" width="0" frameborder="0" style="display:none;position:absolute;clip:rect(0px 0px 0px 0px)" src="about:blank"></iframe>
<script language="text/javascript" src="https://tags.bkrtx.com/js/bk-coretag.js"></script>
<script language="text/javascript">
//pass page and user attributes using the following syntax:
//bk_addPageCtx('Key', 'Value');
bk_addPageCtx("prodType", "Laptop");
bk_addPageCtx("prodModel", "Z3-HX2");
//pass UUIDs for ID swaps using the following syntax:
//bk_addPageCtx('id', 'Value');
bk_addPageCtx("id", "5Gya3quS");
//pass oHashes (SHA-256 hashed email addresses and phone numbers) using the following syntax:
//bk_addEMailHash(“user@example.com”);
//bk_addPhoneHash(“<Country Code><Number>”);
bk_addEMailHash(“joecool@example.com”);
bk_addPhoneHash(“14085551212”);
//block passing of meta data (URL, meta keywords, and page title)
bk_ignore_meta = true;
//pass your Site ID and the pixel limit using the following syntax:
//bk_doJSTag('Site ID', 'Pixel Limit');
bk_doJSTag(99999,4);
</script>
<!-- End BlueKai desktop CoreTag -->

Oracle Data Cloud core tag for mobile sites

You can use the Oracle Data Cloud mobile core tag to send mobile-based user attributes, user IDs, and device IDs to the platform.

If you are using the mobile core tag to ID swap with the platform, you should pass the device ID (Google ADID or IDFA) and a user ID (oHash) in the tag call.

  • If you are operating in a known ID space (you can identify your site visitors using their email-based logins or contact information they enter into a form), pass an oHash for the user ID.
  • If you can only pass a single ID, the device ID is preferred.
  • If you cannot provide a device ID or oHash, contact your SC.

<!-- Begin BlueKai mobile CoreTag -->
<iframe name="__bkframe" height="0" width="0" frameborder="0" style="display:none;position:absolute;clip:rect(0px 0px 0px 0px)" src="about:blank"></iframe>
<script language="text/javascript" src="https://tags.bkrtx.com/js/bk-coretag.js"></script>
<script language="text/javascript">
//allow tag to be called multiple times while previous calls are being executed
//(helps prevent race conditions and data corruption)
bk_allow_multiple_calls=true;
//dynamically create separate iframes for each tag call
//(helps prevent race conditions and data corruption)
bk_use_multiple_iframes=true;
//pass a device ID (Google Ad ID or IDFA) and a user ID (an oHash)
//if you can only pass one ID, send the device ID
//MOBILE APP: SEND THE DEVICE ID
//***Android Mobile Apps: Open a WebView and pass the Device ID using the Google Advertising ID***
//bk_addPageCtx("AdID", 'GOOGLE_AD_ID');
bk_addPageCtx("AdID", "38400000-8cf0-11bd-b23e-10b96e40000d");
//***iPhone Mobile Apps: Open a WebView and pass the Device ID using the IDFA***
//bk_addPageCtx("idfa", 'iPhone_IDFA');
bk_addPageCtx("idfa", "AEBE52E7-03EE-455A-B3C4-E57283966239");
//MOBILE WEB: SEND THE USER ID
//***Mobile Web: Identify users with an oHash***
//pass email addresses and phone numbers using the following syntax:
//bk_addEMailHash(“user@example.com”);
//bk_addPhoneHash(“<Country Code><Number>”);
bk_addEMailHash(“joecool@example.com”);
bk_addPhoneHash(“14085551212”);
//SEND USER ATTRIBUTES
//pass page and user attributes using the following syntax:
//bk_addPageCtx("Key", "Value");
bk_addPageCtx("Make", "Acura");
bk_addPageCtx("Model", "MDX");
bk_addPageCtx("Zip", "90201");

//SEND THE MOBILE ADVERTISING ID
//bk_addPageCtx("appid",'App ID');
bk_addPageCtx("appid","id659503543");
//pass your site ID and the pixel limit using the following syntax:
//bk_doJSTag(Site ID, Pixel Limit);
bk_doJSTag(99999,1);
</script>
<!-- End BlueKai mobile CoreTag -->

Using the Oracle Data Cloud core tag in Accelerated Mobile Pages (AMP)

AMP sites do not support the iframe used with the bk-coretag.js file. If your mobile site uses AMP, you can implement an AMP iframe to link to an HTML file that contains a typical iframe that references bk-coretag.js.

The following sample HTML file contains an AMP iframe that references a second sample test.html file. 

<!doctype html>
<html amp lang="en">
<head>
    <meta charset="utf-8">
    <script async src="https://cdn.ampproject.org/v0.js"></script>
    <script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>
    <title>Hello, AMPs</title>
    <link rel="canonical" href="http://example.ampproject.org/article-metadata.html" />
    <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
    <style amp-boilerplate>
        body {
            -webkit-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
            -moz-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
            -ms-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
            animation: -amp-start 8s steps(1, end) 0s 1 normal both
        }
        @-webkit-keyframes -amp-start {
            from {
                visibility: hidden
            }
            to {
                visibility: visible
            }
        }
        @-moz-keyframes -amp-start {
            from {
                visibility: hidden
            }
            to {
                visibility: visible
            }
        }
        @-ms-keyframes -amp-start {
            from {
                visibility: hidden
            }
            to {
                visibility: visible
            }
        }
        @-o-keyframes -amp-start {
            from {
                visibility: hidden
            }
            to {
                visibility: visible
            }
        }
        @keyframes -amp-start {
            from {
                visibility: hidden
            }
            to {
                visibility: visible
            }
        }
    </style>
    <noscript>
        <style amp-boilerplate>
            body {
                -webkit-animation: none;
                -moz-animation: none;
                -ms-animation: none;
                animation: none
            }
        </style>
    </noscript>
    <style amp-custom>
        amp-iframe {
            margin-top: 600px;
            height: 1px;
            width: 1px;
            visibility: hidden;
        }
    </style>
</head>
<body>
    <!-- Contents of the page -->
    <h1>Welcome to the mobile web</h1>
    <!-- This AMP iframe links to the second file called test.html, which contains an iframe linking to the bk-core tag -->
    <amp-iframe sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox" height="1" width="1" frameborder="0" layout="responsive" src="https://localhost:4443/test.html"></amp-iframe>
</body>
</html>

 

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Hello, AMPs</title>
</head>

<body>
    <h1>Below is the iframe to the bk-core tag</h1>
    <!-- Begin BlueKai Tag -->
    <iframe name="__bkframe" height="0" width="0" frameborder="0" style="display:none;position:absolute;clip:rect(0px 0px 0px 0px)" src="about:blank"></iframe>
    <script type="text/javascript" src="https://tags.bkrtx.com/js/bk-coretag.js"></script>
    <script type="text/javascript">
        bk_addPageCtx('amp', 'enabled');
        bk_addPageCtx('cars', 'audi');
        bk_addPageCtx('flight', 'Philadelphia');
        bk_addPageCtx('education', 'master');
        bk_doJSTag(4868, 1);
    </script>
    <!-- End BlueKai Tag -->
</body>
</html>

Important: AMP supports only HTTPS, so these sample files assume that you will test them using an HTTPS server on your local host.

Oracle Data Cloud core tag syntax

The key functions in the Oracle Data Cloud core tag include:

  • bk_addPageCtx: Enables you to pass explicit page and user attributes to the platform.
  • bk_addEMailHash and bk_addPhoneHash: Enable you to pass hashed email addresses and phone numbers.
  • bk_doJSTag: Initiates an HTTP GET request that passes your phints to the platform.

bk_addPageCtx

To pass explicit page and user attributes to the platform such as product views, purchase intent, add-to-cart actions, and conversions, generate percent-encoded key-value pairs that called phints. Example

&phint=product%3DSmartphone

Important: All URIs sent to the platform are assumed to be percent-encoded on the client side.

bk_addEMailHash and bk_addPhoneHash

When you call one of these methods, they do the following:

  • Normalize the email address or phone number. For example, the function enforces UTF-8 character encoding, lowercases all characters in the email address, verifies that it has the @ symbol, and removes all special characters, punctuation, and spaces.
  • Encrypt the email address or phone number using SHA-256. The generated oHashes are passed as phints in an HTTP GET request to the platform. Each oHash will be associated with a key identifying its data type (email or phone) and hash (SHA-256):
    KeyData typeHash
    e_id_s  Email  SHA-256  
    p_id_s  Phone  SHA-256  

Note: MD5 hashes are also supported. An e_id_m or p_id_m key indicates an MD5 oHash. For security reasons, Oracle recommends that you not use MD5.

For example, if you pass an email address in the bk_addEMailHash function, the HTTP GET request will include the following phint:

phint=e_id_s%3DSHA-256oHash

Before deploying an Oracle Data Cloud core tag in your production environment to pass oHashes to the platform, contact your Oracle Data Cloud representative to request that we provide you with a set of raw email addresses and phone numbers to verify that you are passing valid oHashes that adhere to the platform’s standards.

bk_doJSTag

This function initiates an HTTP GET request that passes your phints to the platform. The URL in the GET request includes your site ID. The query string contains the pixel limit and the URL-encoded phints.

HTTP GET request:

https://stags.bluekai.com/site/siteID/?ret=html&limit=pixelLimit&phint=KEY%3DVALUE

Where:

  • siteID is the unique identifier generated when you create a container and is used to manage your site in the Oracle Data Cloud platform.
  • pixelLimit sets the maximum number of third-party tags that can be fired during a single page view. This controls the number of slots available for transferring first-party data to media vendors. The default pixel limit is 4.

HTTP GET request passing user attributes:

https://stags.bluekai.com/site/15415/?ret=html&limit=4&phint=prodType%3DSmartphone

Passing oHashes:

https://stags.bluekai.com/site/15415/?ret=html&limit=4&phint=e_id_s%3DSHA-256oHash

Important: Call the bk_doJSTag function last. To ensure that phints are processed, call bk_addPageCtx, bk_addEMailHash, and bk_addPhoneHash before bk_doJSTag.

Oracle Data Cloud core tag process

The bk-coretag.js file sets the iframe's src value, which is a dynamic URL that initiates a GET request to pass the phints that classify users into the appropriate categories in the taxonomy. the platform returns the media vendor pixels associated with your active data campaigns to the iframe.

The Oracle Data Cloud platform can provide you with an Oracle Data Cloud core tag that contains numerous phints for passing native page data, such as JavaScript and analytics variables. To pass phints for other data types (such as forms and shopping carts), add a call to the bk_addPageCtx function for each phint to be sent.

Deploying the Oracle Data Cloud core tag

To deploy your Oracle Data Cloud core tag, copy the code from the Tag Code Generator or from the code templates you configured in a text file, and paste it before the closing </body> tag on your Web page. User data will not begin flowing into your DMP until you create your categories and classification rules in the next section.

Before deploying your Oracle Data Cloud core tag into your production environment, you can add the Oracle Data Cloud core tag to a test site and then do the following:

  1. Check that the Oracle Data Cloud core tag is properly making requests to the platform.
    On each page view, the Oracle Data Cloud core tag should generate a GET request to the platform that has the following syntax:
    https://stags.bluekai.com/site/siteID?ret=html&phint=param1%3Dvalue1&phint=param2%3Dvalue2&phint=paramN%3DvalueN

    To examine the GET request being made to the platform on each page view, use a standard browser tool such as FireBug, HTTPFox, or Tamper Data on Firefox; Web Developer on Chrome; or Fiddler on Internet Explorer.
  2. Verify the number of tag calls with the site hit report. To ensure that the Oracle Data Cloud is receiving approximately the same number of requests you are generating with an Oracle Data Cloud core tag, use a web analytics solution (for example, Google Analytics, Webtrends, Coremetrics, SiteCatalyst) to report the number of page views your tag generated during testing. You can then compare your reported page views to the figures listed in the Site Hit Report. The reports should not have a discrepancy greater than 10%.
  3. After you have successfully tested your Oracle Data Cloud core tag, you can deploy it into your production environment. Gradually implement the Oracle Data Cloud core tag. For example, start with a low-risk area in your site and then slowly move to more high-volume areas. Each time you deploy the Oracle Data Cloud core tag on a page, repeat the tests to verify that the Oracle Data Cloud core tag is functioning properly in your production environment.

Classifying your online data

To import your online user attributes into the Oracle Data Cloud platform:

  1. Create a data map that outlines the keys and values you are passing to the Oracle Data Cloud platform.
  2. Create categories and classification rules that map the user attributes extracted from your site to your taxonomy.

Creating a data map

To organize the online user attributes you are ingesting and help facilitate the classification process, you need to create a data map. The data map provides an outline of how you will organize your online 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 Data Cloud services to classify your offline data, the data map is required. The data map should do the following:

  • 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, if necessary.
  • 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 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 Data Cloud 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 site:

Key Key translation Value Value translation (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, coffee drinkers, video gamers, smartphone purchasers, and so on). Classification rules map the user attributes extracted from your site to categories in your Oracle Data Cloud platform taxonomy.

Consider a user that has purchased a smartphone from your online or mobile site. You could pass a "purchase=smartphone" attribute for this user in the Oracle Data Cloud core tag. When this user 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 purchaseissmartphone, 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 them.

If you purchased consulting services, you can have our classification and taxonomy team you build your taxonomy.

Monitoring data ingest

After you create your categories and classification rules, user data begins to flow into your taxonomy. To verify that your data is being collected and classified correctly and that your site is generating the expected amount of inventory, you can do the following:

  • 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. Alternatively, you can use the categories API to programmatically check your inventory of your unique users.

It may take a few days for your ramped inventory numbers to appear in the platform UI reports and tools.

Learn more

bk-coretag.js file

Categories API

Container tool

Percent-encoding