{"id":15722636,"url":"https://github.com/indiesoftby/defold-playable-ads","last_synced_at":"2025-05-07T10:11:19.294Z","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":"2024-10-23T12:20:13.000Z","size":54588,"stargazers_count":48,"open_issues_count":1,"forks_count":7,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-12-19T03:09:43.867Z","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}},"created_at":"2019-04-21T13:40:57.000Z","updated_at":"2024-11-16T17:58:12.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":[],"tags_count":15,"template":false,"template_full_name":null,"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","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231439030,"owners_count":18376836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2025-05-07T10:11:19.280Z","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.2          | 1.9.8          | Tested ✅     |\n\n### Supported Platforms\n\n| Platform | Status |\n| ---------| -------|\n| [Facebook](https://developers.facebook.com/tools/playable-preview/) | Supported ✅ |\n| [Unity Ads](https://docs.unity.com/acquire/en-us/manual/playable-ads-specifications) | Supported ✅ |\n| AppLovin, Snapchat, etc | Not tested. Can be done on request ⏩ |\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\u003e [!NOTE]\n\u003e If your ad is for Unity Ads, change the links to App Store and Google Play in the `playable_ad/manifests/web/engine_template.html` file at the very bottom in the `doClick()` function. This should be done directly in this file, as a playable ad testing tools of the ad platforms usually require these links to be directly in the html file.\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.5/zstd-v1.5.5-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.5\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_js-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE.html`.\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: js-web,wasm-web (default = 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\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_js-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE.html`\n* `/playable_ad/build/output_js-web/YOUR_PROJECT_TITLE/YOUR_PROJECT_TITLE_archive.js`\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"}