Building dynamic creatives for the Cortex Player

Introduction

A dynamic creative is an ad that changes based on variables like location or time. With dynamic creatives, you can show the right message to the right audience, instead of a general creative. 

This guide explains how to structure both static and animated dynamic creatives so the Cortex player can display them correctly.

File Structure

Dynamic creatives must be zipped and uploaded to an order in the Ad Server. The .zip file must include a file named index.html in the root (parent) directory. Other files (JavaScript, CSS, images, videos, etc.) can be organized however you like. 

Required files are shown in orange in the diagram below.

Fetching Information from the Cortex Player

Your dynamic creative can call the getConfig function to fetch the Player’s venue ID and any custom parameters. You can add properties like device location to custom parameters so dynamic creatives can reference them. For more technical detail, see Config API and Calling the API with HTML and Javascript here. 

Detecting When the Creative is Visible

Cortex loads creatives in the background before showing them on-screen. Dynamic creatives can listen for events that explain what is happening: 

• cortex-ready: creative is set up in the background but isn’t visible yet
• cortex-visible: creative is visible on-screen
• cortex-hidden: creative is no longer visible

The time between cortex-ready and cortex-visible depends on the app your device uses: 

• The UAS app prepares creatives a few milliseconds before they appear
• VSA (in development; available to select partners) prepares them ~5 seconds before  

For more technical detail and an example of how a dynamic creative can listen for these events, see Calling the API with HTML and Javascript here. 

Best Practices 

1. Listen for cortex-ready before calling getConfig
   • See the events and parameters dynamic creative sample at the bottom of this article for a working example 
2. Pause animations/videos until cortex-visible fires
   • See the animated dynamic creative sample at the bottom of this article for a working example 

Caching Dynamic Creatives

The Cortex Player caches all .zip creatives it plays, including their embedded assets. However, it doesn’t cache assets or data fetched from the internet in real-time.

Cached dynamic creatives can play when the Player isn’t connected to the internet. If your creative fetches information from the internet in real-time, include logic to display an offline-friendly version when real-time requests are unsuccessful. See the webpage dynamic creative sample at the bottom of this article for a working example.

Sample Dynamic Creatives

When building your dynamic creative, you can reference three sample dynamic creatives attached to this article: 

• animated-dynamic-creative-sample: uses cortex-ready and cortex-visible events to start animations and videos when the dynamic creative appears on-screen
  • Includes two examples; sub-folders have their own index.html files. To play one, zip a sub-folder (so index.html is in the top directory) and upload it as a creative to an Ad Server order
• events-and-parameter-dynamic-creative-sample: listens for visible, ready, and hidden events, and uses getConfig to retrieve Player properties (parameters)
• webpage-with-fallback-dynamic-creative-sample: tries to loads a webpage for 2 seconds, or shows a local (cached) image if the webpage doesn’t load 
  • Only recommended if your devices use VSA (not the UAS app) since VSA prepares creatives more than 2 seconds early

Frequently Asked Questions