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.

{ "width": 980, "height": 120, "source": "index.html" }
  • 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 defined multiple clicktags inside the metadata file. These will be available inside the creative alongside our default clicktag, mentioned in the previous section.

Let's say that you have defined your creative with the following metadata.json file

{ "width" : 980, "height": 120, "source": "index.html", "clicktags": [ {"clickTAG2": "https://www.advertiser.com/sale"}, {"clickTAG3": "http://www.advertiser.com/more-sale"} ] }

These urls will be prefixed by our click tracking url and 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.

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.

Did this answer your question?