IX Identity Library

What Is the IX Identity Library?

The IX Identity Library™ brings certified Real Time Identity (RTI) adapters and their benefits—traditionally available only through the IX Custom Library™ and IX Wrapper Library™ types—to publishers using any header bidding solution.

Target Audience

  • Publishers who want to continue using a header bidding solution that is not offered by IX, but do want to enrich bid requests with people-based or cookie-based identifiers.
  • Publishers who are comfortable with the technical setup of the IX Identity Library.
  • Publishers who are comfortable managing the integration between JavaScript libraries (the IX Identity Library and another header bidding solution on the page).

What are the Benefits of the IX Identity Library?

For Publishers

By providing access to RTI adapters, which may not be available in a publisher's existing header bidding solution, the IX Identity Library unlocks people-based marketing and previously unknown budgets. As DSPs begin to adopt shared identifiers, publishers will see increased bid density (more frequent bidding) via increased DSP participation rate.

For Users

A key pain point for users is page load time, and the main driver of page load time is the number of network calls on a given web page. The Real Time Identity (RTI) framework allows publishers to collect only the identifiers they need and to suppress unnecessary network calls for an ID they already have. This results in faster page load times for users.

Which RTI Adapters are Available?

See Real Time Identity to learn about which RTI adapters are available in the IX Identity Library.

How Does the IX Identity Library Work?

The IX Identity Library is a JavaScript library that lives in the <head> section of a publisher’s site, placed above other header bidding solutions implemented on the page, and runs parallel to it.

When the IX Identity Library is implemented, this is what happens:

  1. The IX Identity Library instantiates on page load. It checks if a value is stored locally in the browser for each RTI adapter enabled. If a cached value is located, step 3 occurs.
  2. If a value is not found, the IX Identity Library makes a network call to each of the RTI adapter’s endpoint to request this information. It stores this response in the browser’s Local Storage, therefore reducing the number of additional network calls required.
  3. The RTI data retrieved is made available to the publisher’s header bidding solution through one of two methods, depending on the publisher’s integration. See Integration Options for more information.

What are the Integration Options?

The IX Identity Library packages up IX's proprietary RTI framework into a standalone library with simple and extensible implementation. It allows Prebid publishers a very easy implementation path, while providing multiple integration routes for publishers using other header bidding solutions to ingest the Identity information.

Publishers can choose between two integration options: API Model and Subscription Model. Regardless of which integration method is chosen, the IX Identity Library must be placed above the other header bidding solution library running on the page.

API Model

The publisher’s header bidding solution (or webpage) calls the IX Identity Library using headertag.getIdentityInfo() to retrieve and share RTI data with any bidders that support Identity fields before the header bidding solution requests demand from these bidders.

Example

if (typeof  headertag.getIdentityInfo === "function") {
var rtiData = headertag.getIdentityInfo();
}

Subscription Model

The publisher’s header bidding solution (or webpage) subscribes to the event rti_partner_request_complete. This event is triggered after all RTI adapters have responded. The header bidding solution (or webpage) then makes the API call headertag.getIdentityInfo() to retrieve and share RTI data with any bidders who support identity fields.

Note

Because the RTI data is stored in the browser’s Local Storage, it’s possible that the event may have already occurred before it’s subscribed. Therefore, we recommend checking if the data is available using the API Model and subscribe to the event if it is not. Click here to learn more about how RTI framework works with Local Storage.

Example

var headertag = headertag || {};
headertag.cmd = headertag.cmd || [];
headertag.cmd.push(function() {
    var rtiData = headertag.getIdentityInfo();

    var responsePending = 0;
    for (var rtiPartner in rtiData) {
        if (rtiData.hasOwnProperty(rtiPartner) && rtiData[rtiPartner].responsePending === true) {
            responsePending = 1;
            break;
        }
    }

    // Subscribe if response is pending
    if (responsePending) {
        window.headertag.subscribeEvent('rti_partner_request_complete', false, function(eventName, eventData) {
            rtiData = headertag.getIdentityInfo();
        })
    }
});

Response

The API call, headertag.getIdentityInfo(), returns RTI data per partner in the following format:

{
	RTI-Adapter-1: { 
		responsePending: false, // This will be updated to true once response is received
		data: {
			// RTI data from RTI-Adapter-1
		}
	},
	RTI-Adapter-2: { 
		responsePending: true,
		data: {
			// RTI data from RTI-Adapter-2
		}
	}
}

Example of RTI data retrieved from the IX Identity Library, configured with Unified ID and LiveRamp:

{
	"AdserverOrgIp": {
		"data": {
			"source": "adserver.org",
			"uids": [{
					"id": "uid123",
					"ext": {
						"rtiPartner": "TDID"
					}
				},
				{
					"id": "TRUE",
					"ext": {
						"rtiPartner": "TDID_LOOKUP"
					}
				},
				{
					"id": "2018-08-06T18:55:26",
					"ext": {
						"rtiPartner": "TDID_CREATED_AT"
					}
				}
			]
		},
		"responsePending": false
	},
	"LiveRampIp": {
		"data": {
			"source": "liveramp.com",
			"uids": [{
				"id": "XY6104gr0njcH9UDIR7ysFFJcm2XNpqeJTYslleJ_cMlsFOfZI",
				"ext": {
					"rtiPartner": "idl"
				}
			}],
			"responsePending": false
		}
	}
}