Impression Script

Introduction

A flexible script to be used on the demand side, which requests a 1x1 transparent GIF file from our server whilst capturing parameters passed in the URL. These parameters are populated with values dictated by us or auto-populated by the demand side platform, commonly DSPs.

The script can be embedded into the HTML5 creative, if this is what is required by the DSP or inserted into dedicated fields in the DSP designed to reference impression pixels.

The format of the impression pixel script will vary and will depend on the installation protocols of the buy-side platform.

Basic Structure

The basic structure is as follows:

CODE

<img src="https://api.anonymised.io/v3/public/img?{querystringparameters}/>

Where:

https://api.anonymised.io/v3/public/img is the GIF endpoint, and
?{querystringparameters} is the data to be passed for the impression

In addition, if the impression script is being installed in environments where HTML validation is required, rare but possible, the attributes such as style and alt may be introduced. This will not usually be the case for DSP implementations.

Installation examples

Please see the following examples for illustrations of different scenarios; this is not intended to be a comprehensive list:

Standard JavaScript + <img> beacon

CODE

<script>
  (function() {
    var img = new Image(1, 1);
    img.src = "https://api.anonymised.io/v3/public/img?{querystringparameters}";
    img.alt = "";
    img.style.display = "none";
    document.body.appendChild(img);
  })();
</script>

This is the most common form in programmatic creatives — it injects a hidden 1×1 pixel dynamically when the creative renders.

Static <img> fallback (non-JS environments)

CODE

<img src="https://api.anonymised.io/v3/public/img?{querystringparameters}"
     width="1" height="1" alt="" style="display:none;" />

Even if JavaScript fails, this will still generate an HTTP request to the tracker.

<noscript> fallback (for script-blocked browsers or email clients)

CODE

<noscript>
  <img src="https://api.anonymised.io/v3/public/img?{querystringparameters}"
       width="1" height="1" alt="" style="display:none;" />
</noscript>

If JavaScript is disabled, this ensures the pixel still fires.

<iframe> beacon (used when isolation or sandboxing is required)

CODE

<iframe src="https://api.anonymised.io/v3/public/img?{querystringparameters}"
        width="1" height="1" frameborder="0" scrolling="no"
        style="display:none;" title="impression-tracker"></iframe>

Typical DSP-safe version

CODE

<img src="https://api.anonymised.io/v3/public/img?{querystringparameters}"/>

The DSP will usually:

Insert its own width/height attributes (if needed).
Insert the appropriate query string parameter values as directed.
Handle whether the beacon is visible or hidden.
Fire it automatically when the ad is rendered.~

Guidance on the Query String Parameters

Query string parameters are optional, but for the impression script to successfully record an impression, they should be populated as per the buy-side platforms capabilities.

It is expected that the line item ID and the creative ID should be passed as a minimum.

The impression script currently supports these parameters. Note these are the names of the parameters and not the values:

Parameter name	Purpose
itId	Identifies the frequency capping settings to use [currently obsolete]
clientId	Allows the clientId to be sent. Accompanied itId for frequency capping
campaignId	Allows the buy-side platform, typically a DSP, to pass the campaign id
creativeId	Allows the buy-side platform, typically a DSP, to pass the creative id
publisherId	Allows the buy-side platform, typically a DSP, to pass the publisher id
placementId	Allows the buy-side platform, typically a DSP, to pass the placement id
ePlacementId	Allows CM360, a buy-side ad server to pass an external placement id
anonId	A wildcard parameter enabling anything else to be sent
dealId	Allows the buy-side platform, typically a DSP, to pass the deal id
advertiserId	Allows the buy-side platform, typically a DSP, to pass the advertiser id
publisherName	Allows the buy-side platform, typically a DSP, to pass the publisher name

Notes:

The order of the query string parameters is irrelevant.
Always check with the buy side platform on how and what data can be sent before recommending params.

DV360 QSP example

The example below is not exhaustive, please refer to the DV360 support documentation on which macros are available: https://support.google.com/displayvideo/answer/2789508?hl=en

CODE

<img src="https://api.anonymised.io/v3/public/img?campaignId=${CAMPAIGN_ID}
&creativeId=${CREATIVE_ID}&publisherId=${PUBLISHER_ID}&cb=${CACHEBUSTER}"/>

Notes:

Line wrapping is used to ease reading, but the impression script can be written as a continuous single line.
&cb=${CACHEBUSTER} is a cache busting instruction and so the parameter can be named anything.

CM360 QSP example

The example below is not exhaustive, please refer to the CM360 support documentation on which macros are available: https://support.google.com/campaignmanager/table/6096962?hl=en&sjid=2478016180863597861-EU#exp

CODE

<img src="https://api.anonymised.io/v3/public/img?campaignId=%ebuy!
&creativeId=%ecid!&cb=%n"/>

Notes:

Line wrapping is used to ease reading, but the impression script can be written as a continuous single line.
&cb=${CACHEBUSTER} is a cache busting instruction and so the parameter can be named anything.

Other things to note

In all cases the impression will also capture:
1. IP address
2. Useragent
3. Timestamp

Recommended approach

Establish the practice used in the buy-side platform for deploying impression scripts and replicate accordingly. The impression script is flexible to accommodate most implementations.