{"id":15722636,"url":"https://github.com/indiesoftby/defold-playable-ads","last_synced_at":"2026-09-30T18:12:35.471Z","repository":{"id":34690360,"uuid":"182538309","full_name":"indiesoftby/defold-playable-ads","owner":"indiesoftby","description":"Make playable ads with Defold! It's a project with Gulp tasks to bundle the Defold game into a single HTML file.","archived":false,"fork":false,"pushed_at":"2026-08-05T10:27:58.000Z","size":60388,"stargazers_count":62,"open_issues_count":2,"forks_count":11,"subscribers_count":8,"default_branch":"master","last_synced_at":"2026-08-05T12:06:03.124Z","etag":null,"topics":["defold","defold-game-engine","defold-library","playable-ad","playable-ads"],"latest_commit_sha":null,"homepage":"https://indiesoftby.github.io/defold-playable-ads/index.html","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indiesoftby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"claude":null,"gemini":null,"cursor":null,"copilot":null,"dco":null,"cla":null,"disclosure":null}},"created_at":"2019-04-21T13:40:57.000Z","updated_at":"2026-08-05T10:28:01.000Z","dependencies_parsed_at":"2023-01-16T23:00:36.757Z","dependency_job_id":"223d59d9-91d6-4f91-bbda-4134f7b2286d","html_url":"https://github.com/indiesoftby/defold-playable-ads","commit_stats":null,"previous_names":["aglitchman/defold-playable-ads"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/indiesoftby/defold-playable-ads","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indiesoftby%2Fdefold-playable-ads","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indiesoftby%2Fdefold-playable-ads/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indiesoftby%2Fdefold-playable-ads/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indiesoftby%2Fdefold-playable-ads/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indiesoftby","download_url":"https://codeload.github.com/indiesoftby/defold-playable-ads/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indiesoftby%2Fdefold-playable-ads/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":342085742,"owners_count":37883853,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-09-30T02:00:06.001Z","response_time":133,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defold","defold-game-engine","defold-library","playable-ad","playable-ads"],"created_at":"2024-10-03T22:08:43.269Z","updated_at":"2026-09-30T18:12:35.464Z","avatar_url":"https://github.com/indiesoftby.png","language":"JavaScript","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"[![Defold for Playable Ads](cover.jpg)](https://github.com/indiesoftby/defold-playable-ads/)\n\n# Defold for Playable Ads\n\nDevelop and build playable ads with the Defold game engine!\n\nThis repository contains an easy-to-use script for the [Gulp](https://gulpjs.com/) build system, which:\n1. Downloads [bob.jar](https://d.defold.com/stable/).\n2. Builds the project for the HTML5 platform using `bob.jar`.\n3. Combines all resources into **a single HTML file**. The binary of the Defold engine is compressed using Zstd and encoded with Base64.\n\n☝ All you need is to be a little familiar with the command line. The script will do the rest on its own.\n\n**Open the build result - [`https://indiesoftby.github.io/defold-playable-ads/index.html`](https://indiesoftby.github.io/defold-playable-ads/index.html)**. Also, you can put the link to it in the [Ad Tester tool](https://play.google.com/store/apps/details?id=com.unity3d.auicreativetestapp\u0026hl=en\u0026gl=US) to check that it's a valid playable ad.\n\nPlease 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.\n\n## Current Status\n\nFeel free to ask questions: [the topic about this asset is on the Defold forum](https://forum.defold.com/t/defold-for-playable-ads/68689).\n\n| Tool Version   | Defold Version | Status        |\n| -------------- | -------------- | ------------- |\n| 1.5.4          | 1.11.1         | Tested ✅     |\n\n### Supported Platforms\n\n| Platform | Status |\n| ---------| -------|\n| [Google Ads](https://support.google.com/google-ads/answer/9981650?hl=en) | Supported ✅ |\n| [Facebook](https://developers.facebook.com/tools/playable-preview/) | Supported ✅ |\n| [Mintegral](https://www.playturbo.com/review/doc) | Supported ✅ |\n| [Unity Ads](https://docs.unity.com/acquire/en-us/manual/playable-ads-specifications) | Supported ✅ |\n| [AppLovin](https://p.applov.in/playablePreview?create=1) | Supported ✅ |\n| Moloco, Snapchat, etc | Not tested. Can be done on request ⏩ |\n\n### Playable Ad Testers\n\nUse these platform tools to preview and validate the generated playable ad before submission:\n\n- **Facebook:** [Playable Ads Preview](https://developers.facebook.com/tools/playable-preview/)\n- **Google:** [HTML5 Validator](https://h5validator.appspot.com/adwords/asset)\n- **Mintegral:** [Playturbo Review](https://www.playturbo.com/review)\n- **AppLovin:** [Playable Preview](https://p.applov.in/playablePreview?create=1)\n- **Unity Ads and IronSource:** [MRAID Validator](https://tools.playablemaker.com/mraid-validator)\n\nPlatform 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.\n\n`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.\n\n## About A Playable Ad\n\nA [playable ad](https://learn.g2crowd.com/playable-ads) 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.\n\nAccepted sizes for HTML5 playable ad vary between ad networks:\n1. [Facebook specifications for Playable Ads](https://www.facebook.com/business/help/412951382532338?helpref=faq_content) 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.\n2. [Google](https://support.google.com/google-ads/answer/9981650?hl=en) 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.\n3. [AppLovin](https://p.applov.in/playablePreview?create=1\u0026qr=1), and [Unity Ads](https://docs.unity.com/acquire/en-us/manual/playable-ads-specifications) require a single HTML file. The maximum ad size is 5MB.\n\n## Playable Ad Development Steps With Defold\n\n1. Create a new project, develop some simple game mechanics for your ad. Or use a part of your project that you will advertise.\n2. Optimise your project according to the steps in the `How To Shrink Your Game Size` section below.\n3. Follow the simple steps in the `Usage` section and add the following code to your game to handle the call to action:\n\n```lua\nlocal function call_to_action()\n    if html5 then\n        html5.run([[\n            try {\n                // \u003c!\u003e The function is located in the `playable_ad/manifests/web/engine_template.html` file.\n                // \u003c!\u003e The function exists only when you build your project using `gulp`.\n                doClick();\n            } catch (e) {\n                console.warn(e);\n            }\n        ]])\n    end\nend\n```\n\n### Store URLs\n\nSet the iOS and Android destination URLs in your project's `game.project`:\n\n```ini\n[playable_ad]\napp_store_url = https://apps.apple.com/app/idYOUR_IOS_APP_ID\ngoogle_play_url = https://play.google.com/store/apps/details?id=YOUR_ANDROID_PACKAGE\n```\n\nThe build injects these values into the final HTML as\n`window.PlayableData.URL_IOS` and `window.PlayableData.URL_ANDROID`. MRAID\nnetworks use the URL selected from the device user agent when the CTA calls\n`mraid.open()`. The same values are used by the generic browser fallback.\n\nThe plugin's defaults point to AppLovin's playable-preview applications so an\nexample project can be tested immediately. **Replace both defaults before\nshipping a production creative.** Google `ExitApi`, Facebook `FbPlayableAd`,\nand Mintegral `window.install` normally use the destination configured in the\nad network rather than these embedded fallback URLs.\n\n\u003e [!TIP]\n\u003e 99% of playable ad build time with the script presented here takes a build on the remote Defold extender server. And usually it is about 1-2 minutes! So we advise you to develop your ad as a normal game and be pleased with super fast desktop builds. And only when you are ready to upload the playable ad to the ad system, then run the playable ad build script.\n\n## How To Shrink Your Game Size\n\nFollow these tips to decrease the resulting size of the HTML file significantly:\n\n1. Customize `.appmanifest` to keep only the necessary parts of the engine.\n2. Keep only the core mechanic of your game and all assets that it requires. Remove everything else!\n3. Install the latest version of the [Zstd executable](https://github.com/facebook/zstd/releases) (i.e. Zstd 1.5.0 has better compression than Zstd 1.4.x).\n\n\u003e [!IMPORTANT]\n\u003e And, the last tip and the most important: set [HTML5 heap size](https://defold.com/manuals/project-settings/#heap-size) as small as possible (**minimum is 32MB**, default is 256MB) to allow your game to run on low-end Android devices.\n\n## Required Prerequisites\n\nYou will need the following apps installed on your environment:\n- Node.js 18 or newer.\n- Java 21 (Defold \u003e=1.9.8).\n- Zstd 1.5 or newer.\n- Gulp CLI.\n\n\u003cdetails\u003e\n  \u003csummary\u003eWindows\u003c/summary\u003e\n\n1. Download and install [Java 21](https://adoptium.net/).\n2. Download and unpack [Zstd for Windows 64-bit](https://github.com/facebook/zstd/releases/download/v1.5.7/zstd-v1.5.7-win64.zip). Add the path to the `zstd.exe` executable to the PATH environment variable. Also, you can just put `zstd.exe` in the `playable_ad` folder - the script will use it from here.\n3. Download [Node.js Windows Installer (.msi) for 64-bit](https://nodejs.org/en/download/) and install it.\n4. Open `cmd.exe` and run to install Gulp CLI:\n\n```\nnpm install --global gulp-cli\n```\n\n\u003e [!NOTE]\n\u003e We recommend using Windows Terminal to see the coloured log. If you use PowerShell to run your scripts, run `gulp --no-color` to avoid the problem when the text colour matches the background colour.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eUbuntu/Debian or Windows Subsystem for Linux (WSL)\u003c/summary\u003e\n\n```\nsudo apt install --no-install-recommends openjdk-21-jre-headless nodejs npm zstd\n\nnpm install --global gulp-cli\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003emacOS\u003c/summary\u003e\n\nInstall [brew](https://brew.sh/) and paste that in a macOS Terminal prompt:\n\n```\nbrew install node@18\nbrew install openjdk@21\nbrew install zstd@1.5.7\n\nnpm install --global gulp-cli\n```\n\u003c/details\u003e\n\n\n## Usage\n\nCopy the `playable_ad` folder into the root of your project and the `.defignore` file. Then, in the command line:\n\n```\ncd your_project_folder\ncd playable_ad\nnpm install\ngulp\n```\n\n`npm install` installs required NodeJS packages (run it only once!). \n\n`gulp` builds the project into a single HTML file.\n\nThe resulting HTML file is located at `/playable_ad/build/output_wasm-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE.html`.\n\nIf a custom HTML template references packshot files named `logo.png` or\n`playnow.png`, put them in `/playable_ad/packshot`. The build copies any that\nexist into the intermediate bundle and then embeds their CSS `url(...)`\nreferences as Base64 data URIs. The packshot directory and either file are\noptional.\n\n### Command Line Arguments\n\nYou can pass the following arguments from the command line to the script:\n\n```bash\n--architectures \u003carg\u003e           Comma separated list of architectures to include: wasm-web.\n--embed-archive-js \u003carg\u003e        Embed `_archive.js` file: true/false (default = true).\n--engine-sha1 \u003carg\u003e             Set sha1 of a specific version of the engine to be used (stable version by default)\n--admob                         Build for AdMob with Google's external exitapi.js script.\n\n# The following arguments passed to Bob.jar as is:\n--build-server \u003carg\u003e            The build server (default = https://build.defold.com).\n--settings \u003carg\u003e                Path to a game project settings file. Only one occurrance is allowed.\n--variant \u003carg\u003e                 Specify debug or release (default = release).\n--texture-compression \u003carg\u003e     Use texture compression as specified in texture profiles (default = true).\n```\n\ni.e. run `gulp --embed-archive-js=false` to build a playable ad with the two files:\n\n* `/playable_ad/build/output_wasm-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE.html`\n* `/playable_ad/build/output_wasm-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE_archive.js`\n\nStandard builds omit Google's external `exitapi.js` reference and remain\nself-contained for Mintegral, Facebook, and MRAID-based networks. For AdMob,\nrun `gulp --admob`; this retains the literal `exitapi.js` script required for\n`ExitApi.exit()`. Do not use `--admob` for other ad networks.\n\n## License\n\nMIT.\n\nThe splash uses an image from [iconfinder.com](https://www.iconfinder.com/icons/1222768/facebook_ads_facebook_marketing_marketing_icon).\n\nThe included music credits:\n```\nSilly Intro by Alexander Nakarada | https://creatorchords.com\nMusic promoted by https://www.chosic.com/free-music/all/free-music/\nAttribution 4.0 International (CC BY 4.0)\nhttps://creativecommons.org/licenses/by/4.0/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findiesoftby%2Fdefold-playable-ads","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findiesoftby%2Fdefold-playable-ads","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findiesoftby%2Fdefold-playable-ads/lists"}