Skip to main content

Liftoff Accelerate Creative Integration and API

v2​

Liftoff can serve creatives produced by outside developers. This document provides the technical details developers must know to make creatives that can be integrated into Liftoff's system.

Quick Navigation​

Release Notes​

This is version 2 of Liftoff's guidelines for creative integration. Creatives built to conform to version 1 can still be integrated.

Getting started​

Folder Structure​

Liftoff must receive creatives as a zip file containing a single folder of all assets the creative needs to function properly. This includes but is not limited to all image, video, sound, HTML, Javascript, CSS, and font files. Liftoff will host these files on our content-delivery network (CDN). A creative's file structure could look like this:

Folder Structure

Our system needs to be able to detect the entry point for the creative. An entry point can be indicated via:

  • A single HTML file in the root of the creative's folder.
  • In the case of multiple HTML files in the root of the folder, the entry point must be called index.html.
  • Users can upload a single HTML file directly (without a zip file).
  • Files within a zip folder should not contain names with non-ASCII characters.

Loading Assets​

Assets should be loaded using relative URLs. The case of all asset filenames should match the case of their URLs in the creative code. Creatives will be hosted using servers that resolve locations in a case-sensitive manner.

Progressive Loading​

Do not preload every asset up front. Only load what's needed to show the first screen or respond to the first user interaction. Defer secondary assets (e.g., background music, end screens) until they are actually required.

Sound Triggering​

Sound should only be triggered in response to an initial user interaction (e.g., tap, click). Do not start any audio automatically on page load. This ensures compatibility with autoplay restrictions on mobile devices and avoids rejected creatives.

Respecting CORS for Web Workers​

Some assets like js files passed to new Worker() may fail to load if the CDN does not provide CORS headers. The following strategy avoids these issues:

  1. First attempt to fetch the asset using a HEAD request to test CORS access. If it fails or is blocked, fallback to creating a Blob from the local data:

    function fallbackToBlob() {
      const blob = new Blob([App.Assets["FSolver.js"].data], {
        type: "application/javascript",
      });
      const worker = new Worker(URL.createObjectURL(blob));
    }

    fetch(asset.url, { method: "HEAD" })
      .then((res) => (res.ok ? useDirectUrl() : fallbackToBlob()))
      .catch(() => fallbackToBlob());

  2. Using a Blob URL avoids CORS issues entirely by creating a local script object, circumventing the need for Access-Control-Allow-Origin headers on JS files.

  3. Our CDN does not expose Access-Control-Allow-Origin headers for js files due to the security risk of cross-origin script execution.

  4. Note that the blob technique does not allow importing external scripts from other origins.

Handling MRAID Load Sequence​

Some ad exchanges do not fire viewableChange events if the ad is already viewable on load, causing creatives to hang.

  1. Always check mraid.viewable immediately after mraid.ready and start the creative if true:

    mraid.addEventListener("ready", function () {
      if (mraid.viewable) {
        App.startGame();
      } else {
        let didStart = false;
        mraid.addEventListener("viewableChange", function (isViewable) {
          if (isViewable && !didStart) {
            didStart = true;
            App.startGame();
          }
        });
      }
    });

  2. Log all MRAID lifecycle events (ready, viewableChange, etc.) for easier debugging.

  3. Avoid double-registration of viewableChange by managing or cleaning up listeners carefully.

  4. Design for graceful degradation — never let the creative hang due to a missing MRAID event.

Handling Clicks​

In order to take a user to the clickthrough destination (e.g. app store, app, or external web site), open the destination URL using mraid.open (preferred) or window.open. Do not use window.location. The user may only be taken to an external destination following an interaction with the creative.

Requirements​

Filenames​

Restrict filenames to use ASCII characters. Do not use UTF-8 encoded filenames. Filenames are also case-sensitive so make sure the file names match in the code and the creative's file directory.

IFrames​

Do not use any iframe elements.

Sizing and layout​

Each impression is assigned a standard size based on the information given to us by exchanges. Every impression is matched with the closest standard size, which is not guaranteed to equal the actual rendered size. For instance, an impression on a device with a 375 px x 812 px screen will map to the standard 320 px x 480 px size. Currently, Liftoff supports the following standard sizes (width x height in pixels):

  • 320x480 (full-screen phone portrait)
  • 480x320 (full-screen phone landscape)
  • 768x1024 (full-screen tablet portrait)
  • 1024x768 (full-screen tablet landscape)
  • 320x50 (phone banner)
  • 728x90 (tablet banner)
  • 300x250 (inline medium rectangle, often called an MREC or mRect)

When providing us with the creative, you must indicate to us the standard sizes for which the creative is designed. For instance, if the creative layout is adaptive such that it can render properly on both tablets and phones in either landscape or portrait orientations, you must indicate to us that it can run in 320x480, 480x320, 768x1024, and 1024x768 ad slots, while if the creative is designed only to render on phones in the portrait orientation, you must indicate to us that it can run only in 320x480 ad slots.

Close Buttons​

Do not include a close button in your creative. There is considerable variation across publishers in how the close button needs to be handled, and we can only ensure conformance to publisher policies if we handle creatives' close behaviors ourselves. You should design the creative with the understanding that 50px x 50px regions in both top corners may be obscured by the close button. See Watermarks for a visual example.

Watermarks​

You should design the creative with the understanding that the corners may be obscured by small elements necessary to meet regulatory requirements. The image below shows a 320px x 480px creative with red regions indicating areas that may be obscured by the close button or by watermarks. Watermarks can exist in all sizes of creatives.

Watermarks

Video Encoding​

Videos should be provided in mp4 format with the moov atom placed at the start of the file.

Fonts​

The default font on Android devices is Roboto, and the default font on iOS devices is Helvetic Neue. When Liftoff renders the creative on a live device, the font family for the document body will be set to either Roboto or Helvetic Neue with appropriate fallbacks depending on the platform. To preview creatives in the browser as they would appear on devices, you will need to make sure you have these fonts installed and configured inside the creative.

Testing​

You can use the Interactive Ad Validator to:

  • Receive immediate feedback on file errors
  • Visualize how the creative will look on Ad Exchanges
  • Interact with the Ad to validate clicks

When the validation is successful, please make sure to zip the files used before sending them to Liftoff.

Troubleshooting​

If your creative is not displayed properly in Interactive Ad Validator, there are few ways to troubleshoot:

  • Open the html file with a Safari and/or Chrome browser (outside of the validator) and verify the creative functions properly.
  • Verify the code conforms to the specified Requirements. For example, a common issue is the use of iframes.
  • Use the browser developer tools to troubleshoot (press F12 for Google Chrome). Note that the Interactive Ad Validator renders a creative in an iframe (div with id = 'liftoff-snippet') similar to how it would be rendered on a mobile device. So you can check JS errors in the Console tab, identify errors related to loading resources in the network tab, etc. If the creative functions in the validator, it should function on the user's device.

If you identify a problem, try to resolve the issues in your code and then re-upload the updated creative to the Interactive Ad Validator. If there are no errors returned, and the creative is still not displayed properly in the Interactive Ad Validator but does display properly in a browser, please contact your account team for more assistance.

Recommendations​

Asset File Sizes​

We recommend that the total size of a creative (including all images, videos, scripts, fonts, stylesheets, etc.) be less than 700 kb (1 MB at the most) for creatives without videos and < 5MB for creatives with videos. The optimal size depends on many factors. We will not perform any processing of creative assets to optimize file sizes.

Creative Sizing​

Interstitial (full-screen) creatives should render properly on a range of screen sizes. For example, creatives described as 320 px x 480 px will be rendered on phones with a range of viewport sizes, and creatives will perform better if they adapt to the available space.

Support​

If you have any questions about creative integration or the Liftoff creative API, please contact your Liftoff account representative.