Creating interactive advertisements

An interactive advertisement is an HTML5 creative (a folder with index.html at its root) that the player renders in a web view. An interactive ad talks to the player through a JavaScript bridge: it receives screen and campaign metadata, controls its own duration and reports playback results back to the platform.

The bridge object is called csBackend and exposes:

  • csBackend.playerData — a JSON object with the data the server sends to the advertisement (see the csPlayerData object for the field list);

  • csBackend.completeData — an object the advertisement fills in; it is sent to the platform after the show ends (e.g. programmatic bid data);

  • csBackend.setDuration(milliseconds) — sets the duration of the current advertisement;

  • csBackend.sendResponse(data) — sends data to the player immediately;

  • events:

    • csBackend.afterPlayerInit — fired when the page has loaded in the background; request your data here;

    • csBackend.beforePlayerShow — fired right before the ad appears on screen; start videos and animations here;

    • csBackend.afterPlayerShow — fired when the show ends; finalize completeData here.

The way csBackend is obtained differs between platforms.

Windows / Linux (Qt player)

On PC the bridge is exposed through Qt WebChannel. Include qwebchannel.js and connect:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Interactive ad</title>
    <script type="text/javascript" src="qrc:///qtwebchannel/qwebchannel.js"></script>
</head>
<body>
    <div style="position: absolute; top: 0px; left: 0px">
        <video muted id="v2"></video>
    </div>
    <script>
        var csBackend;
        var video;
        var metaData;

        new QWebChannel(qt.webChannelTransport, function(channel) {
            // the object with the player data
            csBackend = channel.objects.csBackend;

            // fired when the page has loaded in the background;
            // all data requests belong here
            csBackend.afterPlayerInit.connect(function() {

                // plug in the content
                video = document.getElementById("v2");
                video.setAttribute("src", "video.mp4");

                metaData = JSON.parse(csBackend.playerData);

                // the frame inventory number (gid) is used across systems — rely on it
                console.log(metaData.gid);

                // the frame size — content plays at exactly these dimensions
                console.log("width " + metaData.frameResolution.width);
                console.log("height " + metaData.frameResolution.height);

                // the slot duration in milliseconds; you may skip longer videos
                // or change the ad duration via setDuration
                console.log(metaData.duration);

                // when the advertisement will appear on screen
                var now = Date.now();
                console.log("goes on screen in ms: " +
                    (metaData.showingAdvertisementEndTime - now));
            });

            // fired right before the ad appears on screen
            csBackend.beforePlayerShow.connect(function() {
                video.play();
                csBackend.completeData = {
                    htmlProgrammaticAd: "store the bid and other data of what was shown here"
                };
            });

            // fired right before the show ends
            csBackend.afterPlayerShow.connect(function() {
                console.log("the show has ended");
            });
        });
    </script>
</body>
</html>

To test the creative locally without a CS Play account, run the player in debug mode.

Android

On Android the bridge is initialized through the injected Android object:

<script>
    // init the CS channel
    var csBackend;
    eval(Android.initCsBackend());

    csBackend.afterPlayerInit.connect(function() {
        var metaData = JSON.parse(csBackend.playerData);
        csBackend.setDuration(10000);
        csBackend.completeData = { "complete": "data" };
    });

    csBackend.beforePlayerShow.connect(function() {
        // start playback
    });

    csBackend.afterPlayerShow.connect(function() {
        var completeData = JSON.stringify(csBackend.completeData);
        Android.afterPlayerShow(completeData);
    });
</script>

The csBackend API surface (fields, methods and events) is the same as on PC. Note the extra Android.afterPlayerShow(completeData) call that hands the results back to the player.

Smart TV (Tizen / webOS)

On Smart TV the player is a web application. Interactive content receives lifecycle events via postMessage — see CS Player on Smart TV for the event subscription example and the rules for HTML content.

Delivering files to the player

An interactive advertisement is uploaded to the media library as an archive. If the creative needs data files updated at runtime (prices, schedules, media), configure FTP synchronization for it.