HTML5 Creatives | BidTheatre Help Center

All uploads of HTML5 creatives are done via the "drag and drop"-box in the Setup / Ad creatives view or any of the html5-ad and magic-ad endpoints in our API.

File Structure

Each HTML5 banner should be archived as a ZIP-file that contains at least the files listed below. When creating the ZIP file make sure to archive only the files and subfolders, not the parent folder that contains all files.

a metadata file called metadata.json, this file defines the banner size and its main html-source. This file is placed in the root folder of the zip archive. The name property is optional, if not included the creative will be given a default name based on the campaign name and ad size.

{ "width": 980, "height": 240, "source": "index.html", "name": "980x240 - version 2.1" }

the source HTML-file as specified in the metadata file. This file is also placed in the root folder of the zip archive.
all other resources, javascript, images, fonts etc., could be loaded from a local directory or an external path. If an external path is used, see the section below about secure invokations for ways to make your creative HTTPS-compatible.
make sure no illegal characters are used in file or directory names, typically space or dot (besides to indicate file endings).

Clicktag

It is important to incorporate the possibility to click on all creatives served. The clickurl to be used can be retrieved in the following way. Begin by including our helper script

<script src="https://adsby.bidtheatre.com/js/asxhtml5.min.js"></script>

The clickurl is then retrieved with the following function call. The second part of the function call is what to use as a default value if no specific clickurl is found (typically the case during development)

var clickurl = asxhtml5.getParam('clickurl', 'https://www.advertiser.com');

The actually implementation of the clicktag can be done in many different ways. One is exemplified below.

<div id="banner">
<!-- This is where the actual creative content is displayed -->
 </div> <script> var clickurl = asxhtml5.getParam('clickurl', 'https://www.advertiser.com'); var clickDiv = document.getElementById('banner'); clickDiv.onclick = function() { window.open(clickurl,'_blank'); } </script>

Multiple clicktags

It's possible to define multiple clicktags inside the metadata file. These will be available inside the creative alongside our default clicktag, mentioned in the previous section. If clicks should be routed passed our clicktracking the macro "{clickurl}" should be prefixed to desired landing page. Note that the landingpage must be URL encoded if the click macro is used.

Let's say that you have defined your creative with the following metadata.json file, clickTAG2 will not be routed passed our clicktracking, i.e. we will not track clicks on banner elements with that click tag tied to it, and clickTAG3 will be routed passed our clicktracker and then redirected to the desired landing page. Note that the landingpage must be URL encoded.

{ "width" : 980, "height": 120, "source": "index.html", "clicktags": [ {"clickTAG2": "https://www.advertiser.com/sale"}, {"clickTAG3": "{clickurl}http%3A%2F%2Fwww.advertiser.com%2Fmore-sale"} ] }

These urls will be available inside the creative via the helper script in the following manner

var clickurl2 = asxhtml5.getParam('clickTAG2', 'https://www.advertiser.com/sale');

and

var clickurl3 = asxhtml5.getParam('clickTAG3', 'http://www.advertiser.com/more-sale');

and could be used to send the user to different pages depending on where he or she clicks on the creative.

Clicktags in Google Web Designer

Some combinations of elements can be troublesome to bind our click tracking to, tap areas in ads created in GWD is one known problem. To support clicktracking in these cases our clicktracking needs to be incorporated in the ad when creating it by following these steps

Switch over to GWD Code View and add our helper script in the head-section
Back in "Design view", right click and choose "Add event..." -> Tap Area -> Touch/Click -> Action -> Add Custom Action and add the following code
```
var clickurl = asxhtml5.getParam('clickurl','');
window.open(clickurl,'_blank')
```

Document loaded

Sometimes it can be useful or required to bind the click event when the complete ad have finished loading. We provide a helper function for that, just pass a function with the desired actions to perform when the document have finished loading.

asxhtml5.docReady(function() {
  var elem = document.getElementById("banner");
  var clickurl =   asxhtml5.getParam('clickurl','https://www.bidtheatre.com');

  elem.onclick = function() {
    window.open(clickurl,'_blank');
  }; 
});

Expected parameters

Some applications of HTML5 creatives include the use of feeding dynamic parameters into the creative impression time to display for instance certain product information that differs between each invocation of the ad.

It's possible to define what parameters the ad requires to function properly either in the metadata.json or later manually in asx-studio. An ad that is detected to be configured in such a way that not all mandatory parameters is available to it will not be allowed to go live.

{ "width" : 980, "height": 120, "source": "index.html", "expectedParams": [ {"paramValue": "prod_url", "mandatory": true}, {"paramValue": "prod_price"} ] }

Secure invocations

We recommend that all HTML5 creatives are HTTPS compatible. There are different ways to approach this problem, some of them are listed below:

Load all assets securely all the time
Develop your own solution to determine the protocol based on the protocol of the iframe-src-url.
Use our helper script to retrieve the protocol.

To use our script, start by including it

<script src="https://adsby.bidtheatre.com/js/asxhtml5.min.js"></script>

once that is done, the protocol of the invocation can be retrieved like this. The second part of the function call is what to use as a default value if no protocol information was found.

var protocol = asxhtml5.getParam('protocol', 'https');

Implementation details

All HTML 5 banners will be loaded inside an iframe to guarantee that no scripts or styles leaks from the page to creative or vice versa. The protocol and clickurl will be transfered into the iframe via standard HTML-parameters. The actual HTML code invoking the creative will look something along the lines of this. If multiple clicktags is used they will be appended after the clickurl-paramter.

<iframe id='asx_1443448197270_iframe' name='asx_1443448197270_iframe' src='about:blank' border='0' frameborder='0' marginwidth='0' marginheight='0' scrolling='no' width='980' height='120'></iframe> <script> var asx_proto = '{protocol}'; var asx_clickurl = encodeURIComponent('{clickurl}'); var asx_uri = '{protocol}://creatives.bidtheatre.com/html5/2339/4A861/index.html?protocol=' + asx_proto + '&clickurl=' + asx_clickurl; document.getElementById('asx_1443448197270_iframe').src = asx_uri; </script>

Creative preview / testing

To test your creative without actually uploading it as a new creative you can use our HTML5 preview tool, found here https://studio.bidtheatre.com/html5-preview

Multiple sizes

Sometimes the same creative can scale to different sizes and thus be reused for several different creative sizes. The best way to accommodate this is to upload the same creative multiple times with different size-settings in the JSON file.