HTML5 Banner Ads With CreateJS
14 | 15 | 16 | 17 |Preamble
18 | 19 |This is a living document. It will be updated as standards and best practices evolve. See Appendix: Document History for a list of changes. The source, along with supporting materials, examples, and helper classes is available at github.com/createjs/html5ads/, and contributions are welcome.
20 | 21 |The content of this document is copyrighted, and is licensed under the Creative Commons Attribution license.
22 | 23 |Introduction
24 | 25 |The online advertising industry has been subject to numerous disruptive changes recently. Traditionally, most ads were built with Flash Pro and dependent on the Flash plugin. The rise of mobile browsing on platforms that do not support plugins has provided an increasingly compelling reason to find alternative workflows, but Google's recent move to block Flash ads in Chrome, and Amazon no longer accepting these ads make finding new solutions imperative.
26 | 27 |This article explores how the CreateJS suite of libraries allows ad creators to transition easily to HTML5/JS, examines how the libraries fit into emerging IAB (Interactive Advertising Bureau) standards, and provides guidance for creators making the transition. Workflows using the new HTML5 Canvas publish target for Flash Pro will also be discussed, including how it boosts productivity and allows ad creators to leverage prior experience or even convert existing ads.
28 | 29 |Appendixes provide more in-depth information on technical topics.
30 | 31 |Authors
32 | 33 |This document was authored by:
34 | 35 |Grant Skinner, CEO gskinner, inc.
36 | 37 |Grant and his team at gskinner conceptualize, design, and build world-class interactive experiences for smart clients such as Microsoft, Google, Mozilla, and EA. He has spoken at hundreds of events on five continents about interactive design and development. He heads the development of CreateJS, and partnered closely with Adobe to lead the development of the HTML5 Canvas publishing for Flash Professional.
38 | 39 |Cory Hudson, Sr. Director, Creative Technology, AOL
40 | 41 |Cory leads a large team of interactive designers and front-end developers who are entirely focused on building feature-rich, cross-screen advertising experiences. His team is directly responsible for developing highly engaging creative solutions and driving technical R&D initiatives in order to effectively evaluate and leverage emerging technologies within AOL's digital advertising formats and platforms. Cory also serves as Chair of the IAB's HTML5 Working Group, where he leads an industry-wide group of experts who are collaboratively working to establish standardized best practices and guidelines for HTML5 based digital advertising.
42 | 43 |Emerging IAB Standards
44 | 45 |The Interactive Advertising Bureau (IAB) recognizes that the industry's long established digital advertising specs tailored to the SWF file format are no longer viable for HTML5-based advertising. With HTML5 there is no longer a convenient dependency upon a single, optimized creative asset package, but rather a compilation of separate assets that must be created, optimized, measured and evaluated individually, while collectively adhering to standardized specs.
46 | 47 |This introduces several new obstacles that must be adequately accounted for in order to successfully deliver a compliant advertising experience. The challenges that HTML5 faces when compared to Flash are mainly the required overall file size and number of HTTP server requests associated with an ad unit.
48 | 49 |File Size
50 | 51 |Client bandwidth has increased significantly since the 40kB file size limitation was first introduced. Additionally, the realities of building HTML5-based ad units make it more challenging to adhere to this limit.
52 | 53 |Based on these factors, a desire to enable richer ad experiences, and in accordance with the results of recent IAB sponsored industry-wide performance testing, the IAB is proposing an increase in the file size standard for most HTML5 ad formats to 200kB.
54 | 55 |Because most ad networks and browsers automatically gzip files crossing the network, file size will be calculated by combining the total gzipped, wire-weights of all utilized assets that are initially required in order for the ad to display in a local, standalone environment. This includes all local images, CSS, JS, HTML, etc.
56 | 57 |Shared Libraries Exception
58 | 59 |The sole exception to the file-size policy is CDN hosted JavaScript libraries that are granted an exception by the publisher or ad server, because these common libraries are leveraged across multiple campaigns and can be cached by users' browsers. A number of ad networks are already supporting this exception for CreateJS (ex. CoFactor/Pointroll, AOL).
60 | 61 |CreateJS is on a shortlist of suitable libraries (widely used and distributed, professionally maintained, well documented, frequently updated, backwards compatible) that the IAB will publicly recommend through its soon-to-be-updated and republished HTML5 Best Practices documentation, located at http://www.iab.net/html5. This would ultimately allow ad creators to exclude the file size of the library from the overall 200kB file size calculation.
62 | 63 |CreateJS
64 | 65 |Developed by widely-recognized interactive shop gskinner to facilitate the creation of Flash-like experiences using open web standards (ex. HTML5), CreateJS is a suite of four libraries that accelerate the production of rich interactive experiences such as games, ads, data visualizations, and micro-sites.
66 | 67 |The four libraries in the suite can be used together or completely independently, and are focused on specific areas of functionality.
68 | 69 |EaselJS
70 | 71 |High performance 2D graphics and interaction, with a Flash-inspired display list and feature-rich API.
72 | 73 |SoundJS
74 | 75 |Audio playback and management, with transparent support for WebAudio, Audio elements, and optional Flash plugin fallback.
76 | 77 |PreloadJS
78 | 79 |Robust asset loading and management, with granular progress reports, and nested dependencies.
80 | 81 |TweenJS
82 | 83 |Simple but powerful animation engine with multi-step tweens, synced tweens, non-numeric property support, and motion paths.
84 | 85 |CreateJS has no external dependencies, imposes no specific architectural requirements on your code, and is designed to work seamlessly with almost every other JS library, including favorites like GSAP (aka TweenLite), Three.js, AngularJS, and jQuery.
86 | 87 |It is free and open source, licensed under the permissive MIT license. This means it can be easily incorporated into commercial projects, and the project welcomes contributions and feedback from the community.
88 | 89 |CreateJS is robust and mature. The suite was created and is maintained by a highly experienced team of interactive developers and designers, who have been building rich content for over 15 years using Flash and HTML5. It is over 5 years old, has grown through 8 major releases, and has been sponsored by Adobe, Microsoft, Mozilla, and AOL. CreateJS is used by tens of thousands of developers, with over one third of FWA Site of the Day winners using it, and content built with CreateJS is viewed by hundreds of millions of users every day.
90 | 91 |Flash Professional: HTML5 Canvas
92 | 93 |Great experiences require both code and design. While it's entirely possible to code amazing content with CreateJS, Flash Pro CC empowers designers to engage fully, and boosts productivity by accelerating the creation of art and animation.
94 | 95 |With Flash Pro, you can create an "HTML5 Canvas" document, which will be output as human-readable JavaScript code leveraging the CreateJS libraries when published.
96 | 97 |As is the case for traditional Flash development, it is possible to create interactive banners entirely in Flash with timeline scripting. For more complex projects though, you may realize considerable benefits from using Flash Pro to prepare an asset library of art and animation, then write business logic in your code editor of choice that utilizes those assets.
98 | 99 |This approach provides a clear delineation of roles and asset ownership between developer and designer. Designers own the FLA, and hand off the published assets to a developer, who can integrate them into a larger project, and manage them via version control. The designer never has to worry about the code, and the developer never has to open the FLA or modify the published assets.
100 | 101 |See "Appendix: Designer / Developer Workflow" for more information on this topic.
102 | 103 |Considerations
104 | 105 |While CreateJS and Flash Pro provide a highly productive workflow, and allow you to leverage prior experience with Flash, there are important considerations to keep in mind when getting started.
106 | 107 |Code & API Differences
108 | 109 |CreateJS content is developed using JavaScript, which is very similar to ActionScript, however there are some notable differences that you should be aware of when converting common functionality within Flash Pro CC.
110 | 111 |The most immediate difference is scope, which must be defined explicitly. For example, on the timeline, rather than calling stop(), you must use this.stop().
While the CreateJS API will be very familiar to ActionScript developers, there are significant differences. As examples, only Container and MovieClip can have child objects, and only Shape can draw vector graphics. Timelines are zero based: this.gotoAndStop(0) will take you to the first frame.
More detail on this topic can be found in "Appendix: Code & API Differences".
116 | 117 |Browser Compatibility
118 | 119 |CreateJS is reliably supported by all modern browsers. The only unsupported browser with notable market share is IE8 (<2% market share and dropping) due to its lack of Canvas or Audio support. We recommend providing a fallback static image with a link for unsupported browsers. This can be done with code similar to the following, which prevents the fallback image from loading unless it is needed.
120 | 121 |
122 | <canvas><script>
123 | if (!window.CanvasRenderingContext2D) {
124 | document.write("<a href='url'><img src='image.jpg' alt='text'></a>");
125 | }
126 | </script></canvas>
127 |
128 |
129 | The CreateJS AdHelper class described in "Appendix: AdHelper" simplifies setting up fallback content, and makes the code above unnecessary.
130 | 131 |Load Optimization
132 | 133 |There are a number of strategies and techniques you can employ to reduce the size of the assets used in your ad and ensure it adheres to the 200kB limit specified by the IAB. Minimizing the number of HTTP requests required to display your ad is also important to decrease load times.
134 | 135 |Reducing HTTP Requests
136 | 137 |Recent IAB-sponsored performance testing has indicated that the number of HTTP requests can have a significant impact on the perceived loading performance of the visual ad unit, especially on mobile devices. Minimizing the number of requests allows the browser to optimize and parallelize loads, and reduces the overall time cost for establishing http connections.
138 | 139 |The emerging HTTP2 standard will mitigate this concern by allowing browsers and servers to transfer multiple assets over a single connection.
140 | 141 |Ideally, the number of initial HTTP requests should be kept below 8. This would include all creative assets, CDN hosted and cached support files, and necessary 3rd party impression or click tracking calls.
142 | 143 |Using sprite sheets, code minification / concatenation, and data URIs (for embedded web fonts or SVGs) can all help reduce HTTP connections.
144 | 145 |CreateJS's PreloadJS library provides capabilities for loading assets, including progress events, maintaining dependencies, loading subsequent assets on interaction, and specifying a maximum number of parallel http connections (via queue.maxConnections). EaselJS supports sprite sheets and audio sprites, and Flash Pro allows for the automatic creation of sprite sheets during publishing.
Graphics
148 | 149 |The bulk of file size for most ads is in graphical assets. There are a number of techniques you can use to reduce this cost.
150 | 151 |Vector Graphics
152 | 153 |Vector graphics represent art as a collection of resolution-independent drawing commands. They are especially suited to illustrations and other non-photographic art. Unlike bitmap images, they can be scaled indefinitely and retain full fidelity, which makes them ideal for responsive designs targeting multiple display sizes or densities. When used with appropriate content, vectors can also be much smaller than the equivalent bitmap image.
154 | 155 |The primary disadvantage to using vectors is that rendering performance scales directly with the complexity (ex. number of curves and points) in the graphic. This is especially true on mobile devices where CPUs are slower and less powerful.
156 | 157 |Coding vector graphics manually is possible, but not pragmatic. Luckily, there are several tools that can make working with vector graphics very intuitive. You can create graphics within Flash Pro, or use other software programs such as Adobe Illustrator and then import the result directly into Flash Pro.
158 | 159 |See "Bitmap Caching" below for a technique to reduce the ongoing cost of drawing complex vector graphics.
160 | 161 |Bitmaps
162 | 163 |Bitmaps graphics define the color of every pixel in an image. It is very inexpensive for the GPU to manipulate bitmap images, so leveraging bitmaps within your animations rather than vectors can often provide tremendous performance gains.
164 | 165 |Bitmaps are ideal for photographic images as well as imagery that requires soft-edges and transparency. Using vectors for these types of graphics would require a gratuitous amount of complexity to represent the image detail, resulting in increased file size as well as visual results that don't appear as natural.
166 | 167 |The main disadvantages to using bitmaps is that they come at the expense of increased memory overhead and lack of scalability when compared to vectors. Bitmaps can consume a great deal of both RAM and graphics memory and overuse can cause performance problems on mobile devices. This is especially true with the need to support high DPI screens, which can require you to double the size of images, effectively quadrupling their memory footprint.
168 | 169 |Bitmap Caching
170 | 171 |Similar to Flash Player, EaselJS supports bitmap caching, which allows you to pre-render complex graphics to an off-screen bitmap, so it does not have to be rendered each frame. This can provide significant performance benefits when used appropriately with static art.
172 | 173 |The rules for using bitmap caching are similar to using it with Flash Player: use it only on static content, and only when the complexity of the graphics are sufficient to warrant its use. This is because bitmap caching creates new bitmaps, which use both RAM and graphics memory. The latter is limited on mobile devices and overuse can cause performance problems.
174 | 175 |Bitmap caching can be applied from within Flash Pro via the "cache as bitmap" option, or with code using the cache() method of display objects.
High DPI Screen Support
178 | 179 |In order to ensure that bitmaps are displayed crisply on high DPI screens, they should be created at double the display size and then scaled down accordingly within Flash Pro. For example an image that is intended to display at 300x250, should actually be created at 600x500 and then scaled down to 300x250 within Flash Pro. Alternatively, you could author your FLA at double resolution, and scale it to the appropriate size at runtime.
180 | 181 |This should be approached in a strategic manner in order to avoid the unnecessary bloating of the overall file size associated with your image assets. You can sometimes avoid having to double the dimensions of photographic images that are not the focal point of the ad experience (e.g. photographic background image).
182 | 183 |Conversely, photographic imagery that is the focal point of the ad experience or graphical elements that have sharp, crisp edges such as logos, line artwork and text will most likely always need to be doubled in dimensions because the difference in visual quality is very apparent and noticeable.
184 | 185 |Testing your ad on high DPI devices will allow you to determine which graphics will need to be double-sized or not. With experience you will be able to identify these scenarios readily.
186 | 187 |The CreateJS AdHelper class described in "Appendix: AdHelper" makes it easier to work with high DPI screens, including support for content authored at double scale.
188 | 189 |Compression
190 | 191 |Unfortunately, Flash Pro's default bitmap compression is not very aggressive. You should leverage other image optimization tools such as ImageOptim or ImageAlpha to more fully compress your images. In some cases, these tools can reduce image size by 50-75% without any visible loss in quality. These tools can also be integrated into automated build processes.
192 | 193 |Sprite Sheets
194 | 195 |Sprite sheets combine multiple images or frames of animation onto one larger image, and can dramatically reduce your overall file size and number of server requests.
196 | 197 |It is suggested that you combine similar images into sprite sheets, a single JPG sprite sheet for photographic images with opaque backgrounds and another separate PNG sprite sheet for crisp graphics and imagery that requires transparency. There should generally be no need for more than 2 sprite sheets.
198 | 199 |You can create sprite sheets manually in Photoshop or using standalone tools such as Zoë or TexturePacker. However the easiest way to create sprite sheets when creating ads with Flash Pro is to use its built-in features:
200 | 201 |- Generate Sprite Sheet. Available via the Flash Pro library panel and requires manual placement and masking for each displayed image. 202 | 203 |
- Export All Bitmaps As Sprite Sheets. Available via the Flash Pro publish settings which automatically handles sprite sheet creation for you however currently outputs a single sprite sheet for all asset types. "Appendix: Code & API Differences" has additional information on leveraging this new feature.
Audio
206 | 207 |When used, audio can also contribute significantly to file size. As with images, you should consider compressing your audio using a dedicated tool that will provide better results than Flash Pro. This is particularly true because as of the time of writing, Flash Pro does not compress audio below 128kbps.
208 | 209 |When compressing play, with settings and get a feel for what provides adequate quality for your needs. For example, you might be able to use 48kbps mono for voice or some sound effects, but may not want to drop below 128 kbps for music.
210 | 211 |Code
212 | 213 |Traveling over the wire, your code will be gzipped, which will vastly reduce its file size automatically. However, you can further decrease the file size via minification, and reduce the number of HTTP requests via concatenation.
214 | 215 |Concatenation involves combining multiple source files into a single file. Ideally, all of your source files (HTML, CSS, JS) are combined into a single HTML file prior to deployment.
216 | 217 |Minification is the process of removing all unnecessary characters from the source code, such as whitespace and comments. More aggressive minification will also refactor your code to use shorter variable names and more compact syntax.
218 | 219 |These processes make your code vastly harder to work with, and as such should be used to build a copy of the code for deployment. They are easily integrated into an automated build process using Grunt or Gulp. The functionality of the code should remain intact, but it's important to always test after concatenation and minification.
220 | 221 |Performance
222 | 223 |Building your ads with performance in mind is critical, especially when they will be viewed on mobile devices. Not only do you want your ads to play back smoothly, but you also want to be respectful of users' experience of the site they are visiting, and the battery life of their device.
224 | 225 |There are a number of factors that can have a significant impact on the performance of CreateJS content. It's good to be aware of them, and avoid or use them sparingly.
226 | 227 |- drop shadows and glows can be expensive to render, especially on mobile devices 228 | 229 |
- filters are very performance intensive, and it is recommended to consider alternatives to animating them directly. For example, rather than animate a ColorMatrixFilter to fade a Bitmap from grayscale to color, consider desaturating a copy of the Bitmap by applying the filter once, and fade it over top of the colored version. Similar approaches can be used for blurs and color transforms (which are filters in EaselJS). 230 | 231 |
- complex vector graphics with lots of curves or points (or large numbers of simpler vectors graphics). Consider using bitmap caching to pre-render complex vectors. 232 | 233 |
- large or complex gradients (especially circular gradients). 234 | 235 |
- vector masks are costly in some browsers, consider using
compositeOperationin combination with bitmap caching to attain similar results.
You should always profile your content's performance using browser developer tools prior to deployment. Be sure to consider the relative performance of the device you use to profile versus the devices your users may be using. Testing on actual devices is always ideal when possible.
238 | 239 |Performance monitoring
240 | 241 |Some devices are just slow. It doesn't matter how well you author your ad, it will likely never run well on a 5 year old phone intended for a third-world market. Given that, it's a good idea to monitor the performance of your ad, and fall back to alternate content (ex. an image) if it's performing poorly.
242 | 243 |The EaselJS Ticker can help with this via its getMeasuredFPS() and getMeasuredTickTime() methods. The former returns the actual framerate that the Ticker is running at, and the latter reports the time actually spent executing each tick. For example, if an ad that was authored to play at 20fps reported 19.8fps, that would mean it's playing right around where we'd expect. However, if it was using 48ms each tick on a desktop PC, that would indicate that it was using almost all of the time available per frame (48ms of 50ms), which could lead to problems when running on less powerful devices.
The CreateJS AdHelper class described in "Appendix: AdHelper" provides a configurable method for monitoring performance and showing fallback content or providing actionable events. It also correctly avoids false positives when running in a background tab.
246 | 247 |Duration
248 | 249 |Ads are often required to run for a set amount of time before sleeping (pausing). It's reasonably easy to set a timer to do this in JavaScript, however it's important to consider the elastic nature of frame timing in EaselJS.
250 | 251 |When you set a framerate, this doesn't guarantee that your content will play back at that speed. If the device becomes overburdened, frames may take longer to render, slowing the playback of your content. This can cause problems when your ad fails to reach the expected keyframe in the allotted time.
252 | 253 |EaselJS allows you to set a target framerate on MovieClip and Sprite instances, placing them in a time-synced mode. If the real-world framerate drops, the MovieClip will adjust its playback rate to accommodate it. For example, if you set a target framerate of 20 on a MovieClip, and the real-world framerate drops to 10fps, it will play 2 frames per second to remain synchronized.
256 | myMovieClip.framerate = 20; 257 |258 | 259 |
Note that the timing may still vary slightly, but this is easily resolved by shortening your animation by a small amount. For example, if you have a 15s maximum duration, you may want to author your ad to be 14.8s long to ensure it reaches the last frame before sleeping.
260 | 261 |The CreateJS AdHelper class described in "Appendix: AdHelper" provides tools for scheduling sleep and wake for ads, as well as propagating a target framerate to all MovieClip instances in the display list.
262 | 263 |Summary
264 | 265 |Authoring ads using CreateJS and Flash Pro allows you to leverage your existing skills and workflows to develop rich interactive content built on open web standards, that can play on any device, and adhere fully to the emerging IAB standards.
266 | 267 |There are a number of differences from SWF and AS3 production, and as with any new platform, it will take a bit of adjustment to fully develop your expertise. However, a lot of effort has been put into both CreateJS and Flash Pro's HTML5 Canvas publishing to make it comfortable and familiar to developers coming from a SWF background.
268 | 269 |To get started, check out the demos and documentation on the CreateJS site or download the latest source and examples from the CreateJS GitHub repo. Then, install the latest version of Flash Professional, and check out the AdHelper example.
270 | 271 |272 | 273 |
Appendix: Links
274 | 275 |HTML5 Ads
276 | 277 |- http://www.iab.net/html5 IAB HTML5 specs 278 | 279 |
- http://github.com/createjs/html5ads/ Repository for this document, supporting materials, and helper classes.
CreateJS
282 | 283 |- http://createjs.com/ CreateJS site 284 | 285 |
- http://github.com/createjs/ CreateJS GitHub rep 286 | 287 |
- http://createjs.com/docs/ CreateJS API documentation 288 | 289 |
- http://createjs.com/demos/easeljs/ CreateJS demos
You can access tutorials and examples for each CreateJS library by cloning its GitHub repository (or simply downloading the latest as a zip file), and looking in the /tutorials and /examples directories.
Tools
294 | 295 |- http://www.adobe.com/products/flash.html Flash Professional 296 | 297 |
- http://www.createjs.com/zoe Zoë 298 | 299 |
- https://www.codeandweb.com/texturepacker TexturePacker 300 | 301 |
- https://imageoptim.com ImageOptim 302 | 303 |
- http://pngmini.com ImageAlpha
JavaScript / Web
306 | 307 |- https://developer.mozilla.org/docs/Web/ MDN HTML & JS reference 308 | 309 |
- http://caniuse.com/ Browser feature support reference 310 | 311 |
- https://dev.modern.ie/platform/documentation/f12-devtools-guide/performance/ Performance profiling in MS Edge 312 | 313 |
- https://developer.mozilla.org/en-US/docs/Tools/Performance Performance profiling in Firefox 314 | 315 |
- https://developer.chrome.com/devtools/docs/timeline Performance profiling in Chrome
318 | 319 |
Appendix: AdHelper
320 | 321 |AdHelper is a helper class that makes it easier to build and deploy ads using CreateJS. It serves a number of functions, and is very easy to set up.
322 | 323 |324 | var ad = new createjs.AdHelper(myStage); 325 |326 | 327 |
AdHelper can be found in the CreateJS Sandbox repository on GitHub:
328 | 329 |http://github.com/createjs/sandbox/
330 | 331 |Method Chaining
332 | 333 |Most methods can be chained for simpler setup. For example, the following code creates a new AdHelper instance and enables time sync, performance monitoring, and high dpi support using default settings.
334 | 335 |336 | new createjs.AdHelper(myStage).timeSync().watchFPS().highDPI(); 337 |338 | 339 |
Sleep / Wake
340 | 341 |Puts the ad to sleep according to a configurable schedule, and wakes it for the specified amount of time when the mouse is within the ad, or the user clicks in the ad. When an ad is put to sleep, its Ticker is paused, its tick listener is unsubscribed, any GreenSock tweens are paused, and a sleep event is dispatched to allow custom handling. On wake, this is reversed, and a wake event is generated.
344 | ad.setSleep(start, mousedown, inBounds, useTicks, listener); 345 |346 | 347 |
Ads can also be put to sleep directly via the "sleep" and wake" methods:
348 | 349 |350 | ad.wake(time); 351 | ad.sleep(delay); 352 |353 | 354 |
Visibility
355 | 356 |Detects when the ad is not visible (ex. in a background browser tab), and sleeps the ad and mutes all sound. Resumes / unmutes the ad when it is visible. The "hidden" property is set accordingly and the sleep and wake events are dispatched as normal.
This feature is enabled automatically when using AdHelper.
359 | 360 |CreateJS Support
361 | 362 |Test to see if CreateJS is supported on the current browser. For example, this can be used to display alternative content.
363 | 364 |
365 | if (!createjs.AdHelper.isSupported()) {
366 | createjs.AdHelper.showAltImage(myCanvas, "myImage.jpg", "url");
367 | }
368 |
369 |
370 | Alternative Content
371 | 372 |Static methods to replace your ad canvas with alternative content. This can be useful when CreateJS is not supported, or if performance monitoring determines the ad is running too slowly. There are three methods, that give different levels of control.
373 | 374 |375 | createjs.AdHelper.showAltImage(canvas, imgSrc, href, alt, target); 376 | createjs.AdHelper.showAltHTML(canvas, html); 377 | createjs.AdHelper.showAlt(canvas, element); 378 |379 | 380 |
Time Sync
381 | 382 |Force all MovieClips in the ad to operate in time-synced mode (ie. by setting framerate on all MovieClip instances). This allows the ad to play back with a predictable duration even if the real framerate fluctuates.
385 | ad.timeSync(framerate); 386 |387 | 388 |
High DPI Support
389 | 390 |Enable full resolution rendering on high DPI screens. Can also be used to disable full resolution rendering on high DPI screens to improve performance. Also allows for authoring the ad at a different scale.
391 | 392 |393 | ad.highDPI(enabled, nominalScale); 394 |395 | 396 |
Performance Monitoring
397 | 398 |Monitors playback framerate, and uses a simple heuristic to determine when the ad fails to satisfy configurable performance minimums. Dispatches a slow event and sleeps the ad by default. Works with visibility features to avoid failing while in a background tab due to throttling.
401 | ad.watchFPS(minFPS, tolerance); 402 |403 | 404 |
405 | 406 |
Appendix: Designer / Developer Workflow
407 | 408 |As with traditional SWF development, there are many valid workflows for developing HTML5 Canvas content using Flash Pro.
409 | 410 |For simpler projects owned by a single designer, building everything on the timeline, including simple frame scripts is often perfectly acceptable.
411 | 412 |As projects grow in complexity, it is generally wise to create a separation between the creation of visual assets (presentation), and the code that drives functionality (logic). In many cases these areas are divided between a designer(s) and developer(s) respectively. Even when a single creator is producing the full project there are usually significant benefits to productivity, quality control, reuse, and robustness that can be realized by separating presentation and logic.
413 | 414 |One common approach to this separation when building CreateJS content is to have the FLA owned entirely by the designer, who passes the published JS library to the developer (via email, version control, etc), who consumes it into a larger project with additional HTML and JS files. It winds up looking something like this:
415 | 416 |
417 |
418 | Using this approach, the developer should almost never need to touch the published JS. They can simply treat it as an asset library, instantiating elements from it using new. For example, if the FLA has a symbol named (or with the linkage) "FunnyCat", a developer could add an instance to the stage, position it, and play its "run" animation using:
421 | var myCat = new lib.FunnyCat();
422 | stage.addChild(myCat);
423 | myCat.x = 100;
424 | myCat.gotoAndPlay("run");
425 |
426 |
427 | The JS file also includes a properties object that includes information on the original FLA (dimensions, background color, framerate), and a manifest of external media assets that can be passed directly to a PreloadJS LoadQueue.
430 | var props = lib.properties;
431 | createjs.Ticker.setFPS(props.fps);
432 | var queue = new createjs.LoadQueue();
433 | queue.on("complete", handleComplete, this);
434 | queue.loadManifest(props.manifest);
435 |
436 |
437 | It's often critical for a project's business logic to know when an animation finishes or reaches a particular point. For example, you may want to change the position of the cat in the example above each time it finishes the "run" animation. This is easily achieved. In addition to the presentation code to loop the animation, the designer could also add an event trigger at the end of the animation:
438 | 439 |
440 | // timeline code on the last frame of the run animation:
441 | this.gotoAndPlay("run"); // loop
442 | this.dispatchEvent("runend"); // the name can be anything
443 |
444 |
445 | Once this is in place, the developer can easily subscribe and react to this event:
446 | 447 |
448 | myCat.on("runend", function(evt) {
449 | // with on() "this" defaults to the dispatcher.
450 | this.x += 100;
451 | });
452 |
453 |
454 | This supports a loosely coupled interaction between the timeline and the business logic. The designer only needs to worry about a single simple command to communicate events, and can move the event freely as the animation is revised. The developer can subscribe to events as needed. Events dispatched without subscribers do not generate errors, and have very low cost (no event object is created).
455 | 456 |457 | 458 |
Appendix: Code & API Differences
459 | 460 |The following are common tasks that you are likely to encounter when building HTML5 ads with Flash Pro.
461 | 462 |Text
463 | 464 |Flash Pro currently only supports the usage of dynamic text fields with a single style which can be very limiting when it comes to controlling the appearance and presentation of type. When Flash Pro converts existing static text fields to dynamic text fields the text is converted to a single style and overrides any specific styling that was previously applied, such as leading, weight, etc., and also visually removes line-wrapping even though the hidden text actually exists and will properly wrap to a new line when published.
465 | 466 |Most advertisers have very specific requirements when it comes to font styling and branding, so these limitations can be challenging and make the design process unnecessarily cumbersome when working within the Flash Pro Canvas project environment. In order to maintain the visual integrity of your styled text you may want to take one of the following approaches:
467 | 468 |- Start your banner ad project as a Flash ActionScript 3 document type (not an HTML5 Canvas FLA) and then break apart all static text before converting the file over to HTML5 Canvas. This will convert all text into vector shapes, maintaining both appearance and scalability. 469 | 470 |
- Maintain a separate AS3 FLA for the styling of all text and then paste the text into your working HTML5 Canvas document after it has been converted to vector outlines. 471 | 472 |
- Design all of your text in Photoshop or Flash Pro and then integrate the text as bitmaps. This approach is not recommended as it removes the benefits of vector based text which would be small file size and scalability.
Regardless of which approach you prefer it is suggested that you adhere to the following best practices when working with vector text inside of Flash Pro CC:
475 | 476 |477 | 478 |
- Create a movieclip of your broken apart text and set it to cache as bitmap. This will improve performance as the vector drawing calculations won't have to be repeatedly processed on every stage tick. 479 | 480 |
- Be sure to maintain an editable version of your text by creating a "guided out" backup layer containing a static text field. This ensures that edits can be easily made in the future.
483 | 484 |
Filters and Color Effects
485 | 486 |Flash Pro CC supports most filters and color effects. These effects fall into one of two categories: shadow effects, and filter effects. All effects are expensive to render, particularly on mobile devices, and should be tested thoroughly.
487 | 488 |Shadow Effects
489 | 490 |Drop shadows and glows (which are essentially shadows with no offset) are rendered in EaselJS using canvas's built in shadow features. They render reasonably fast on desktop, but can cause performance issues on mobile, and can be applied to animated content.
491 | 492 |At this time, shadow effects cannot be animated on the timeline, though this is primarily an authoring limitation that may be removed in the future.
493 | 494 |Filter Effects
495 | 496 |Blurs, color transforms (excluding alpha), and color adjustments are treated as filters in EaselJS. These effects work by manipulating pixel data, can be quite expensive to render, and require bitmap caching to be enabled to work (this is done automatically when you apply these filters in Flash Pro).
497 | 498 |This bitmap caching "freezes" the movieclip on its first frame, which stops it from animating. Similarly, the filter cannot be animated on the timeline. This is an intentional limitation, because updating filters is very expensive, and it would be very easy to unintentionally create content with very poor performance.
499 | 500 |It is possible to animate content with a filter by re-rendering the filter each tick (or frame) via myDisplayObject.updateCache(), but in almost all cases it is better to consider alternative approaches. For example, to transition an image from grayscale to color, you could simply duplicate the image, apply a grayscale color adjustment to the top copy, and fade down its alpha over the color copy. Similar approaches can be used for blur and color transforms.
Another option is to create a sprite sheet animation of the filter effect and use that in your ad instead.
503 | 504 |Logging
505 | 506 |It's likely that you've previously used ActionScript's trace()statement to debug your code. In JavaScript, you can use console.log() instead:
509 | 510 |
511 | console.log("This is the same as a trace statement." );
512 |
513 |
514 | To view console.log()statements when previewing your HTML file, you will need to open up the JavaScript Console in Chrome Dev Tools, or the Console tab in Firebug if you are testing using Firefox. Be aware that in IE9 the console must be open to function correctly or it will generate errors. Make sure you remove any console.log() calls prior to deployment.
517 | 518 |
Scope
519 | 520 |JavaScript does not use this as an implicit scope as is the case with ActionScript 3. You must explicitly specify scope in timeline scripts. For example:
523 | 524 |
525 | // "this" in a timeline script refers to the MovieClip or stage that it's defined in.
526 | this.stop();
527 | // access a child MovieClip instance:
528 | this.myChildMC.gotoAndPlay("end");
529 |
530 |
531 | 532 | 533 |
Defining Global Variables and Functions
534 | 535 |Variables are defined with the scope of their frame code, so if you define a variable in the first frame, you will not be able to access that variable in the final frame. For example:
536 | 537 |538 | // first frame 539 | var foo = 20; 540 | // second frame 541 | console.log(foo); // undefined 542 |543 | 544 |
Scope your variables using this to make them accessible across all frames. Please note that variables are not strictly typed in JavaScript as they were previously in AS3.
545 |
548 | // first frame 549 | this.foo = 20; 550 | // second frame 551 | console.log(this.foo); // 20 552 |553 | 554 |
The same approach should be taken for defining any functions on your timeline that will need to be called later in the animation or by a parent MovieClip:
555 | 556 |
557 | this.startOver = function(){
558 | this.score = 0;
559 | this.gotoAndPlay("start");
560 | };
561 |
562 |
563 | Stage, Root, and exportRoot
564 | 565 |When published from Flash Pro, the main timeline of the FLA is exported as a MovieClip and assigned a global reference named exportRoot, which can be used to access it from nested MovieClips. By default exportRoot is the only child of the EaselJS Stage.
EaselJS also exposes a stage property on all DisplayObject instances, which points to the Stage that contains the instance. As such, by default you can access your FLA's root timeline from a nested MovieClip using this.stage.getChildAt(0).
You can also append global variables to the window object to make them accessible anywhere. This is generally frowned on in JS for the same reasons as using global or root in AS3 (scalability and polluting the global space), but should be fine for most ad development scenarios.
572 | // on the root timeline: 573 | window.root = this; // create a global reference 574 | // in another MovieClip's frame action: 575 | root.doSomething(); // can use the global variable without a scope 576 |577 | 578 |
Events
579 | 580 |The event model in CreateJS is similar to AS3's but has a few variations you should be aware of. Firstly, there are no onevent handlers. For example you can't use:
583 | myBtn.onClick = function(){...};
584 |
585 |
586 | Instead you can use addEventListener() or on(). The former is very similar to addEventListener() in AS3, and nearly identical to its namesake in JS.
589 | // named function:
590 | myBtn.addEventListener("click", handleClick);
591 | // anonymous function:
592 | myBtn.addEventListener("click", function() { … });
593 |
594 |
595 | As in vanilla JS, these callbacks are not scoped, so in the examples above, "this" will not point to the local scope. You must either use bind() or create a scope in the activation object.
598 | // bind:
599 | myBtn.addEventListener("click", handleClick.bind(this));
600 | // activation object:
601 | var _this = this;
602 | myBtn.addEventListener("click", function() { _this.doStuff(); });
603 |
604 |
605 | The on() method provides an easy way to scope your methods (and offers some other handy features). By default, on() sets the scope to the dispatching object, but you can include a third parameter to specify your own scope.
608 | // will execute in myBtn:
609 | myBtn.on("click", function() {...});
610 | // will execute in the local scope:
611 | myBtn.on("click", function() {...}), this);
612 | // also works with named functions:
613 | myBtn.on("click", handleClick, this);
614 |
615 |
616 | It's important to note that this scoping works by wrapping your handler in an anonymous function and subscribing it as the listener. This listener is returned by on() and must be used if you want to remove the listener later. There is also an off() method which is just a shortcut to removeEventListener().
619 | var listener = myBtn.on("click", handleClick);
620 | // this won't work:
621 | myBtn.off("click", handleClick);
622 | // because the actual listener, is the one returned by on():
623 | myBtn.off("click", listener);
624 |
625 |
626 | The on() method also provides the ability to create single use event listeners, and to pass data to the listener.
629 | // this event listener will automatically unsubscribe after it runs:
630 | myBtn.on("click", handleClick, this, true, "some data");
631 | function handleClick(evt, data) {
632 | console.log(data); // "some data"
633 | }
634 |
635 |
636 | Mouse Interactions
637 | 638 |EaselJS display objects dispatch most of the mouse events you would expect coming from AS3, including click, dblclick, and mousedown. To save costs when they are unneeded, you must explicitly enable mouseover, mouseout, rollover, and rollout events, via:
641 | myStage.enableMouseOver() 642 |643 | 644 |
This also enables support for the cursor property, and is included automatically in the HTML generated by Flash Pro if a button is included.
Similarly, untargeted mouse events such as mousemove and mouseup are not dispatched to every display object on stage to reduce unnecessary overhead. Instead, you can subscribe to stage level events stagemousemove and stagemouseup. The following shows a simple mouse follow behavior:
647 |
650 | this.stage.on("stagemousemove", moveTarget, this);
651 | function moveTarget(evt){
652 | var t = this.myTarget;
653 | t.x = evt.stageX;
654 | t.y = evt.stageY;
655 | };
656 |
657 |
658 | EaselJS also dispatches two events that make implementing drag interactions really simple. The pressmove event fires whenever the mouse moves after a press occurs on the target object. The pressup event is fired when the mouse is released after a press on the target, even if the mouse is no longer over the target (and in most browsers, even if it's outside the window). A drag interaction looks like this:
661 | this.foo.on("pressmove", function(evt) {
662 | this.foo.x = evt.localX;
663 | this.foo.y = evt.localY;
664 | }, this);
665 | this.foo.on("pressup", function(evt) {
666 | console.log("final position:", this.foo.x, this.foo.y);
667 | }, this);
668 |
669 |
670 | When targeting touch-based devices, you should generally enable touch interactions. EaselJS will listen for touch events from both the touch and pointer JS APIs, and translate them into mouse events. This has no effect on devices without touch.
673 | createjs.Touch.enable(myStage); 674 |675 | 676 |
Cursor
677 | 678 |It is an ad-creation best practice to display a pointer icon anytime the user has moused over a clickable design element. This functionality is enabled by default on Button symbols (or when using ButtonHelper), but must be manually enabled on other clickable elements as follows:
681 | this.childMC.cursor = "pointer"; 682 | 683 | // and mouseover must be enabled for your stage (just once): 684 | myStage.enableMouseOver(); 685 |686 | 687 |
DisplayObject Properties
688 | 689 |Published movieclip symbols expose methods to control their timelines and properties to adjust their settings, similarly to AS3. Here are some common examples:
690 | 691 |--- code
692 | mc.gotoAndPlay("yourFrameLabelName");
693 | mc.gotoAndStop(10);
694 | mc.stop();
695 | mc.play();
696 | mc.scaleX = 1;
697 | mc.scaleY = .5;
698 | mc.x = 0;
699 | mc.y = 150;
700 | mc.alpha = .75;
701 | mc.visible = false;
Programmatic Animations
704 | 705 |You can use tweening engines such as TweenJS, or GSAP TweenLite to create new animations (TweenJS powers the timeline animations published from Flash Pro), but it's also easy to write custom animation using the tick event, which is analogous to enterframe in AS3, and dispatched from all display objects within the display list each time the stage is updated, immediately before it redraws.
708 | this.on("tick", function() {
709 | this.x ++; // move right each tick
710 | });
711 |
712 |
713 | You can also subscribe to the global tick event dispatched from Ticker.
714 | 715 |
716 | createjs.Ticker.on("tick", function() {
717 | console.log("tick!");
718 | });
719 |
720 |
721 | The stage must have update() called each tick in order to propagate the tick event to child display objects and to redraw. By default, Flash Pro subscribes the stage as a listener to Ticker's tick event, which covers this requirement, but you may want to remove this and call your own tick handler in order to run logic before the update. It's very important to call stage.update() and pass the tick event object to it (this is needed for time syncing in EaselJS).
724 | createjs.Ticker.on("tick", handleTick);
725 | function handleTick(evt) {
726 | // do stuff
727 | myStage.update(evt);
728 | }
729 |
730 |
731 | Setting the frequency of these events can be done as follows, which effectively sets the framerate of your ad. 732 |
733 | 734 |735 | //the following are equivalent, 1000ms / 40fps = 25ms 736 | createjs.Ticker.interval = 25; 737 | createjs.Ticker.framerate = 40; 738 |739 | 740 |
Frame Numbers & Labels
741 | 742 |EaselJS uses zero-based frame numbering rather than Flash's (unusual) one-based indexing. This can cause confusion as it (currently) requires you to subtract 1 from the indexes displayed in Flash Pro.
743 | 744 |To avoid this confusion, it is suggested that you label your animation frames with frame labels, and reference those in your code rather than numbers.
745 | 746 |
747 | this.childMC.gotoAndPlay(0); // first frame, may be confusing
748 | this.childMC.gotoAndPlay("start"); // less ambiguous, and easier to update
749 |
750 |
751 | 752 | 753 |
Links
754 | 755 |Successfully navigating to a clickthrough URL can be achieved in a number of ways, however the following method is the closest to what was previously done in ActionScript and should function properly in all browser scenarios:
756 | 757 |
758 | this.myBtn.on("click", function(evt){
759 | window.open("URL", "_blank");
760 | });
761 |
762 |
763 | Note that you need to be careful where this code is placed. If it is on a frame in a looping MovieClip, it will be called repeatedly, and set up multiple listeners for the click. Ensure it only runs once, either by placing the code on a frame that won't loop, or by setting an initialization variable.
764 | 765 |
766 | if (!this.inited) {
767 | this.myBtn.on("click", ... );
768 | this.inited = true;
769 | }
770 |
771 |
772 | Flash Pro Publish Settings
773 | 774 |There are several Publish Settings available within Flash Pro that are very important to understand and configure properly.
775 | 776 |Overwrite Images
777 | 778 |Under the "Asset Export Options" publish setting in Flash Pro CC, you can uncheck "Images", so that Flash Pro will no longer replace your images with each republish. This allows you to replace images with optimized versions. Just remember that if you add new images to the FLA, they will not be exported until you re-enable this option.
779 | 780 |Overwrite HTML
781 | 782 |Under the "Output File" options you can uncheck this setting, and the contents of the HTML file will not be overwritten on subsequent publishes. This can be useful since you'll need to customize the HTML file for tracking implementation, meta tags, CSS, backup image logic, linking to externally referenced JavaScript helper files and libraries, etc.
783 | 784 |Alternatively, you can duplicate the HTML file and modify the copy. You can then inject a line of code into the first frame of your main timeline to load the copy automatically. This is ideal when working with a developer, since it allows the developer to provide a deploy HTML file to test with. Ensure you remove the redirect for deployment.
785 | 786 |
787 | // redirect to deploy.html if we aren't already there:
788 | if (window.location.pathname.indexOf("deploy.html") == -1) {
789 | window.location = "./deploy.html";
790 | }
791 |
792 |
793 | Export All Bitmaps As Sprite Sheets
794 | 795 |By checking this setting under "Asset Export Options/Images" Flash Pro CC will automatically combine all of the utilized images within your Flash library into a single, PNG32 sprite sheet along with a JSON file defining all of the coordinates of the separate image regions that comprise the sprite sheet.
796 | 797 |This is a significant time-saver, versus the manual process previously required. It is important to test and evaluate the outputted sprite sheet when using this new and evolving feature. Because Flash is outputting the sprite sheet to a single PNG32 sprite sheet, server requests are successfully reduced, however the overall file size is increased when compared to leveraging separate sprite sheets for PNG32 and JPEG image assets. Because of this, you should definitely compress the sprite sheet with ImageOptim or a comparable image optimization tool in order to maximize the file size compression.
798 | 799 |800 | 801 |
Appendix: Document History
802 | 803 |October 5, 2015
804 | 805 |Initial release.
806 | 807 |October 26, 2015
808 | 809 |Minor edits, and changes to reflect AdHelper updates.
810 | 811 | 812 | 813 | 814 | 815 | 816 | 817 | 818 | 819 | 820 | 821 |