The Cross-Player Prebid Component communicates with the publisher’s player using window.postMessage as supported by all browsers. The message can be initiated either by the Component or by the Player.
The following rules apply for this communication:
window.postMessage ('hello', '*');top.postMessage ('hello', '*');window.addEventLIstener('message', listenerHandler);The communication between the Component and the Player uses two messages, one from the Player to request the Prebid results and the other from the Component to respond to the request.
This message is sent by the Player to request the prebid results from Prebid Component. The message should be constructed as a JSON object with the following fields:
PPCP:prebidUrlRequest.The message should be converted to a String using JSON.stringify before passing it into the postMessage.
This message is sent by the Component to the Player in response to the Player’s request for Prebid results. The message should be constructed as a JSON object with the following fields:
PPCP:prebidResponse.The message should be converted to a String using JSON.stringify before passing it into the postMessage.
NOTE: These steps assume that the Component is being loaded in the header and the Player is loaded in an IFrame.
Prebid Component
Adds a listener on the window within the document where it is running.
The Component is listening for the following command in a postMessage: PPCP:prebidUrlRequest. Filter the messages looking for this command inside the requestHandler.
window.addEventListener('message', requestHandler);
Request Handler Sample Code:
// the component code is written in ES6 Javascript
this.requestHandler = (event) => {
if (event && event.data) {
let data;
try {
data = JSON.parse(event.data);
}
catch (err) {
// Invalid message data. Ignore it.
return;
}
const frameWnd = event.source;
// internal function used to send back the response
const sendResponse = (url) => {
// send response to source window (iframe)
Logger.log(this._prefix, 'Post url:', url);
const response = {
command: 'PPCP:prebidResponse',
messageId: data.messageId,
url: url
};
const sendingData = JSON.stringify(response);
frameWnd.postMessage(sendingData, '*');
};
// sync request
if (data.command === 'PPCP:prebidUrlRequest') {
if (this.defaultUrl) {
// we have ad URL to play
sendResponse(this.defaultUrl);
}
else if (this.defaultUrl === null) {
// failed to get ad URL
sendResponse('failed');
}
else {
// prebid.js is not ready (not loaded yet)
sendResponse('unknown');
}
}
}
};
Player
Adds a listener on the player window, looking for a message that contains a response from the Component.
The Player is listening for the following command in a postMessage: PPCP:prebidResponse. Filter the messages looking for this command inside the responseHandler.
window.addEventListener('message', responseHandler);Player
Sends a postMessage to the top window when it is ready for the results of the Prebid process.
The Player posts a message with the following command: PPCP:prebidUrlRequest to request Prebid results from the Component.
NOTE: The * argument indicates post the message to any domain.
var msg = {};
msg.command = 'PPCP:prebidUrlRequest';
msg.messageId = 1234;
top.postMessage(JSON.stringify(msg), '*');
Prebid Component
The Component will post a response message back to the Player's IFrame, sending the current status of the Prebid process.
If the Component posts the message, indicating that it does not yet know the results, the Player should be prepared to request the results again.
When the Component receives a PPCP:prebidUrlRequest message, it will post a response message back to the Player’s IFrame, sending the current status of the Prebid process. The URL field of the response will indicate what the Component knows at that time about the Prebid process. Possible values:
* argument indicates post the message to any domain.
var msg = {};
msg.command = 'PPCP:prebidResponse';
msg.messageId = 1234;
msg.url = 'http://url-to-vast.xml'
top.postMessage(JSON.stringify(msg), '*');
Player
Once the Component has received the Prebid results using the listener for response message, the Player should do one of the following:
Once the Player receives a message it should parse the **event.data** in the listener handler using JSON.parse. If event.data includes the event.data.command 'PPCP:prebidResponse', it should examine event.data.url and event.data.messageId.
It should make sure that the messageId matches the messageId that it used in the request for Prebid response.
If the event.data.url field contains a valid URL, the Player should use that URL to retrieve the ad to play.
If event.data.url contains the value failed, then Prebid.js was unable to find an ad and, as a result, the Player should continue with its normal content.
If event.data.url contains the value unknown, then the Player should send out another request for the Prebid results after waiting a brief period of time.
var lastMessageId = 12345;
var responseHandler = function(event) {
if (event && event.data) {
var data = JSON.parse(event.data);
if (data.command === ‘PPCP:prebidResponse’ && data.messageId === lastMessageId) {
if (data.url === ‘unknown’) {
// the prebid process is still pending
setTimeout(function () {
// request url
// ...
}, 100);
}
else if (data.url === ‘failed’) {
// the prebid process did not return an ad
// continue main content
// ...
}
else if (typeof data.url === ‘string’ && data.url.length > 0) {
// prebid successfully selected an ad to play
// play ad
// ...
}
}
}
};