Defold for Playable Ads

Develop and build playable ads with the Defold game engine!

This repository contains an easy-to-use script for the Gulp build system, which:

1. Downloads bob.jar.
2. Builds the project for the HTML5 platform using bob.jar.
3. Combines all resources into a single HTML file. The binary of the Defold engine is compressed using Zstd and encoded with Base64.

☝ All you need is to be a little familiar with the command line. The script will do the rest on its own.

Open the build result - https://indiesoftby.github.io/defold-playable-ads/index.html. Also, you can put the link to it in the Ad Tester tool to check that it's a valid playable ad.

Please note that the example build doesn't use any external resources as required. The total size is less than 1 megabyte! In this example, BasisU Decoder, Physics, Live Update are disabled in the engine.

Feel free to ask questions: the topic about this asset is on the Defold forum.

Use these platform tools to preview and validate the generated playable ad before submission:

• Facebook: Playable Ads Preview
• Google: HTML5 Validator
• Mintegral: Playturbo Review
• AppLovin: Playable Preview
• Unity Ads and IronSource: MRAID Validator

Platform integration is selected at runtime by the APIs injected into the ad webview: Facebook FbPlayableAd, Mintegral window.install, MRAID mraid.open, or Google ExitApi, in that order. Injected network APIs take priority over the bundled Google API so previews and builds used on other networks do not route their CTA through Google. MRAID may be exposed either as window.mraid or as a global lexical binding by a validator. MRAID startup integration additionally uses getState and addEventListener when available, while CTA routing only requires mraid.open. The plugin does not inject a fake mraid object or use the user agent to select the ad network; the user agent is only used to choose the iOS or Android store URL. Luna-specific events such as luna:build are only relevant when a playable is exported through Unity Playworks/Luna.

window.Playable provides a shared lifecycle for all platforms. gameLoaded() is reported once after the embedded archive is ready. The game should call gameEnd() when it reaches its packshot or final win/fail state. Calling install() first reports gameEnd() if necessary and then invokes the detected platform's CTA API. retry() forwards the optional Mintegral retry callback.

A playable ad is an interactive advertisement, mostly used to promote mobile games. A playable ad acts as a demo of the game (or product), allowing users to quickly play the game directly in the ad before downloading it.

Accepted sizes for HTML5 playable ad vary between ad networks:

1. Facebook specifications for Playable Ads require that there be a single file for playable ad that contains all assets as part of that single HTML file and assets should be data uri compressed. Also playable asset size should be less than 2MB. And Facebook has started accepting .zip archives with up to 5MB since 2020.
2. Google requires a .ZIP file with a maximum size of 5MB and no more than 512 files within the .ZIP. Plus .ZIP files can contain the following formats: HTML, CSS, JS, GIF, PNG, JPG, JPEG, SVG.
3. AppLovin, and Unity Ads require a single HTML file. The maximum ad size is 5MB.

1. Create a new project, develop some simple game mechanics for your ad. Or use a part of your project that you will advertise.
2. Optimise your project according to the steps in the How To Shrink Your Game Size section below.
3. Follow the simple steps in the Usage section and add the following code to your game to handle the call to action:

local function call_to_action()
    if html5 then
        html5.run([[
            try {
                // <!> The function is located in the `playable_ad/manifests/web/engine_template.html` file.
                // <!> The function exists only when you build your project using `gulp`.
                doClick();
            } catch (e) {
                console.warn(e);
            }
        ]])
    end
end

Set the iOS and Android destination URLs in your project's game.project:

[playable_ad]
app_store_url = https://apps.apple.com/app/idYOUR_IOS_APP_ID
google_play_url = https://play.google.com/store/apps/details?id=YOUR_ANDROID_PACKAGE

The build injects these values into the final HTML as window.PlayableData.URL_IOS and window.PlayableData.URL_ANDROID. MRAID networks use the URL selected from the device user agent when the CTA calls mraid.open(). The same values are used by the generic browser fallback.

The plugin's defaults point to AppLovin's playable-preview applications so an example project can be tested immediately. Replace both defaults before shipping a production creative. Google ExitApi, Facebook FbPlayableAd, and Mintegral window.install normally use the destination configured in the ad network rather than these embedded fallback URLs.

Follow these tips to decrease the resulting size of the HTML file significantly:

1. Customize .appmanifest to keep only the necessary parts of the engine.
2. Keep only the core mechanic of your game and all assets that it requires. Remove everything else!
3. Install the latest version of the Zstd executable (i.e. Zstd 1.5.0 has better compression than Zstd 1.4.x).

You will need the following apps installed on your environment:

• Node.js 18 or newer.
• Java 21 (Defold >=1.9.8).
• Zstd 1.5 or newer.
• Gulp CLI.

npm install --global gulp-cli

sudo apt install --no-install-recommends openjdk-21-jre-headless nodejs npm zstd

npm install --global gulp-cli

brew install node@18
brew install openjdk@21
brew install zstd@1.5.7

npm install --global gulp-cli

Copy the playable_ad folder into the root of your project and the .defignore file. Then, in the command line:

cd your_project_folder
cd playable_ad
npm install
gulp

npm install installs required NodeJS packages (run it only once!).

gulp builds the project into a single HTML file.

The resulting HTML file is located at /playable_ad/build/output_wasm-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE.html.

If a custom HTML template references packshot files named logo.png or playnow.png, put them in /playable_ad/packshot. The build copies any that exist into the intermediate bundle and then embeds their CSS url(https://github.com/...) references as Base64 data URIs. The packshot directory and either file are optional.

You can pass the following arguments from the command line to the script:

--architectures <arg>           Comma separated list of architectures to include: wasm-web.
--embed-archive-js <arg>        Embed `_archive.js` file: true/false (default = true).
--engine-sha1 <arg>             Set sha1 of a specific version of the engine to be used (stable version by default)
--admob                         Build for AdMob with Google's external exitapi.js script.

# The following arguments passed to Bob.jar as is:
--build-server <arg>            The build server (default = https://build.defold.com).
--settings <arg>                Path to a game project settings file. Only one occurrance is allowed.
--variant <arg>                 Specify debug or release (default = release).
--texture-compression <arg>     Use texture compression as specified in texture profiles (default = true).

i.e. run gulp --embed-archive-js=false to build a playable ad with the two files:

• /playable_ad/build/output_wasm-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE.html
• /playable_ad/build/output_wasm-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE_archive.js

Standard builds omit Google's external exitapi.js reference and remain self-contained for Mintegral, Facebook, and MRAID-based networks. For AdMob, run gulp --admob; this retains the literal exitapi.js script required for ExitApi.exit(). Do not use --admob for other ad networks.

MIT.

The splash uses an image from iconfinder.com.

The included music credits:

Silly Intro by Alexander Nakarada | https://creatorchords.com
Music promoted by https://www.chosic.com/free-music/all/free-music/
Attribution 4.0 International (CC BY 4.0)
https://creativecommons.org/licenses/by/4.0/