Follow

Overview

Build a Sizmek-compliant Expandable Banners with Animate CC. This workflow guide will help you build your project and understand basic techniques for developing desktop / mobile(MRAID) compliant ads.

Build two separate projects and proceed to next the published expandPanel folder under your published mainPanel folder to form a workspace. For this task, you can download the following example files:

The following example displays the main panel and expand panel as two separate Animate CC Projects.

2-pub.png

The following displays the Published folder nesting structure.
published.png

Workflow for Building the Sizmek-Compatible Animate CC Ad

Workflow Guidelines

  • Pick a name to use to reference your panels. It needs to be consistent across both project code and platform ad setup.
  • There is a five step process for each of the panels and an additional three steps when preparing for upload. 
  • The steps are not identical for the main panel and expand panels. 

Build the Main Panel

  1. Create a Main Panel Animate CC project.
  2. Load adkit.js as a Global Include.
  3. Load EBCMD module EBModulesToLoad = ['EBCMD'];and other modules if needed.
  4. Pause the movie clip, hide the button place adkit.onReady(function) and deploy Set EB.expand() method in function definition.
  5. Set clickthrough, user action counters, automatic event counters and video tracking.

Build the Expand Panels

  1. Create a Separate Expand Panel Animate CC project.
  2. Load adkit.js as a Global Include.
  3. Load EBCMD and EBAPI module EBModulesToLoad = ['EBAPI','EBCMD']; and other modules if needed.
  4. Pause the movie clip, hide the button place adkit.onReady(function) and deploy Set EB.collapse() method and SDK close button code in function definition.
  5. Set clickthrough, user action counters, automatic event counters and video tracking.

Generate the Ad

  1. Publish mainPanel and expandPanel.
  2. Copy default image and config.js files
  3. Nest the expandPanel published folder under mainPanel. 

Preview the Ad Locally 

There is no way of testing expandable functionality locally(outside of the platform), however panels - separate Animate CC projects can be previewed directly from Animate CC (ctrl+enter).
When testing locally please ignore this error (will not show once the ad gets prepared for upload - config.js is copied to both mainPanel and expandPanel publish folders):
3_config_js_error.png

Animate CC: Scopes, Symbols, Instances, and Tick Events 

The way createjs API works with the canvas in Animate CC is that it uses instances of symbols (MovieClips, Graphis, Buttons) on stage and allows you to change their properties over time.

  • Scopes: If we want to manipulate a MovieClip on the stage by use of createjs we would want to give it an instance name and then access it by typing this.instanceName on its parent scope(symbol instance). For example, if we want to access mainFrame instance of Symbol 1 MovieClip on top level stage from top level stage, we can simply write: this.mainFrame or we can reference it from the top level stage notation with stage.children[0].mainFrame allowing us more clarity over symbol instance inheritance.

  • Stage: Main top level scope of where the code of your canvas output is executed. Can be accessed by calling this on the top level of the project or by referencing it directly stage.children[0]:

  • Createjs: API used by Animate CC.

  • Symbol: A symbol is a graphic, button, or movie clip that you create in Animate CC. You can then reuse the symbol throughout your project or in other documents - behaving as JS classes.

  • Symbol Instance: An instance is a copy of a symbol located on the Stage or nested inside another symbol. An instance can be different from its parent symbol in color, size, and function. Editing the symbol updates all of its instances, but applying effects to an instance of a symbol updates only that instance. For more information, see Symbols and Symbol Instances.

  • Tick: In Animate CC each time a play head progresses over the frame in a movie clip or stage, it generates its own heart beat like event - "tick". If we wanted to track tick event of the current movie clip symbol instance we could attach an event listener to statement this - being our current scope. For example,
    this.addEventListener("tick", function(e){console.log(e);});
    However, if we are listening for an event in a child movie clip instance we can reference it from the top level scope:
    stage.children[0].path.to.instance.addEventListener("tick", function(e){console.log(e);});

1. Building the Main Panel

This will be the base of your main panel. Please make sure to follow the project architecture as described in step 1. All of the code in steps 4 and 5 needs to be executed within a function invoked by adkit.onReady() method. For example, adkit.onReady(function name);

  1. Create a Main Panel Animate CC project.
      1. Create a new HTML5 Canvas document in Animate CC.
      2. Make sure that you build your ads contents within a single movie clip  instance nested under a single frame layer. Also, make sure to define an empty actions layer.
        setup.png
        Examplary contents / animation of mainMc instance:
        setup-cont.png
      3. Stop the nested movie clip instance and hide the close button on first frame of the stage.
        tlcode.png
        stage.children[0].mainMc.stop();
        
      4. Right after code from previuous step, use adkit.onReady() method and populate it with a function name then write the function definition:
        adkit.onReady(startAd);
        function startAd(){

        stage.children[0].mainMc.play(); }
        Inside this startAd function is where all your code from steps 4 and 5 will run. Do not place code from steps 2 and 3 here.
  2. Load adkit.js - https://secure-ds.serving-sys.com/BurstingScript/adKit/adkit.js as a Global Include.
    4-global-include.png
  3. Load EBCMD module(mandatory for expandable banners - panels) and other modules if needed. You can also declare any global vars here. In this example we are loading EBCMD and Video modules, and declaring a loopCount global var to use for loop control:
    EBModulesToLoad = ['EBCMD','Video'];
    var loopCount = 0;
    
    5-global-modules.pngFor a full list of modules and explanation on what they do, see Overview: Sizmek AdKit HTML5 API.

  4. Add an on click event listener to your expand button symbol instance and invoke EB.expand() in your event handler with panel name and position / size settings passed in as an object.
    stage.children[0].path.to.instance.addEventListener("click", mainExpand);
      function mainExpand(){
    	EB.expand({panelName:'expandPanel'});
      }
    
    6-zero.png

  5. Set clickthrough, user action counters, automatic event counters and video tracking.
    stage.children[0].path.to.instance.addEventListener("click", mainClick);
      function mainClick(){
        EB.clickthrough();
    }
    

    The following example displays the Clickthrough on mainMc.clickthroughButtonMain.

    7-click.png

2. Building the Expand Panel

This project will be the base of your expand panel. Please make sure to follow the project architecture as described in step 1. All of the code in steps 4 and 5 needs to be executed within a function invoked by adkit.onReady() method - E.g. adkit.onReady(function name);

  1. Create the Expand Panel Animate CC project.
    • Create new HTML5 Canvas document in Animate CC.
    • Make sure that you build your ads contents within a single movie clip  instance nested under a single frame layer. Also, make sure to define an empty actions layer.
      setup.png
      This is an example fo the contents/animation of mainMc instance.
      setup-cont.png
    • Stop the nested movie clip instance and hide the close button on first frame of the stage.
      tlcode.png
      stage.children[0].mainMc.stop();
      stage.children[0].mainMc.closeButton.visible = false;
      
    • Use the adkit.onReady() method and populate it with a function name then write a function definition for it right after the code from previous step.
      adkit.onReady(startAd);
      function startAd(){

      stage.children[0].mainMc.play(); }
      Inside this startAd function is where all your code from steps 4 and 5 will run. Do not place code from steps 2 and 3 here.

  2. Load adkit.js - https://secure-ds.serving-sys.com/BurstingScript/adKit/adkit.js as a Global Include.
    8-expanel-ginclude.png
  3. Load EBCMD and EBAPI modules(mandatory for panels of expandable banners), and any other modules if needed(). We also need to set initial expansion parameters so that the ad knows where to expand the panel and which dimensions it should have.
    EBModulesToLoad = ['EBAPI','EBCMD'];
    try{EB.initExpansionParams(0, 0, 320, 430);}catch(e){};
    9-expanel-gscripts.png
  4. Set EB.collapse() method and SDK close button code.
    stage.children[0].closeButton.addEventListener("click", panelCollapse);
      function panelCollapse(){
        EB.collapse({panelName:'expandPanel'});
      }
    10-expanel-clps.png

    Before waiting for adKit to be ready or any other action on the stage we need to hide the close button so that it can be shown or kept hidden based on sdk data

    //hide collapse button (set it's default state) so that it can be shown or hidden based on SDK setup.
    stage.children[0].closeButton.visible = false;
    

    Initialize close button function definition and invocation, you dont need to think too much about this one, just make sure it's within the function triggered by adkit.onReady(function) and chage references(property notations) on two places:

    //initializeCloseButton function definition - shows or hides closeButton based on mraid sdk closebutton settings
    function initializeCloseButton(){
    	var sdkData = EB.getSDKData();
    	var enableSDKDefaultCloseButton = EB._adConfig && EB._adConfig.hasOwnProperty("mdEnableSDKDefaultCloseButton") && EB._adConfig.mdEnableSDKDefaultCloseButton;
    	if (sdkData !== null && sdkData !== undefined)
    	{
    		if (sdkData.SDKType === "MRAID" && !enableSDKDefaultCloseButton)
    		{
    			//change reference to close button here to fit your purpose
    			stage.children[0].closeButton.visible = true;
    		}
    	}
    	else
    	{
    		//change reference to close button here to fit your purpose
    		stage.children[0].closeButton.visible = true;
    	}
    }
    //initializeCloseButton function invocation - basically showing the button when tested on desktop if everything is wired up correctly
    initializeCloseButton();	
    
    11-sdkButton.png

  5. Set clickthrough, user action counters, automatic event counters and video tracking.
    //clickthrough - adjust notation after stage.children[0] - top level scope, to fit your build  
    stage.children[0].path.to.instance.addEventListener("click", panelClick);
    function panelClick(){
    	console.log('clickthrough');
    	EB.clickthrough();
    	}
    //user action counter - adjust notation after stage.children[0] - top level scope, to fit your build  
    stage.children[0].path.to.instance.addEventListener("click", panelUserActionCounter);
      function panelUserActionCounter(){
    	console.log('userActionCounter');
    	EB.userActionCounter('UserActionCounterName');
      }
    //video tracking - just copy paste
    createjs.Ticker.addEventListener("tick", tickCheck, false);
    function tickCheck(e){
      createjs.Ticker.removeEventListener("tick", tickCheck);
    $("video").each(function(){new EBG.VideoModule($(this).get(0));});
    }
    //lastly get the mainInstance to play since we stopped it to wait for adkit to be ready and event listeners attached. stage.children[0].mainMc.play();
    12-expanel_clickthrough.png

3. Publishing and Packaging the Ad

  1. Publish both of your panels in separate folders, please make sure that hosted libraries are not ticked on advanced publish settings panel.
    13-publish-settings.png
    Prior to publishing in Animate CC.
    14-pub-1.png
  2. Copy the config.js to both panels publish folders root folder.

    Download empty config.js here.

    15-pub-2.png
  3. Create and / or copy the default image to the root of the main panel publish folder.
    16-pub-3.png
  4. Copy the entire expand panel publish folder and paste it in the main panel publish folder.
    17-pub-4.png
  5. Zip up the mainPanels root folder contents and upload it to the platform.
    mainPublishFolder.png

Serving the Ad in the Platform

Procedure
  1. Create a new master ad.
  2. Assign the uploaded workspace and default image.
  3. Set the expand panel's html file as the.
  4. Assign panel names.
  5. Set panel properties.
  6. Preview / test interaction tracking. 

Appendix: Optimize Your Ad's Weight and Avoid CORS / SSL Compliance Limitations

Sizmek encourages the use of shared libraries, as advised by the IAB creative guidelines. This allows us to reduce the total weight of the ad’s Workspace on the platform (shared libraries not accounted for), and prevent any potential Cross Origin Resource Sharing (CORS) requests being made to https://code.createjs.com/createjs-2015.11.26.min.js or any other web location which might not be safe-listed by the publisher, or is simply not secure enough - low encryption.

For a full list of hosted libraries that are available, see REFERENCE: HTML5 Shared Libraries.

Glossary

  • Adkit: Sizmek's client API. Adkit and EBLoader are two of our API's. Adkit is mostly used for recently released formats and Dynamic Creative, while EBLoader is still used in most of our base formats. Both of these allow you to access EB. namespace while adkit allows you to use adkit. notation as well.

  • Sizmek HTML5 Expandable banner format: This is the format we will be aligning our Animate cc build with. for more info on how the HTML version works please see this page: Sizmek HTML5 Expandable Banner.

  • Panels: Sizmek Expandable formats refer to panels as separate HTML documents within a single workspace that form the actual Ad unit when setup on the platform. Panel names should be defined within the code of the main panel and expand panel projects when setting the target of the expand:
    EB.expand({panelName:'actualName'})
    or collapse method in the object property panelName of the we pass as the argument:
    EB.collapse({panelName:'actualName'})
    those objects are usually refereed to as expand properties - full list of available object properties here.

  • EBModules: Optional API ad delivery dependencies - easily manage additional API modules required to facilitate certain format functionality or sets of functionalities, like Video Tracking, Smart Versioning, MRAID Adapter or EBAPI.

  • MRAID: Mobile Rich Media Ad Interface Definitions  in order to be compliant with it we need to load the EBCMD module that enables the MRAID SDK functionality.

  • Expansion Properties: Method that allows you to set the base position and dimensions of the expanded panel.
    try{EB.initExpansionParams(x, y, width, height);}catch(e){}
    You do not need to set this up for your main - non expanded panel, as it's dimensions always reflect the dimensions of the default image, and position on the publishers page is determined by the slot where our tags have ran, however can be set for the expand panel relative to the mainPanel - x, y part of the method.

    Name

    Type

    Description

    x

    Number

    Defines the left offset (x-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.

    y

    Number

    Defines the top offset (y-coordinate) of the collapsed-state rectangle relative to the expanded-state rectangle.

    width

    Number

    The width of the expanded-state rectangle.

    height

    Number

    The height of the expanded-state rectangle.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments