Communication Between Cross Player Prebid Component and Player

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:

  • If the Component is loaded within the same document where the Player is located, either in the header or in the body of the document, the publisher’s code has to invoke ‘postMessage’ on the Player’s window.
    • Example: window.postMessage ('hello', '*');
  • If the Component is loaded in the header of a document that is different from the document where the Player is loaded (for example, in an IFrame), then the publisher’s code must invoke the ‘postMessage’ on the ‘top’ window.
    • Example: top.postMessage ('hello', '*');
  • The publisher’s code must listen for a response via ‘postMessage’ on the Player’s window.
    • Example: window.addEventLIstener('message', listenerHandler);

Message Content

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.

Player Request for Prebid Results

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:

  • command - Value MUST be PPCP:prebidUrlRequest.
  • messageId - Integer to uniquely identify each request.

The message should be converted to a String using JSON.stringify before passing it into the postMessage.

Prebid Component Response

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:

  • command - Value MUST be PPCP:prebidResponse.
  • messageId - Integer to uniquely identify each request; this value will match the messageId of the request message.
  • url - Value will be a String containing one of the following values:
    • a URL to VAST XML (Prebid successfully selected an ad to play).
    • ‘unknown’ - The Prebid process is still pending.
    • ‘failed’ - The Prebid process did not return an ad.

The message should be converted to a String using JSON.stringify before passing it into the postMessage.

Communication Steps

NOTE: These steps assume that the Component is being loaded in the header and the Player is loaded in an IFrame.

Step 1

  • Who: Prebid Component
  • What: Adds a listener on the window within the document where it is running
  • Comments: The Component is listening for the following command in a postMessage: PPCP:prebidUrlRequest. Filter the messages looking for this command inside the requestHandler.
Sample Request Handler
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');
            }
        }
    }
};

Step 2

  • Who: Player
  • What: Adds a listener on the player window, looking for a message that contains a response from the Component.
  • Comments: The Player is listening for the following command in a postMessage: PPCP:prebidResponse. Filter the messages looking for this command inside the responseHandler.
Sample Response Handler
window.addEventListener('message', responseHandler);

Step 3

  • Who: Player
  • What: Sends a postMessage to the top window when it is ready for the results of the Prebid process.
  • Comments: The Player posts a message with the following command: PPCP:prebidUrlRequest to request Prebid results from the Component.
Sample Code for PPCP:prebidUrlRequest

NOTE: The * argument indicates post the message to any domain.

const msg = {};

msg.command = 'PPCP:prebidUrlRequest';
msg.messageId = 1234;

top.postMessage(JSON.stringify(msg), '*');

Step 4

  • Who: Prebid Component

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

  • Comments: 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:
    • unknown: Prebid results are not yet ready.
    • failed: Prebid returned NO ad.
    • VAST XML: Prebid has returned back the URL to the XML of the selected ad.
Sample Code PPCP:prebidResponse

NOTE: The * 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), '*');

Step 5

  • Who: Player
  • What: Once the Component has received the Prebid results using the listener for response message, the Player should do one of the following:
    • Render the winning ad (if the results were valid).
    • Skip the ad and start the video content (if Prebid returned a failed response).
    • Send another request for Prebid results (if the results are still unknown to the Component).
  • Comments: The Player posts a message with the following command: PPCP:prebidUrlRequest to request Prebid results from the Component.
    • 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.
Sample Code Response Handler (Step 5)
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
                // ...
            }
        }
    }
};

Further Reading