Send feedback on this topic

ID swapping

An ID swap is the transfer of unique user IDs (UUIDs) between your sites and the Oracle Data Cloud platform. When a user visits a web page on your network, a container tag that you deployed on your site is fired. The container tag code sends your UUIDs to the platform. Your UUIDs are then synchronized to 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 customers. You can then use offline onboard and server data transfer (SDT) integrations.

ID swap diagram

UUID types

You can pass the following types of UUIDs in a container:

Important: Personally identifiable information (PII) must not 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.

ID swap environments

You can execute ID swaps from the following environments.

The following table summarizes how to ID swap with the platform based on the ID space (known or anonymous), your tag deployment environment (web site or media), and device (desktop, mobile web, app, and hybrid app).

ID space → Known Anonymous Known Anonymous

Environment →
Device ↓

Site Site Media Media

Desktop

  • Tag: Oracle Data Cloud core tag
  • ID: oHash
  • Tag: Oracle Data Cloud core tag
  • ID: PUUID
  • Tag: Image pixel
  • ID: oHash
  • Tag: Image pixel
  • ID: PUUID

Mobile web and hybrid app

  • Tag: Oracle Data Cloud mobile core tag
  • ID: device ID or oHash
  • Tag: Oracle Data Cloud mobile core tag
  • ID: device ID or first-party cookie
  • Tag: Oracle Data Cloud mobile core tag
  • ID: device ID or oHash
  • Tag:Oracle Data Cloud mobile core tag
  • ID: device ID or first-party cookie
App and hybrid app via SDK ID:PUUID or device ID ID: PUUID or device ID ID: PUUID or device ID ID: PUUID or device ID

ID swapping with via image pixel

If you are an Oracle Data Cloud partner, you can use send your PUUIDs and oHashes to the platform via an image pixel.

To begin ID swapping:

  1. Create a container and the ID swap tag.
  2. Deploy the ID swap tag.
  3. Monitor the ID swap tag.

Use the Oracle Data Cloud core tag to send your oHashes or PUUIDs to the platform (see Oracle Data Cloud core tag implementation).

Creating a container and ID swap tag

A container manages the collection and classification of the UUIDs from your site. It includes a unique site ID that associates your site with the Oracle Data Cloud platform. For example, when your site calls the ID swap tag, the site ID enables the platform to recognize the UUIDs as yours and map them to BKUUIDs.

To create your container and ID swap tag code:

  1. Use the container tool or the containers API to create the configuration for your container (if you use the containers API, record the generated site ID). Use the following settings for your container:
    SettingValue
    NameEnter “ID Swap Container” (or another name that makes it easy to identify your container’s functionality).
    Default Auction LimitEnter 0 for the number of slots to be allocated on your site for firing third-party pixels. This is the standard limit for pixel-based ID swaps.
    Campaign AccessAccept the default Only Me.
  2. Fire the ID swap tag on each unique user (mobile or desktop) at least once every 30 days. Firing the ID swap tag more frequently than 30 days ensures that the user profile remains active in the DMP.
  3. Use the tag code generator to create the code for the ID swap tag you will deploy on your site. If you used the containers API to create your container, you can copy and configure the code examples provided in the deploying the ID swap tag section. Use the following settings for your ID swap tag.
    SettingValue

    Tag Type

    Pixel
    Site IDUse the default site ID (the desktop site ID that was generated when you created the container).
    ProtocolSelect the protocol of the page on which the tag is to be deployed (HTTP or HTTPS). Always use a secure ID swap tag (HTTPS) for web pages that use SSL.
  4. Contact My Oracle Support (MOS) and provide them with your site ID and UUID key type.

Deploying the ID swap tag

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

To deploy the ID swap tag:

  1. Copy the code in the tag code generator (click Copy Code to Clipboard), and then paste the code directly above the closing </body> tag of each web page in your network.
  2. In the query string, insert a key and value placeholder for passing your UUIDs to the platform.
    • If you are passing PUUIDs, use id as the key. The following example demonstrates where to place the PUUID key-value pair in the call:

      https://stags.bluekai.com/site/siteID?id=PUUID

    • If you are passing oHashes, the key specifies the data type (email or phone) and SHA-256 hash of the ID you are passing.
      The following example demonstrates where to place the e_id_s SHA-256 email oHash key-value pair in the call:

      https://stags.bluekai.com/site/siteID?e_id_s=oHash

      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.

      KeyData typeHash
      e_id_sEmailSHA-256
      p_id_sPhoneSHA-256

    Alternatively, you can copy one of the following ID swap tag examples, paste it into a text file, edit the site ID and UUID placeholder, and then copy and paste the tag code onto your web pages.

    PUUID ID swap tag example

    <!-- Begin ID Swap Tag-->
    <img height="1" width="1" src="https://stags.bluekai.com/site/siteID?limit=0&id=PUUID"/>
    <!-- End ID Swap Tag-->

    oHash ID swap tag example

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

  3. Fire the ID swap tag on each unique user once every 30 days (desktop) or once every 7 days (mobile).
  4. After you deploy the ID swap tag, contact My Oracle Support (MOS) to verify that your ID swap tag is sending requests to the platform.
  5. If you are a DMP client, you can maximize overlap by deploying the ID swap tag in your DMP in addition to deploying it in your network. For more details, see trafficking ID swap tags in your DMP.
  6. You may also be allowed to deploy your ID swap tag in our network of data providers (the Oracle Data Cloud network). For more details, see creating and trafficking ID swap tags in the Oracle Data Cloud network.
  7. Deploy the ID swap tag in your network. Oracle recommends that you deploy your ID swap tag in your network instead of exclusively in the Oracle Data Cloud network. Although you may receive more users if you deploy your ID swap tag in the Oracle Data Cloud network, you may not be able to sync all of them to your own ID space if you they haven’t been seen on your network. The following diagram compares the potential number of unsynced users when trafficking ID swap tags in your network and Oracle's.

Deploying ID swap tags for PUUIDs

This section describes the ID swap syntax and provides templates you can use to create your own ID swap tags for passing PUUIDs.

ID swap tag syntax: platform maintains mapping table.

<!-- Begin ID Swap Tag-->
<img height="1" width="1" src="http://your_site.com?redir=https://stags.bluekai.com/site/YOUR_SITE_ID?id=PUUID"/>
<!-- End ID Swap Tag-->

When your ID swap tag is called, it initiates an HTTP GET request that passes your PUUIDs to the platform. The URL in the GET request includes your site ID. The query string contains your pixel limit (the maximum number of slots available for firing third-party pixels, which is typically set to 0 for ID swapping) and your percent-encoded PUUIDs (phint=key%3Dvalue).

ID swap tag example: platform maintains mapping table.

<!-- Begin ID Swap Tag-->
<img height="1" width="1" src="https://stags.bluekai.com/site/19461?limit=0&id=123456"/>
<!-- End ID Swap Tag-->

Important: To create an ID swap tag for secure sites, change the protocol used by the tag to HTTPS (for example, https://stags.bluekai.com). Your tag can then be fired from both non-secure and secure sites.

If your ID swap tag uses HTTP protocol, it will only be fired on non-secured (HTTP) sites; it will not be fired on secure (HTTPS) sites. If a mutual client has a secure site and your ID swap tag uses HTTP, it may affect the amount of overlap between the Oracle Data Cloud platform and your platform and therefore the amount of the client's 1st-party data that can be delivered to you.

If you use a protocol-relative URL, the protocol used to fire your tag is based on the protocol used on the site.

Alternative ID swap process - partner maintains the ID mapping table: If you do not want to share your UUIDs with the platform, you can alternatively maintain the ID mapping table yourself. It is recommended that the platform maintains the ID mapping table in order to debug and enhance the quality of the data. The following diagram illustrates the ID swap process if you are maintaining the ID mapping table:

To create the ID swap tag if you are maintaining the ID map table, use the following syntax:

ID swap tag syntax: Partner maintains ID mapping table.

<!-- Begin ID Swap Tag-->
<img height="1" width="1" src="https://stags.bluekai.com/site/YOUR_SITE_ID?redir=http://your_site.com?bk_uuid=$_BK_UUID"/>
<!-- End ID Swap Tag-->

Alternative ID swap process: Oracle Data Cloud and partner maintain ID mapping table (example not shown). To do this, merge the previous ID swap tag examples that show how Oracle Data Cloud and you can hold the mapping table. Insert the platform macros and your macros in their respective places.

ID swap tag syntax: Oracle Data Cloud and partner both maintain ID mapping table.

<!-- Begin ID Swap Tag-->
<img height="1" width="1" src="https://stags.bluekai.com/site/YOUR_SITE_ID?limit=0&id={PUUID}&redir=http://your_site.com?bk_uuid=$_BK_UUID"/>
<!-- End ID Swap Tag-->

Monitoring your ID swap tag

After you deploy the ID swap tag and users begin logging into your site, your UUIDs should begin flowing into the platform.

To verify that your UUIDs are being collected and classified correctly and that your site is generating the expected amount of user inventory:

  1. Verify that your ID swap tag is sending your match keys to the platform.
    1. Paste your ID swap tag (for example, https://stags.bluekai.com/site/19461?limit=1&id=1234) in a web browser and use Firebug or another web inspector to verify that your Web page is passing your match keys.
    2. Contact My Oracle Support (MOS) to have them verify that your ID swap tag was fired.
  2. Verify that your inventory of UUIDs is accumulating.
    1. Use the self classification tools or the category and rule APIs to create a category that represents your ID swap site and then a URL-based rule that maps the firing of your ID swap tag to this new category.
    2. Use the inventory trend report to view the number of ID swaps being executed daily.
    3. Use the site hit report to compare the inventory figures to the number of site hits the ID swap tag is generating.
    4. Use the Audience Builder in the Oracle Data Cloud platform or the categories API to view the estimated number of unique users seen in your ID swap category. The inventory figures in your taxonomy may not initially be accurate but will indicate whether your match key inventory is ramping up.

Trafficking ID swap tags from your DMP

After your ID swap tag is trafficked in the Oracle Data Cloud network, you will begin to receive new users as they are ID synced on your network and Oracle's.

The following diagrams illustrate how trafficking your ID swap tag in the DMP network maximizes overlap. The ID swap tag is trafficked in the DMP network (1), and then as the tag is fired on new users seen in the DMP network, they are ID synced in the Oracle Data Cloud network and your network/DMP network segments, where there was previously no overlap (2).

To traffic the ID swaps tags:

  1. Create your ID swap tag. In the HTML box, enter your ID swap tag.
  2. Enter the following values for the general settings:
    SettingValue
    StatusActive
    Priority100
    Start DateEnter the date on which the ID swap tag is to start firing
    End DateLeave blank
  3. Enter the following values for the advanced settings:
    Advanced settingValue
    Inside iFrameEnabled
    Override: Tag Avg. Latency Limit (ms)5000
    Override: Max Tag Execution Time (ms)1000
    Frequency1 time every 10 days
  4. Schedule the ID swap tag to set when and where it is fired, and who receives it.
  5. Monitor the ID swap tag to verify that it is firing in a timely manner.
  6. Generate a tag report.

Creating and trafficking ID swap tags

This section describes how to create an ID swap tag and traffic it in the Oracle Data Cloud network.

Creating an ID swap tag

In some cases, you may be able to create an HTTP image tag and traffic it on the Oracle Data Cloud network. The platform monitors your pixel to verify that it loads within a minimum of 1,000 milliseconds; however, for best results, your pixel should load within 400 ms. Your pixel will be removed from the rotation if it does meet the minimum loading speed.

To create an ID swap tag to be trafficked in the Oracle Data Cloud network:

  1. Provide Oracle Data Cloud with your ID swap URL endpoint, which is where you will receive campaign data.
  2. Before trafficking your HTTP image tag in the Oracle Data Cloud network, the platform will assign you a BK_SWAP_DEST=siteID key-value pair, which identifies your site as the source of the ID swap.
  3. Create the ID swap tag using the following syntax:

<img src="your_site.com?BK_SWAP_DEST=siteID&redir=https://stags.bluekai.com/site/siteID?id=PUUID" width="1" height="1">

ID swap process: Oracle Data Cloud maintains the ID mapping table

Note: If you do want to share your UUIDs with Oracle Data Cloud, you can alternatively maintain the ID mapping table yourself. It is recommended that we maintains the ID mapping table to debug and enhance the quality of the data.

To create the ID swap pixel if you are maintaining the ID map table, use the following syntax:

<img src="your_site.com?bk_uuid=$_BK_UUID&BK_SWAP_DEST=siteID" width="1" height="1">

ID swap process: You maintain the ID mapping table

Trafficking ID swap tags on the Oracle Data Cloud network

Oracle Data Cloud may approve the trafficking of your ID swap tag in our network. The firing of the tag is based on the availability of remnant bandwidth and contractual and partnership obligations.

ID swaps are only executed on users for which an ID swap has not already occurred.

The platform initiates ID swaps on users every 30 days by default.

Related

Percent-encoding