Integration options for the IX Identity Library

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

Regardless of the integration method that you chose, the IX Identity Library must be placed above the other header bidding solution library running on the page. For more information about IX Library™ APIs, see IX Library API reference.

Choose one of the following integration options:

  • API Model: Your header bidding solution (or website) calls the IX Identity Library using headertag.getIdentityInfo(). This retrieves and shares RTI data with any bidders who support identity fields, and occurs before the header bidding solution requests demand from the bidders. For more information, see the API Model example
  • Subscription Model: Your header bidding solution (or website) subscribes to the event rti_partner_request_complete. This event is triggered after all RTI adapters have responded. Your header bidding solution (or website) then makes the API call headertag.getIdentityInfo() to retrieve and share RTI data with any bidders who support identity fields. For more information, see the Subscription Model example.

    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. To learn more about how RTI framework works with local storage, see How RTI works in the IX Library.

API Model example

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

Subscription Model 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
		}
	}
}

An 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
		}
	}
}