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.

UUID types

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

Oracle hashed IDs (recommended): An oHash is a normalized, SHA-256 hashed email address or phone number that is automatically generated from raw personally identifiable information (PII). You should pass oHashes if you can identify your site visitors using their email-based logins or contact information they enter into a form (known ID space). The oHashes that you provide are matched to the large pool of oHashes managed by Oracle Data Cloud and added to the Oracle ID Graph.
Partner-based unique user IDs (PUUIDs): An ID in your system used to anonymously and uniquely identify users. Your PUUIDs may be based on encrypted email addresses, phone numbers, physical addresses, client account numbers, Twitter handles, and so on. You should pass PUUIDs when you are operating in an anonymous ID space, where you generate first-party cookie IDs and use them to identify for your site visitors.

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.

Desktop sites: To execute ID swaps, you must be able to make calls to an Oracle Data Cloud core tag or an ID swap tag (an image pixel). The tag you use depends on your environment.
- The Oracle Data Cloud core tag is the standard implementation for integrating with the platform. It contains HTML code and built-in JavaScript functions for sending UUIDs and user attributes to the platform, and it can be deployed directly on your site or in a tag management system.
- The ID swap tag is a 1X1 image pixel. It is typically used in environments that require pixels for making tag calls (for example, in display media).
Mobile sites: To execute ID swaps, deploy a Oracle Data Cloud mobile core tag on your site.
Mobile apps: To execute ID swaps, implement the Oracle Data Cloud SDKs in your app. See the Oracle Data Cloud iOS SDK and Oracle Data Cloud Android SDK for more information.

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:

Create a container and the ID swap tag.
Deploy the ID swap tag.
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:

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:

Setting	Value
Name	Enter “ID Swap Container” (or another name that makes it easy to identify your container’s functionality).
Default Auction Limit	Enter 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 Access	Accept the default Only Me.

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.

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.

Setting	Value
Tag Type	Pixel
Site ID	Use the default site ID (the desktop site ID that was generated when you created the container).
Protocol	Select 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.

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:

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.
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.
  Key Data type Hash
  e_id_s Email SHA-256
  p_id_s Phone SHA-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

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

oHash ID swap tag example

<img height="1" width="1" src= "https://stags.bluekai.com/site/siteID?limit=0&e_id_s=oHash"/>
Fire the ID swap tag on each unique user once every 30 days (desktop) or once every 7 days (mobile).
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.
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.
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.
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.

Key	Data type	Hash
`e_id_s`	Email	SHA-256
`p_id_s`	Phone	SHA-256

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.

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

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.

<img height="1" width="1" src="https://stags.bluekai.com/site/19461?limit=0&id=123456"/>

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.

<img height="1" width="1" src="https://stags.bluekai.com/site/YOUR_SITE_ID?redir=http://your_site.com?bk_uuid=$_BK_UUID"/>

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.

<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"/>

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:

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

Create your ID swap tag. In the HTML box, enter your ID swap tag.
Enter the following values for the general settings:
Setting Value
Status Active
Priority 100
Start Date Enter the date on which the ID swap tag is to start firing
End Date Leave blank
Enter the following values for the advanced settings:
Advanced setting Value
Inside iFrame Enabled
Override: Tag Avg. Latency Limit (ms) 5000
Override: Max Tag Execution Time (ms) 1000
Frequency 1 time every 10 days
Schedule the ID swap tag to set when and where it is fired, and who receives it.
Monitor the ID swap tag to verify that it is firing in a timely manner.
Generate a tag report.

Setting	Value
Status	Active
Priority	100
Start Date	Enter the date on which the ID swap tag is to start firing
End Date	Leave blank

Advanced setting	Value
Inside iFrame	Enabled
Override: Tag Avg. Latency Limit (ms)	5000
Override: Max Tag Execution Time (ms)	1000
Frequency	1 time every 10 days

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:

Provide Oracle Data Cloud with your ID swap URL endpoint, which is where you will receive campaign data.
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.
Create the ID swap tag using the following syntax:

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:

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.

Learn more

Percent-encoding