Search
Clear search
Close search
Google apps
Main menu
true

Pixel Loader

Pixel Loader helps load URLs (typically a 1x1 tracking pixel URL) in rich media creatives. This custom element handles pixel load on specific creative events, such as interaction, user click, after a video starts playing, and more.

Features

  • Supports a wide range of events, including:
  • URL validation
  • Cache busting

Prerequisites

  • Your creative must be built as an HTML5 creative.
  • You must import the DoubleClick Studio Enabler into your HTML file.
  • You must import the Polymer custom elements library into your HTML file.

Imports

Before using the Pixel Loader custom element, you must first include these scripts in the head of your creative's HTML file.

  1. DoubleClick Studio Enabler, the core code library of DoubleClick Studio.
  2. Polymer custom elements library, allows the creation of custom HTML elements that are reusable, encapsulated and can work for both desktop and mobile.
  3. Pixel Loader custom element library.
<script src="//s0.2mdn.net/ads/studio/Enabler.js"></script>
<script src="//www.gstatic.com/external_hosted/polymer/custom.elements.min.js"></script>
<script src="//www.gstatic.com/ads/ci/studio/pixelloader/1/pixelloader_min.js"></script>

Set up the custom element

There are two ways to add the custom element to your creative. You can either add the Pixel Loader tag to your HTML, or create an instance in your JavaScript.

Choose one of the options below:

Add the Pixel Loader custom element tag to your HTML file
<ci-studio-pixelloader
  eventtype="auto"
  url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
Create an instance of the PixelLoader class in your JavaScript file
var pixel = document.createElement('ci-studio-pixelloader');
pixel.setAttribute('eventtype', 'auto');
pixel.setAttribute('url', 'https://example.com/yourpixel.gif?ord=[timestamp]');

Customize custom element settings

Use custom element attributes to choose which event triggers your pixel URL. Expand the sections below to learn about available attributes and see example tags.

Event target

Set which object you want to listen to events from. This attribute works together with the eventtype attribute to target specific events.

  • eventtarget The name of the object to listen for events from.
    Valid values: dom, enabler, ytplayer.
Example tag

To listen to any Studio Event, you must first set the eventtarget to enabler. The example below loads a pixel on interaction.

<ci-studio-pixelloader
    eventtarget="enabler"
    eventtype="interaction"
    url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
Event type

Set which event type will load the pixel URL. Works together with eventtarget to target specific events. You can also set the eventtype to auto or manual for events that do not rely on an event target. See Automatic and manual loading below.

  • eventtype The name of the event to load the tracking pixel URL on.
    Valid values: auto, manual, StudioEvents when you set the eventtarget to enabler, DOM Events or MediaEvents when you set the eventtarget to dom.
Example tag

To load a pixel on a Studio exit event, use the example below, replacing the example pixel URL with your actual pixel URL.

<ci-studio-pixelloader
    eventtarget="enabler"
    eventtype="exit"
    url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
Pixel URL

Assign the URL of the pixel to load. The URL must begin with http:// or https://.

  • url The url of the 1x1 tracking pixel to load.
    Valid value: A url that begins with http:// or https://.

Cache-busting

Add the [timestamp] macro to your url to enable cache-busting. This keeps your pixel loading freshly with each ad load rather than being loaded from cache by the browser.

https://example.com/pixel.gif?ord=[timestamp] automatically becomes https://example.com/pixel.gif?ord=123456789. The number used here is just an example. When your ad is served, this will be replaced with a unique number.

URL validation

Html enitites for the ampersand character (&amp;) are replaced automatically.

https://example.com/pixel.gif?ord=[timestamp]&amp;foo=bar automatically becomes https://example.com/pixel.gif?ord=[timestamp]&foo=bar.

Example tag

Set a pixel URL with cache-busting for the example pixel URL
https://example.com/yourpixel.gif:

<ci-studio-pixelloader
    eventtarget="enabler"
    eventtype="exit"
    url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
Cumulative pixel loading

By default, pixels are only loaded the first time an event, for example, an exit, occurs. If you want the pixel to load every time the event occurs, set the cumulative attribute to true.

  • cumulative Whether to load the pixel every time the event occurs, or only the first time.
    Valid values: false or true.
    Default: false.

Example cumulative tag

Load the pixel URL every time the exit event occurs:

<ci-studio-pixelloader
    eventtarget="enabler"
    eventtype="exit"
    cumulative="true"
    url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
Load on a specific exit event

If you have multiple exit events in your creative, and want a pixel to load on only one specific exit event, use the exitname attribute to specify which exit should trigger the pixel to load.

  • exitname The name of the exit event that should load the pixel.
    Valid value: The name of the exit event.
  • eventtype The event type to load the tracking pixel URL on. You must use a value of "exit" for the exitname setting to work.
Example specific exit event tag

Load the pixel URL when an exit event named myExit occurs:

<ci-studio-pixelloader
    eventtarget="enabler"
    eventtype="exit"
    exitname="myExit"
    url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
Load on a DOM element event

To load a pixel when a DOM element event occurs, set the eventtarget to dom and set the domelementid attribute to the ID of the DOM element to listen to.

  • domelementid The ID of the DOM element to listen to an event from.
    Valid value: A DOM element ID.
  • eventtarget Use a value of dom to target DOM events.
  • eventtype The name of the event to load the tracking pixel URL on.
    Valid value: The DOM event that will load the pixel.
Example DOM event tag

Load the pixel URL when an element named myElement is clicked:

<ci-studio-pixelloader
    eventtarget="dom"
    eventtype="click"
    domelementid="myElement"
    url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
Load after user interaction

To load a pixel after user interaction, set the eventtarget to enabler and set the eventtype to interaction.

  • eventtarget Use a value of enabler to target Enabler events.
  • eventtype Use a value of interaction to load a pixel when the Studio user interaction event occurs.
Example interaction event tag

Load the pixel URL after a Studio user interaction event:

<ci-studio-pixelloader
    eventtarget="enabler"
    eventtype="interaction"
    url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
Load when a video begins playing

Pixel Loader supports video events from Google Web Designer's YouTube player elements, HTML5 video elements, and YouTube's JavaScript player. Expand the examples below to see how.

Google Web Designer's YouTube player example

Listen to a "playing" event:

// Sample Google Web Designer YouTube player.
<gwd-youtube id="gwdplayer"
    video-url="//www.youtube.com/watch?v=M7FIvfx5J10">
</gwd-youtube>

// Listen to the playing event from DOM element gwdplayer.
<ci-studio-pixelloader
    eventtarget="dom"
    eventtype="playing"
    domelementid="gwdplayer"
    url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
HTML5 video element example

Listen to a play event from an HTML5 video element with the id myVideo:

// Sample video element.
<video
    id="myVideo"
    controls=""
    preload="none"
    poster="http://media.w3.org/2010/05/sintel/poster.png"
    width="300">
<source id="mp4" src="http://media.w3.org/2010/05/sintel/trailer.mp4"     type="video/mp4">
<source id="webm" src="http://media.w3.org/2010/05/sintel/trailer.webm"     type="video/webm">
<source id="ogv" src="http://media.w3.org/2010/05/sintel/trailer.ogv"     type="video/ogg">
<p>Your user agent does not support the HTML5 Video element.</p>
</video>

// Listen for the play event from the DOM element myVideo.
<ci-studio-pixelloader
    eventtarget="dom"
    eventtype="play"
    domelementid="myVideo"
    url="https://example.com/yourpixel.gif?ord=[timestamp]">
</ci-studio-pixelloader>
YouTube JavaScript player example

Set up Pixel Loader via the JavaScript rather than using the custom element when you want to listen to YouTube player events. Pixel Loader has a setupYTPlayer() method to support events from the standard YouTube player API or from studioinnovation.YTPlayer. The setupYTPlayer() method accepts 3 parameters:

  • ytplayer The instance name of the YouTube player in your creative.
  • eventType The event type to listen to, in this case, playing
  • url The url of the pixel to load on the video playing event.
// Sample YouTube player.
var player = new YT.Player('ytpapi-container', {
    width: 300,
    height: 200,
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      autoplay: 0,
      enablejsapi: 1,
      html5: 1,
    }
});

// Create an instance of Pixel Loader with JavaScript.
var pixelloader = new ci.studio.pixelloader.PixelLoader();

// Use setupYTPlayer() to listen to the playing event.
pixelloader.setupYTPlayer(
    player,
    'playing',
    'http://example.com/pixel.gif?ord=[timestamp]');

Automatic and manual loading

If you want to load a pixel on an event not tied to an event target, you can set the eventtype to either auto or manual.

  • auto Loads the pixel as soon as the custom element is loaded.
    Example auto loading tag

    To load a pixel automatically as soon as the custom element is loaded:

    <ci-studio-pixelloader
        eventtype="auto"
        url="https://example.com/yourpixel.gif?ord=[timestamp]">
    </ci-studio-pixelloader>
  • manual Loads the pixel only when the load() method is called via JavaScript.
    Example manual loading tag

    To load a pixel manually, set eventtype to manual, and call the load() method on the custom element. The example below calls the load() method from a button element's click event handler.

    <ci-studio-pixelloader
        id="manualPixelLoader"
        eventtype="manual"
        url="https://example.com/yourpixel.gif?ord=[timestamp]">
    </ci-studio-pixelloader>

    <button     onclick="document.getElementById('manualPixelLoader').load()">Load</button>
Was this article helpful?
How can we improve it?