Howto: Deploying Hype animations to DoubleClick Studio

This document was updated February 15, 2018 12:02 PM.

The below instructions are meant for folks who are more comfortable manually modifying code and want to know what's going on under the hood:

Prepare your Tumult Hype document

First, setup your Ad size match one of the available creative sizes supported by DFP.

Download the attached file to follow along with other setup steps: bootsad.zip (971.3 KB)

This page explains how to get an HTML5 document prepared for DFP:

https://support.google.com/richmedia/answer/2672545?hl=en&ref_topic=2672541&rd=1

Filename considerations

Don't use spaces, foreign characters, or symbols in your document name when exporting:

  • Good: 300x340v3
  • Bad: Version 3 (300 x 300)

Doubleclick will display an error if your document name is too long, or if you have any spaces or foreign characters in your document name.

Images

  • The only image formats supported by DFP are jpg, png, and gif.

If you're curious about what Hype exports (and what each file does) please read this post.

Add the Enabler

First, add the enabler to the head of your document:

<script src="https://s0.2mdn.net/ads/studio/Enabler.js"> </script>

This allows tracking impressions and clicks in the creative.

Handle Ad Loading

At a minimum, you need to make sure your document doesn't load until the enabler has loaded. Please look at the EnablerListener script to see how we accomplish this. On the Main Timeline, the Tumult Hype document is paused. Only when the Enabler has loaded do we 'continue' the timeline with this function:

hypeDocument.continueTimelineNamed('Main Timeline', hypeDocument.kDirectionForward);

DFP offers other options for loading. You can load the ad when the content on the page has fully loaded, or only when the ad is visible. Those options are explained here. I have also gone ahead and added the relevant functions to the EnablerListener function for easy access. Just move the 'continueTimeline' function above into your preferred location.

Create an Exit

The other requirement is setting up an HTML5 Exit. This tracks actual clicks on your ad. Please see this thread for the most recent method of creating an exit:

Use a Macro to define the exit URL

Another method of creating an exit is to run a JavaScript function that loads a URL macro. To do this, add the function below to the <head> of your document. You can edit the contents of the <head>…</head> of your exported .html file by clicking on 'Edit HTML Head' in the Document Inspector:

function clickURLTriggered() {
  window.open('%%CLICK_URL_UNESC%%',
  '_blank' // <- This could be _self to open in the same window.
);
} 

This variable would be replaced with the actual URL on document load by the enabler you use and will open the URL in a new window.

In Hype, you can run this function 'On Click' for the element you choose:

clickURLTriggered();

Use a CDN

Now that your document is ready to go, export your document to your computer, and then upload it to a CDN.

In my test I uploaded it to a S3 bucket with cloudfront enabled. This is a highly performant CDN with edge locations all around the world. The example below uses standard S3 bucket URLs, but a Cloudfront URL would look like this: https://dvrsamfw89lsr.cloudfront.net/BootsAd/bootsad.html

I uploaded my bootstest.html document to the following directory:

http://cloudfrontzone.s3.amazonaws.com/BootsAd/

I then edited my bootsad.html document and made some adjustments so that HYPE.js and the Generated .js file are both loaded from absolute URLs. First, I included a reference to HYPE.js in the head of the document:

<script src="//cloudfrontzone.s3.amazonaws.com/BootsAd/bootsad.hyperesources/HYPE-458.full.min.js"></script>

I also modified the source of the generated JS file:

//cloudfrontzone.s3.amazonaws.com/BootsAd/bootsad.hyperesources/bootsad_hype_generated_script.js?74860

I use // instead of http:// so that the ad correctly appears on unencrypted and encrypted pages.

Polite Loading

The DoubleClick enabler has functions built in which detect if your document has loaded. You can run this function 'On Scene Load' to perform certain actions based on whether your document has been downloaded fully, is visible, or both:

Using Adwords?

Start here: Google Adwords (Google Ads) Best Practices

The information below is the manual approach:

If you're deploying this ad on Adwords, you'll be uploading a ZIP file to their server. Currently, Adwords throws an error based on Hype's Script reference, which includes a query string:

"/bootsad.hyperesources/bootsad_hype_generated_script.js?74860"

Just remove that string if you're uploading to Adwords so that it reads:

"/bootsad.hyperesources/bootsad_hype_generated_script.js"

Testing Time

Make sure your Exits are being tracked, and make use of console.log entries to ensure other events have been logged.

6 Likes

Hey Daniel!

Is this method actually working or was changed a while ago?

Please update me, very insterested here.

Thank you!

This was tested and updated in the last month. Let me know if you have any issues!

Hey Daniel,

I’m not being able to insert proper Click Macros to my HTML… example: http://storage.googleapis.com/postedin-ads/sony-5.html

So on the button I am adding the URL as: %%CLICK_URL_UNESC%%http://www.postedin.com which fails to parse when I save the banners code:

sony-5 html { height:100%; } body { background-color: #FFFFFF; margin:0; height:100%; }
<!-- copy these lines to your document head: -->

<meta name="viewport" content="user-scalable=yes, width=300" />

<script src="https://s0.2mdn.net/ads/studio/Enabler.js"> </script>
<script>hypeDocument.continueTimelineNamed('Main Timeline', hypeDocument.kDirectionForward);</script>
<!-- end copy -->
<!-- copy these lines to your document: -->

<div id="sony5_hype_container" style="margin:auto;position:relative;width:300px;height:250px;overflow:hidden;" aria-live="polite">
	<script type="text/javascript" charset="utf-8" src="http://storage.googleapis.com/postedin-ads/sony-5.hyperesources/sony5_hype_generated_script.js?57637"></script>
</div>

<!-- end copy -->

or is there any other special way I can be sure click elements can be tracked by DFP? because we need to enter their MACROS somewhere

You may need to insert your URL in the inner HTML of a rectangle using the following format:

<a href='%%CLICK_URL_UNESC%%%%DEST_URL_ESC%%' target="_blank">
    <img src='//www.google.com/img.gif'>
</a>

There’s more info here: https://support.google.com/dfp_premium/answer/6081628?hl=en

This may not be working because the ‘Enabler’ is running prior to the Hype JavaScript being loaded. I recommend using the HTML5 Exit: https://support.google.com/richmedia/answer/2672517?hl=en&ref_topic=2672541 – Or do you have multiple exits?

Where should I add this exit code? (I’m new to Hype)

Can you give me in here?

Thank you!

The exit code can be added by following the ‘Create an Exit’ section in the first post on this thread. The actual link you use for your Exit URL is set in the creative settings for your ad.

I’m running into a similar issue – My publishers want me to embed a Click macro (%%CLICK_URL_UNESC%%) – My banner is fairly straight forward and the publisher hasn’t mentioned anything about needing an HTML5 exit. Rather they keep saying they need the macro. Can I just create a rectangle and assign a click event to it and put the macro as the url?

Hi Thomas:

Please add this function to the <head> of your document. You can edit the contents of the <head>…</head> of your exported .html file by clicking on ‘Edit HTML Head’ in the Document Inspector:

function clickURLTriggered() {
  window.open('%%CLICK_URL_UNESC%%',
  '_blank' // <- This could be _self to open in the same window.
);
} 

This variable would be replaced with the actual URL on document load by the enabler you use and will open the URL in a new window.

In Hype, you can run this function ‘On Click’ for the element you choose:

clickURLTriggered();

How would you append a variable to the end of the URL exit? DC has the Enabler.exitQueryString(id, opt_queryString); call, but I can’t seem to get it to work.

Hi,

As of Oct 2015, your ‘Create an Exit’ solution is no longer recognized in DFP or DCS.

When using the following function, we are able to specify and click-through to the target URL during preview, but Google still doesn’t count it as an exit, thus preventing ad upload:

function bgExitHandler(e) {
  Enabler.exitOverride('Background Exit', 'http://www.permanent-url.com');
}

document.getElementById('bg-exit').addEventListener('click', bgExitHandler, false);

Please let me know if I can provide further insight.

After much troubleshooting we did find a solution, we posted that solution here, specifically Jon’s response marked ‘solution.’ Hope that helps!

Also, below is the basic clickTag functionality we mainly use for more simple ads requiring only one tag:

Inside head tag paste the following script and specify target URL:

<head>
<script type="text/javascript"> var clickTag = "http://www.YOUR-URL.com";</script>
</head>

After exporting from Hype, in a code text editor (such as Dreamweaver or Sublime Text), around the main div tag paste the following a href:

<a href="javascript:window.open(window.clickTag)">
MAIN DIV
</a>
5 Likes

Thanks for posting your solution, Alex. I’ve updated the post above with this simplified example and the multiple exit example. Thanks @jonathan.larson!

Hey guys,
I’m a designer (not really familiar with functions) who have been creating Flash banners since forever, trying to take a smooth turn to H5, but I’m having quite a hard time following all this information about exits!

What is the difference between clickTags and exits? If my banners have to be iAB compliant as well as for Double-Click + AdWords, what would be the best practice?

I’m posting here 300x250_test4.zip (161.0 KB) a quite simple ad I did and I was wondering if someone could fix it and resend so I can finally understand where to put what!

And maybe you could add this banner as a template in the “Seeking Ad platform templates” thread? I would be glad to help others!

Thanks for your help!

1 Like

Hi @KargoGrafik

OK. I'll try to make a few things clear.

I'm assuming (because you mentioned that you created Flash banners) that you understand the 'clickTag' reference. Basically, this enables the advertisers to track the click throughs and from where they came. So, you have a banner, you click it, it takes you somewhere but records which site you clicked it on. (Apologies if it sounds like I'm stating the obvious)

Now, an 'exit' is kind of what it implies. Example, you have a banner, it has multiple pages through some kind of animation and you have a way to click on it to go to wherever it needs to go. But, you have many ways to click on it, like on page 1, 4, 6 etc. These are your 'exits' so using the Enabler script you can easily add these 'exits' to your banner.

I'll have a look at this and post back with possible solutions.

Edit Ok, after a quick look I've changed your document.

• In the Head HTML I have included the functions for 2 exits.
• In the document scene I have placed the calls for these exits inside the innerHTML of 2 objects: The 'Click' object which is covering the whole advert and the 'button'.

Here I've placed a call to the respective function on click. They both have ID's "bg-exit-1" and "bg-exit-2" respectively.

300x250_test4vDBear.hype.zip (89.9 KB)

Good idea.

Great! Thank you @DBear for your answer! I was not that far from understanding which is a good thing!

But i still wonder, if I need to track those exits on DFP, I would give them a URL with a tracking code instead of using the clickTag function?

But iAB recommends to use clickTags on Ad servers, so in the html exported file, I would wrap the main div in a anchor tag? and remove the exits?

ex. :

 <script>
    var clickArea = document.getElementById("clickArea");
   clickArea.href = clickTag;
</script>


<a href="http://google.com" id="clickArea" target="_blank">
	<div id="300x250test4vdbear_hype_container"></div>
</a>

And I would have to create a version of the banner for each ad servers or websites, according to their specific needs?

Thanks again!

Hi @KargoGrafik

I must admit I haven’t worked on any banners. I’m just following the logic. Saying that I’ve just read up on DCM’s (Double-click Campaign Manager) “How to prepare HTML5 assets”

Basically in your case it look like you want an “exit” using the button at the end of your animation? *This is an assumption.

In this case you would just add a simple piece of code in the Head HTML:

<script>
var clickTag = "YOUR URL";
</script>

then whichever elements you want to use as an exit click you would just create a “New Function…” and call it whatever you want and then place this code inside:

window.open(window.clickTag);

The Enabler way of doing things is for more than one “Tag” and to be honest I’m not entirely confident as to when and why you would use it. As a person who has never created or used banners I would have to say I’m no expert but the logic seems sound.

Edit Having looked at this a bit more at google support, if you use the Enabler script you don’t need to use a “clickTag” URL. It’s simply another way of creating exits and will be ok for DoubleClick. So if you want to create more “Exits” then use the Enabler way in the example.

In Summary, I would use the steps I’ve just outlined. If it doesn’t work then perhaps as suggested above placing this code around the div that is created after export should be the solution.

<a href="javascript:window.open(window.clickTag)">
<div id="whatever_hype_container" style.....
</a>

I hope this helps.

1 Like

I have a button (image) at the bottom of each slide. I placed the

var clickTag = “YOUR URL”;

in the header and created an onClick function

function clickTagGoogleDCM {
window.open(window.clickTag);
}
I load into the DoubleClick Campaign Manager HTML5 Validator and all is well. No errors and success message for tracking when I click the button. I tested this from hype in the browser and it works with no problems.
My problem is in hype reflect. When I test this on my iphone the button does nothing.
Can anyone shed any light on this.
thanks in advance

I recommend testing your clicks only after posting on a server. My guess is that double click throws an error when loading the files from a local server. Hype reflect loads from the local area network.