Knowledge Base

HTML Packages

Suggest Edits

Doohly supports the use of dynamic HTML Creatives. This opens up the possibilities of what your creatives can do. We have made using  HTML Creatives as simple as possible.

Minimum player version: v4.2.3 [android] [windows]

HTML Template: See below

Basic Requirements

HTML Creatives can be uploaded into Doohly by using a zip file. There are a few basic requirements of the contents that make up a HTML Creative.

  1. It needs to contain a single index.html file in the root of the zip file
  2. The index.html file must contain a <head> section
  3. It cannot contain another zip file

These requirements will get checked when you try to upload the zip file into the Doohly Creative Library. If there is an issue, an error will appear, otherwise, it will be uploaded and ready for use!

Assets

Assets refers to CSS, JS, images, videos, fonts & other files. There are two ways of using assets in HTML Creatives: local & remote.

  • Local assets are those that get bundled into the zip file along with index.html.
  • Remote assets are those that are requested by index.html but are not bundled into the zip file

📘

Note: It is always preferable to make use of local assets as these will be cached on the player which allows for playback even without an internet connection.

Supported File Types:

  • Video: MP4 (h.264 & h.265)
  • Photo: JPG, JPEG and PNG

📘

Note: WebM files that are used in HTML packages will be streamed instead of preloaded. This will cause higher CPU & disk usage and likely result in crashing. For the best performance, be sure to use MP4 video files.

<head> Section

When creating a HTML package, it is a requirement to include a <head> section within the index.html file. This section serves to hold meta-data about your package, but also should include a <script> section with the package's main() function.

Creative API

There are some cases where you will want to trigger actions in your HTML Creative during its lifecycle. For example, starting a video or animation when the creative is first displayed on screen. Making use of the Creative API will allow you to do this & more.

Setup

First you will need to define a main() function within the of your HTML. This is the entry point and will be automatically called when the creative is being first prepared on the player.

<script>
     async function main() {
       ...
     }
</script>

Usage

Within main() you can get access to the Creative API. Currently, you are able to:

Listen for events related to the creative lifecycle.

  • play: emitted when the creative is first displayed on the screen

  • pause: emitted when the creative is interrupted

  • resume: emitted when a paused creative is resumed

    <script>
  async function main() {
    doohly.player.on('play', () => {
      // start any animations / video ...
    })
    doohly.player.on('pause', () => {
      // stop any animations / video ...
    })
    doohly.player.on('resume', () => {
      // start any animations / video ...
    }) 
 
    // You can access package information here as well. Examples below:
    // doohly.player.name
    // doohly.frame.name
    // doohly.campaign.name
    // doohly.booking.name
    // doohly.creative.name
  }
</script>

📘

Note: The Doohly object will not exist before main() is called so all code requiring it should start from within main()

Creative Package Control

Within a package it is possible to tell the player that it has finished playing or it should be skipped due to some reason. These are primarily used in programmatic packages like from Hivestack

  • doohly.player.end() Is called when the package has determined it has finished playing. If this is called the player will stop playing the package and move onto the next creative
  • doohly.player.skip() Is called when the package has determined that there is nothing for it to play and it should be skipped this time instead of being played. If a package is partway through playing on the screen & this function is called it will stop playing and will be tracked as skipped

Creative Package Information

There is a range of information that you can make use of within a package. This information can be found on the doohly window object. The campaign & booking information is based on which booking the package was added to. 

Below is what information is available within a package:

window.doohly = {
  player: {
    id: string
    name: string
    location: {
      lat: number // Set via Web App
      long: number // Set via Web App
      address: string | null 
      city: string | null // "Melbourne"
      state: string | null // "Victoria"
      postcode: string | null // "3000"
      country: string | null // "Australia"
    }
    tags: { name: string }[]
  }
  frame: {
    id: string
    name: string
  }
  campaign: {
    id: string
    name: string
    externalId: string | null
    tags: { name: string }[]
  } | null
  booking: {
    id: string
    name: string
    externalId: string | null
    tags: { name: string }[]
  }
  creative: {
    id: string
    name: string
  } 
}

Usage Examples

Weather Data Lookup

You can make use of the players location, set via the web app, to look up weather information based on the player and then display the information on the screen. This example shows how you could use the postcode of the player to find local weather information.

<script>
     async function main() {
        const postcode = doohly.player.location.postcode
        const url = `https://some-weather-lookup-service.com?postcode=${postcode}`
        const data = await fetch(url)
        // Display retruned data
     }
</script>

Using Tags As Dynamic Content

Any tags added to a player, campaign or booking are made available in packages and can be used to control or display different content based on those tags. This allows one package to display different content based on what player it is playing on or what campaign/booking it is part of.

This example searches the player tags for one starting with building-name/, an example being building-name/Main Office, and if it's found the name is then displayed in the creative otherwise it uses a default placeholder title. This example could also be done using campaign or booking tags.

<script>
     async function main() {
        const tagPrefix = 'building-name/'
        const buildingNameTag = doohly.player.tags.find((tag) => tag.name.startsWith(tagPrefix))
        const buildingNameElement = document.getElementById('building-name')
        const name = buildingNameTag ? buildingNameTag.name.replace(tagPrefix, '') : 'Placeholder Building Name'
        buildingNameElement.innerText = name
     }
</script>

Error Handling

The Doohly Player will attempt to prepare the HTML Creative just before it’s going to be played, but if the HTML Creative fails during the preparation phase, it will be skipped and proceed to play the remainder of the loop.

Template

We have also prepared a template that can be used as the starting point for a new HTML Creative.

You can download it here.

Updated about 1 year ago