Sending oHashes to the Oracle Data Cloud Platform

You can convert users' email addresses and phone numbers to SHA-256 hashed IDs called oHashes and send them to the platform. They will be synchronized with the network of user profiles that are linked together in the Oracle ID Graph, which is used to manage IDs and user attributes for all Oracle Data Cloud platform customers.

This synchronization optimizes the targeting and communication of your users across desktop and mobile devices and media execution platforms. oHashes enable you to increase your offline to online match rates, connect your Responsys platform to the Oracle Data Cloud platform, and execute cross-device targeting. Your private user data remains private when providing and using oHashes.

To provide the platform with your oHashes, you add Oracle Data Cloud code to your web page. The code normalizes the raw email addresses or phone numbers entered into your login screen or forms, hashes them using SHA-256 algorithms, and sends the oHashes to the platform. If you do targeted email marketing, you can also provide oHashes by having your vendor add the code to your email messages.

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 platform.

To send oHashes to the Oracle Data Cloud platform:

  1. Generate and send oHashes.
  2. Use the core tag to send oHashes.
  3. Use an ID swap tag to send oHashes.
  4. Use client-side code to send oHashes.
  5. Use server-side code to send oHashes.

Generating and sending oHashes

To add the Oracle Data Cloud code to your web page and begin anonymizing your known users and sending their oHashes to the platform, you can use one of the following methods:

  • Oracle Data Cloud CoreTag (form submission): The Oracle Data Cloud core tag is an iframe that includes JavaScript functions for normalizing email addresses and phone numbers entered into your online forms and converting them into oHashes and sending the oHashes to the platform. The core tag is recommended because it automatically does the normalization and hashing for you.
  • Oracle Data Cloud Mobile CoreTag: You can use the Oracle Data Cloud mobile core tag to pass oHashes to the platform from mobile devices. The mobile core tag is identical to the desktop core tag, but it has a few additional functions for optimizing performance on mobile sites.
  • ID swap tag: The ID swap tag is an image pixel that takes the oHashes passed into it and sends them to the platform. The ID swap tag requires client-side or server-side code to normalize and hash your email addresses or phone numbers because image pixels do not include any normalization or hashing functions. The ID swap tag is typically used in environments that require pixels for making tag calls (for example, in display media).
  • Oracle Data Cloud client-side code (JavaScript): Oracle Data Cloud client-side code uses the same functions as the core tag to generate oHashes and send them to the platform. The client-side code is used by DMP clients who want to generate oHashes on their own instead of using the core tag, or by customers who need to generate oHashes and pass them into an ID swap tag.
  • Oracle Data Cloud server-side code:Oracle Data Cloud Python, Ruby, and Java server-side code includes a series of functions that take raw email addresses and phone numbers, normalize them, and hash them. The server-side code is used by DMP clients who want to send oHashes via server-side communication or by partners who need to generate oHashes and pass them into an ID swap tag. It also used by DMP clients to generate oHashes for their offline files.

You can have your email marketing vendor add the code to your email and send your oHashes to the Oracle Data Cloud platform using one of the following methods:

  • Email open ID swap:Oracle Data Cloud client-side or server-side code converts the contact's email address to oHashes and passes them to an ID swap tag embedded in your email message. This method requires the implementation of server-side code within your email messages to hash the contact's email address prior to sending it to the platform.
  • Click-through ID swaps: An ID swap tag is used to send the contact's oHashes to the platform.

Using the Oracle Data Cloud core tag to send oHashes

If you are a Responsys client who wants send oHashes to the platform via form submissions, contact My Oracle Support (MOS) to get the site ID and Oracle Data Cloud core tag code to be deployed on your site. If you already deployed the Oracle Data Cloud core tag on your site for extracting users' online attributes, you need a separate Oracle Data Cloud core tag for your forms to collect users' email addresses and phone numbers, convert them into oHashes, and send the oHashes to the platform. You can then use the oHashes in the Responsys platform.

If you are an Oracle Data Cloud platform client and you already deployed the core tag or mobile core tag on your site, you just need to add the bk_addEMailHash or bk_addPhoneHash functions to your existing tag code to send oHashes to the platform. For details, see Core tag syntax.

To use the core tag to provide oHashes:

  1. Create the container to generate a site Oracle Data Cloud core tagKai CoreTag code.
  2. Contact My Oracle Support (MOS) and give them the site ID of the container.
  3. Use the Oracle Data Cloud core tag to generate oHashes for delivery to the platform as shown in the following examples.
<!-- Begin Oracle Data Cloud core 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 language="text/javascript" src="http://tags.bkrtx.com/js/bk-coretag.js"></script>
<script language="text/javascript">
 
//pass oHashes (hashed IDs) to the platform using the following syntax:
//bk_addEMailHash("user@example.com");
bk_addEMailHash("joe@example.com");
//bk_addPhoneHash("<Country Code><Number>"); 
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(YOUR_SITE_ID, 1);
</script>
<!-- End Oracle Data Cloud core tag-->

 

<!-- jQuery -->
<link rel="stylesheet" href="//code.jquery.com/ui/1.11.1/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.11.1.js"></script>
<script src="//code.jquery.com/ui/1.11.1/jquery-ui.js"></script>
 
<form id="myform">
    <label>Email Address:</label><input type="email" name="email" placeholder="name@example.com" autocomplete="on"><br>
    <label>Phone Number:</label><input type="tel" name="phone" placeholder="408-555-1212" autocomplete="on"><br>
    <input type="submit" value="Submit" id="submitButton"><br><br>          
</form>
 
<!--Begin Oracle Data Cloud core tag -->
<iframe name="__bkframe" height="0" width="0" frameborder="0" src="javascript:void(0)"></iframe>
<script type="text/javascript" src="http://tags.bkrtx.com/js/bk-coretag.js"></script>
<script type="text/javascript">
    $(function() {
        $("#tabs").tabs();
        $('#myform').on("submit", function(event) {
            event.preventDefault();
            bkCoreTag();
        });
    });
    function bkCoreTag() {
        var email = $('#myform input[name="email"]').val();
        var phone = $('#myform input[name="phone"]').val();
        bk_addEmailHash(email);
        bk_addPhoneHash(phone);
        bk_doJSTag(YOUR_SITE_ID, 1);
    }
</script>
<!--End Oracle Data Cloud core tag -->

For more information on creating and deploying the Oracle Data Cloud core tag, see the Oracle Data Cloud core tag implementation.

Important: You may only pass PII in the bk_addEmailHash and bk_addPhoneHash functions in the Oracle Data Cloud core tag. These functions hash PII (email addresses and phone numbers) and send the hashes to the platform. Do not pass PII into any other fields or functions. Passing PII violates your BlueKai contract and the BlueKai privacy policy.

Using an ID swap tag to send oHashes

If you are a Responsys client who wants to send oHashes to the platform via an ID swap tag, contact My Oracle Support (MOS) to get the site ID to be used in your ID swap tag.

To use an ID swap tag to provide oHashes:

  1. Create a container and generate a site ID and the ID swap tag. The following example demonstrates an ID swap tag configured for passing SHA-256 oHashes to the platform.

    <!-- Begin ID Swap Tag for passing oHashes-->
    <img height="1" width="1"
    src="https://stags.bluekai.com/site/YOUR_SITE_ID?limit=0&e_id_s={oHash}"/>
    <!-- End ID Swap Tag-->

    Note: In previous versions, MD5 hashes were supported. An e_id_m or p_id_m key indicates an MD5 oHash. For security reasons, you should not use MD5 for hashing.

  2. Use one of the server-side code examples to generate oHashes from raw email addresses and phone numbers.
  3. Pass the oHashes into the ID swap tag.

    Important: If you have multiple email addresses or phone numbers for a user, pass all the IDs in the ID swap tag and the platform will synchronize them to the Oracle ID Graph. For example, if you have two SHA-256 hashed email addresses for a user, your ID swap tag might have the following syntax: https://stags.bluekai.com/site/YOUR_SITE_ID?limit=0&e_id_s={oHash1}&e_id_s={oHash2}

  4. Before deploying your ID swap tag in your production environment, contact My Oracle Support (MOS) to get a set of raw email addresses and phone numbers to verify that your server-side code is passing valid oHashes that adhere to the platform’s standards.
  5. After the platform verifies that your ID swap tag is passing valid oHashes, you can deploy it your production environment.

For more information on creating and deploying ID swap tags, see ID swapping.

Using client-side code to send oHashes

You can download following sample client-side code that illustrates how you can take email addresses and phone numbers from your systems, convert them to oHashes, and send them to the platform: client-side oHash example.

The client-side oHash code example does the following:

  1. When the user submits their contact information, it is passed to the bk_addEMailHash and bk_addPhoneHash functions, which normalizes and encrypts 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.

    Important: The bk_addEmailHash and bk_addPhoneHash functions encrypt PII (email addresses and phone numbers) and send the hashes to the Oracle Data Cloud platform. Do not pass PII into any other fields or functions. Passing PII violates your contract and the Oracle privacy policy.

  2. The bk_doJSTag function takes your site ID and pixel limit and initiates an HTTP GET request to send the SHA-256 oHashes to the platform as phints (key-value pairs).
    • Site ID: The unique identifier used to manage your site and oHashes in the Oracle Data Cloud platform. To get your site ID, create a container or use the containers API.
    • Pixel limit: Sets the maximum number of third-party tags that can be fired during a single page view. Set the pixel limit to 0 when sending oHashes.

    Each oHash is associated with a key identifying its data type (email or phone) and hash (SHA-256):

    KeyData typeHash
    e_id_sEmailSHA-256
    p_id_sPhoneSHA-256

    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.

  3. Before deploying the client-side code in your production environment to pass oHashes to the platform, contact My Oracle Support (MOS) to request a set of raw email addresses and phone numbers to verify that you are passing valid oHashes.

Using server-side code to send oHashes

BlueKai’s Python, Ruby, and Java server-side code examples demonstrate how you can convert raw email addresses and phone numbers on your server into oHashes.

These examples define a Hashing object that has the following functions:

  • normalizeEmail and normalizePhone: Trims all special characters, punctuation, and spaces, lowercases all characters, and verifies that the email address has the @ symbol.
  • createEmailHash and createPhoneHash: Takes an email address or phone number and a hashing algorithm (sha256), passes normalized versions of the input and the hashing algorithm to the createHash function, and returns the result.
  • createHash: Takes the normalized email address or phone number and encrypts it using the specified hashing algorithm.

Email open ID swap

If you are an Oracle Marketing Cloud client that uses Responsys, you can send oHashes to the platform via your email marketing messages. BlueKai has an integration with Responsys that automates the creation and transfer of oHashes. Responsys converts the email addresses of the contacts in their database into oHashes. When a contact opens your Repsonsys-based email message, their email address is looked up and the associated oHashes are passed into an ID swap tag embedded in the message. The ID swap tag is then fired and the oHash is sent to the platform.

Alternatively, you can use a different email marketing vendor to pass oHashes to the platform.

To pass oHashes via an email marketing vendor:

  1. Create an ID swap tag for passing oHashes and give it to your email marketing vendor. The following sample ID swap tag can send SHA_256 oHashes to the platform.

    <!-- Begin ID Swap Tag-->

    <img height="1" width="1" src= "https://stags.bluekai.com/site/<YOUR_SITE_ID>?limit=0&e_id_s={value}"/>

    <!-- End ID Swap Tag-->

  2. Ask your vendor to contact your Oracle Data Cloud account manager to set up an integration.
  3. Your email marketing vendor will then:
    1. Programmatically lookup the contact's email address and use BlueKai’s client-side or server-side code to normalize them and create oHashes.
    2. Pass the oHash into the value field of your ID swap tag.
    3. Fire the ID swap tag to send the oHash to the platform.

Click-through ID swaps

Your email marketing messages can include a click-through to your landing page for passing your oHashes to the platform. This is useful if a cookie cannot be directly set on users in the email message. You can execute ID swaps using a click-through for the following scenarios:

  • Tag URL parsing: When a user clicks on a link to your landing page, their hashed email address is looked up and added to the query string, passed to a Oracle Data Cloud core tag or ID swap pixel deployed on the page, and sent to the platform.
  • Third-party site: When a contact clicks on a link to a third-party site, which does not have any tags, a redirect is used to triggers an ID swap that sends the contact's oHashes and GUID to Oracle Data Cloud and redirects the contact to the destination URL.

Tag URL parsing

When a contact clicks on the link to your landing page, the oHash is looked up and added to the query string of the landing page URL. When the landing page opens, the oHash is extracted from the query string and then passed into a Oracle Data Cloud core tag or ID swap tag you have deployed on your site. The tag is then fired and the oHash is sent to the platform.

To use a click-though URL to pass oHashes to the platform:

  1. Provide your email marketing vendor with a link to your landing page. The link must include the SHA-256 oHash key and oHash value placeholder in the query string, as demonstrated in the following example:

    http://your_site.com/landing_page.html?e_id_s=value

  2. Create a Oracle Data Cloud core tag or ID swap tag for passing oHashes and deploy it on the landing page specified in the click-through URL. The following examples demonstrate the syntax of the Oracle Data Cloud core tag and ID swap tag you will deploy on the landing page for email click-throughs:

    <!-- Begin Oracle Data Cloud core 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 language="text/javascript" src="http://tags.bkrtx.com/js/bk-coretag.js"></script>

    <script language="text/javascript">

    //pass oHashes into the 'Value' field of the bk_addPageCtx function

    bk_addPageCtx('e_id_s', 'Value'); // SHA-256 Hash

    //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(YOUR_SITE_ID, 4);

    </script>

    <!-- End Oracle Data Cloud core tag-->

    ID swap tag for sending oHashes for email click-throughs:

    <!-- Begin ID Swap Tag-->
    <img height="1" width="1" src= "https://stags.bluekai.com/site/<YOUR_SITE_ID>?limit=0&e_id_s={value}"/>
    <!-- End ID Swap Tag-->

  3. In your landing page, add code to parse the oHashes in the query string, and pass them to the Oracle Data Cloud core tag or ID swap tag.

FAQs

Q. How is my PII hashed and can the hash be reversed?

An SHA-256 cryptographic hashing function is used to hash the email addresses and phone numbers for your contacts. These are the industry standard hashing algorithms used by many platforms for hashing users' contact information.

The SHA-256 hashing algorithms are one-way functions. The length of the input used in these algorithms may vary, but the output is always a fixed length. This means that an infinite number of input strings could have been used to generate a hash, which makes it impossible to reverse the hash and get the PII from which it was created.

Consider the modulo operation as an example. If you did 5%4, you would get 1, but another party would have no way to determine the numbers used to get the result of 1.

The platform has no way to get the original email address from which the hash was created.

Q. What happens when I send my oHashes to the platform?

When you send your oHashes to the platform, they are mapped to the network of user profiles in the Oracle ID Graph.

Learn more

Oracle Data Cloud core tag implementation

ID swapping

Percent-encoding