{"id":26638019,"url":"https://github.com/smoudjs/playable-scripts","last_synced_at":"2025-04-10T19:50:46.093Z","repository":{"id":282462685,"uuid":"948685700","full_name":"smoudjs/playable-scripts","owner":"smoudjs","description":"Accelerate HTML5 playable ad development and production across different ad networks, with a single tool, which offering both a streamlined CLI and a flexible API.","archived":false,"fork":false,"pushed_at":"2025-03-31T07:58:42.000Z","size":671,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-31T08:02:52.761Z","etag":null,"topics":["ad-builder","ad-network","ad-scripts","api","applovin","build-tool","builder","cli","dapi","facebook","google","ironsource","mraid","playable","playable-ad","scripts","unity","webpack"],"latest_commit_sha":null,"homepage":"","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/smoudjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-03-14T19:16:22.000Z","updated_at":"2025-03-31T07:58:45.000Z","dependencies_parsed_at":"2025-03-14T19:52:17.810Z","dependency_job_id":"cea3db0a-4e79-4393-aad1-665467a9b35e","html_url":"https://github.com/smoudjs/playable-scripts","commit_stats":null,"previous_names":["smoudjs/playable-scripts"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoudjs%2Fplayable-scripts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoudjs%2Fplayable-scripts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoudjs%2Fplayable-scripts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoudjs%2Fplayable-scripts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smoudjs","download_url":"https://codeload.github.com/smoudjs/playable-scripts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248283106,"owners_count":21077773,"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":["ad-builder","ad-network","ad-scripts","api","applovin","build-tool","builder","cli","dapi","facebook","google","ironsource","mraid","playable","playable-ad","scripts","unity","webpack"],"created_at":"2025-03-24T17:24:51.126Z","updated_at":"2025-04-10T19:50:46.073Z","avatar_url":"https://github.com/smoudjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @smoud/playable-scripts\n\n[![npm version](https://img.shields.io/npm/v/@smoud/playable-scripts)](https://www.npmjs.com/package/@smoud/playable-scripts)\n[![Downloads](https://img.shields.io/npm/dw/@smoud/playable-scripts)](https://www.npmjs.com/package/@smoud/playable-scripts)\n[![DeepScan grade](https://deepscan.io/api/teams/19616/projects/29071/branches/935562/badge/grade.svg)](https://github.com/smoudjs/playable-scripts)\n[![License](https://img.shields.io/npm/l/@smoud/playable-scripts)](https://github.com/smoudjs/playable-scripts/blob/master/LICENSE)\n\n**The Ultimate Build Tool for HTML5 Playable Ads**\n\n`@smoud/playable-scripts` is a powerful CLI and API tool designed to streamline the development, optimization, and packaging of HTML5 playable ads for multiple ad networks. Whether you're building playables for **Google Ads, Meta (Facebook), AppLovin, Unity, IronSource, Vungle, Mintegral, and more**, this tool provides a one-command solution to handle network-specific requirements, asset optimization, and build automation.\n\n## Features\n\n- 🚀 **One-Command Build Process** – Easily generate builds for different ad networks.\n- ⚡ **Automatic Optimizations** – Includes minification, tree-shaking, and dead code elimination.\n- 🎯 **Pre-configured for Major Ad Networks** – Works out of the box with **Google Ads, Meta (Facebook), AppLovin, Unity, IronSource, Vungle, Mintegral, and many more**.\n- 🛠️ **Customizable** – Extend the default build pipeline as needed.\n\n## Installation\n\n```bash\nnpm install --save-dev @smoud/playable-scripts\n```\n\n## Quick Start\n\n1. Install the package\n2. Create a basic project structure:\n\n```\nyour-playable/\n  ├── src/\n  │   ├── index.html\n  │   └── index.ts\n  ├── package.json\n  └── build.json (optional)\n```\n\n3. Add scripts to your package.json:\n\n```json\n{\n  \"scripts\": {\n    \"dev\": \"playable-scripts dev\",\n    \"build\": \"playable-scripts build\"\n  }\n}\n```\n\n4. Start development:\n\n```bash\nnpm run dev\n```\n\n5. Build for google:\n\n```bash\nnpm run build google\n```\n\n## 🎮 Playable SDK\n\nWhile `@smoud/playable-scripts` handles the build process, you'll need additional functionality to make your playable ads fully compatible across different ad networks. This is where [`@smoud/playable-sdk`](https://www.npmjs.com/package/@smoud/playable-sdk) comes in.\n\n### ✨ Why Use Playable SDK?\n\n`@smoud/playable-sdk` is a powerful, unified SDK that:\n\n- 🔄 Seamlessly integrates with multiple ad network SDKs (MRAID, Google, Facebook, Vungle, etc.)\n- 🎯 Provides a standardized interface for all networks\n- 🚀 Ensures cross-platform compatibility and optimization\n- 🛠️ Handles ad network-specific requirements automatically\n- 💪 Lets you focus on creating engaging interactive ads\n\n### 🔧 Implementation Guide\n\n#### 1. Installation\n\n```sh\nnpm install @smoud/playable-sdk\n```\n\n#### 2. Basic Setup\n\n```javascript\nimport { sdk } from '@smoud/playable-sdk';\n\n// Initialize SDK with container dimensions\nsdk.init((width, height) =\u003e {\n  new Game(width, height);\n});\n```\n\n#### 3. Event Handling\n\n```javascript\nsdk.on('resize', game.resize, game);\nsdk.on('pause', game.pause, game);\nsdk.on('resume', game.resume, game);\nsdk.on('volume', game.volume, game);\nsdk.on('finish', game.finish, game);\n```\n\n#### 4. Playable Lifecycle\n\n```javascript\n// Mark as resources loaded and gameplay started\nsdk.start();\n\n// Mark as complete\nsdk.finish();\n\n// Handle CTA clicks\ninstallButton.onclick = () =\u003e sdk.install();\n```\n\n### 🔍 Alternative Approach\n\nIf you choose not to use `@smoud/playable-sdk`, you'll need to:\n\n- Implement network-specific requirements manually\n- Handle compatibility issues across different platforms\n- Manage SDK integrations individually\n\nFor detailed implementation guidelines, visit our [GitHub repository](https://github.com/smoudjs/playable-sdk).\n\n## CLI Arguments\n\n| Option                    | Description                               | Default                                                   | Example                          |\n| ------------------------- | ----------------------------------------- | --------------------------------------------------------- | -------------------------------- |\n| **Ad Network**            | Target ad network                         | `preview`                                                 | `applovin`                       |\n| `--out-dir`               | Output directory template for build files | `dist`                                                    | `--out-dir build/{version}`      |\n| `--build-config`          | Path to build.json configuration file     | `build.json`                                              | `--build-config custom.json`     |\n| `--ts-config`             | Path to tsconfig.json configuration file  | `tsconfig.json`                                           | `--ts-config tsconfig.prod.json` |\n| `--js-config`             | Path to jsconfig.json configuration file  | `jsconfig.json`                                           | `--js-config jsconfig.prod.json` |\n| `--protocol`              | Ad protocol to use                        | `none`                                                    | `--protocol mraid`               |\n| `--port`                  | Development server port number            | `3000`                                                    | `--port 8080`                    |\n| `--open`                  | Open browser automatically                | `false`                                                   | `--open`                         |\n| `--dev`                   | Enable development mode                   | `true` for dev\u003cbr\u003e`false` for build                       | `--dev false`                    |\n| `--filename`              | Template for output filename              | [See Build Configuration](#build-configuration-buildjson) | `--filename {app}-{version}`     |\n| `--app`                   | Application name                          | [See Build Configuration](#build-configuration-buildjson) | `--app MyGame`                   |\n| `--name`                  | Concept name                              | [See Build Configuration](#build-configuration-buildjson) | `--name Concept1`                |\n| `--version`               | Build version                             | [See Build Configuration](#build-configuration-buildjson) | `--version v2.1`                 |\n| `--language`              | Language code                             | [See Build Configuration](#build-configuration-buildjson) | `--language fr`                  |\n| `--skip-recommended-meta` | Skip recommended meta tags injection      | -                                                         | `--skip-recommended-meta`        |\n| `--debugger`              | URL of debugger script to inject          | -                                                         | `--debugger http://...`          |\n\n#### Target Ad Network\n\nSpecify the target network directly as a command argument:\n\n```bash\nplayable-scripts build unity\n```\n\n#### Supported Networks\n\n- `preview` (Preview) - Browser preview\n- `applovin` (AL) - AppLovin\n- `unity` (UNITY) - Unity Ads\n- `google` (GOOGLE) - Google Ads\n- `ironsource` (IS) - ironSource\n- `facebook` (FB) - Facebook\n- `moloco` (MOLOCO) - Moloco\n- `adcolony` (ADCOLONY) - AdColony\n- `mintegral` (MINTEGRAL) - Mintegral\n- `vungle` (VUNGLE) - Vungle\n- `tapjoy` (TAPJOY) - Tapjoy\n- `snapchat` (SNAPCHAT) - Snapchat\n- `tiktok` (TIKTOK) - TikTok / Toutiao\n- `appreciate` (APPRECIATE) - Appreciate\n- `chartboost` (CHARTBOOST) - Chartboost\n- `pangle` (PANGLE) - Pangle\n- `mytarget` (MYTARGET) - MyTarget\n- `liftoff` (LIFTOFF) - Liftoff\n\n#### Supported Protocols\n\n- `none` - No specific ad protocol\n- `mraid` - Mobile Rich Media Ad Interface Definitions\n- `dapi` - Display Advertising Programming Interface\n\nNote: MRAID protocol is automatically used for ironSource, AppLovin, Unity, Appreciate, Snapchat, Chartboost, MyTarget, Liftoff, and AdColony networks.\n\n## Build Configuration (build.json)\n\nThe `build.json` file allows you to customize build options. Here's the format:\n\n```json\n{\n  \"filename\": \"{app}_{name}_{version}_{date}_{language}_{network}\",\n  \"app\": \"AppName\",\n  \"name\": \"ConceptName\",\n  \"version\": \"v1\",\n  \"language\": \"EN\",\n  \"google_play_url\": \"https://play.google.com/store/games\",\n  \"app_store_url\": \"https://www.apple.com/app-store/\"\n}\n```\n\nAll fields are optional and will use the default values shown [here](#default-options) if not specified.\n\nCheck [Default options](#default-options) to see full list of available options.\n\n## Output directory and filename template\n\nThe `outDir` and `filename` templates supports the following variables:\n\n- `{app}` - Application name\n- `{name}` - Concept name\n- `{version}` - Build version\n- `{date}` - Current date\n- `{language}` - Language code\n- `{network}` - Target ad network\n- `{hash}` - Unique build identifier\n\n## Defines\n\nThe following global defines are automatically available in your code during development and build:\n\n| Define            | Description                              | Example Value                        |\n| ----------------- | ---------------------------------------- | ------------------------------------ |\n| `__DEV__`         | Boolean flag indicating development mode | `true` or `false`                    |\n| `GOOGLE_PLAY_URL` | Google Play Store URL constant           | `\"https://play.google.com/store/\"`   |\n| `APP_STORE_URL`   | App Store URL constant                   | `\"https://www.apple.com/app-store/\"` |\n| `AD_NETWORK`      | Current advertising network identifier   | `\"google\"`, `\"facebook\"`, etc.       |\n| `AD_PROTOCOL`     | Current advertising protocol             | `\"none\"`, `\"mraid\"`, `\"dapi\"`        |\n| `APP`             | Application name constant                | `\"AppName\"`                          |\n| `NAME`            | Build name constant                      | `\"ConceptName\"`                      |\n| `VERSION`         | Build version constant                   | `\"v1\"`                               |\n| `LANGUAGE`        | Current language code                    | `\"en\"`, `\"es\"`, etc.                 |\n| `BUILD_HASH`      | Unique build hash                        | `\"a1b2c3d4\"`                         |\n\nThese defines can be used in your code for conditional logic:\n\n```javascript\nif (__DEV__) {\n  console.log('Dev mode is active');\n}\n\nif (AD_NETWORK === 'google') {\n  // google network specific code\n}\n\nconsole.log(`Current language: ${LANGUAGE}`);\n```\n\nYou can also add custom defines by modifying the `defines` property in your build.json file:\n\n```json\n{\n  \"defines\": {\n    \"CUSTOM_DEFINE\": \"'custom value'\",\n    \"FEATURE_FLAG\": \"true\"\n  }\n}\n```\n\n## Meta Tags\n\n`@smoud/playable-scripts` automatically manages viewport meta tags for optimal display across devices.\n\n**Do not specify your own `viewport` meta tag** as it will be handled and injected into your HTML automatically:\n\n- `\u003cmeta name=\"viewport\" content=\"width=device-width,initial-scale=1.0,viewport-fit=cover,maximum-scale=1.0,user-scalable=no\"\u003e`\n\n\u003e For Mintegral network, a special viewport configuration is used:\n\u003e `\u003cmeta name=\"viewport\" content=\"width=device-width,user-scalable=no,initial-scale=1.0,minimum-scale=1.0,maximum-scale=1.0\"\u003e`\n\nAdditionally, unless `--skip-recommended-meta` is provided, the following recommended meta tags are automatically injected:\n\n```html\n\u003cmeta name=\"HandheldFriendly\" content=\"True\" /\u003e\n\u003cmeta name=\"cleartype\" http-equiv=\"cleartype\" content=\"on\" /\u003e\n\u003cmeta name=\"apple-mobile-web-app-capable\" content=\"yes\" /\u003e\n\u003cmeta name=\"mobile-web-app-capable\" content=\"yes\" /\u003e\n\u003cmeta http-equiv=\"X-UA-Compatible\" content=\"IE=10\" /\u003e\n```\n\n## Examples\n\n### Development\n\nStart development server:\n\n```bash\nplayable-scripts dev --port 3000 --open\n```\n\n### Building\n\nBuild for AppLovin:\n\n```bash\nnpx playable-scripts build applovin\n```\n\n```bash\nnpm run build applovin\n```\n\nBuild with DAPI protocol with specific version:\n\n```bash\nnpx playable-scripts build ironsource --protocol dapi --version endcard_2\n```\n\n```bash\nnpm run build ironsource -- --protocol dapi --version endcard_2\n```\n\n## API Reference\n\nThe package provides a programmatic API for integration into your build tools:\n\n### Default Options\n\n```javascript\nconst options = {\n  outDir: 'dist', // Output directory for build files\n  buildConfig: 'build.json', // Path to build.json configuration file\n  tsConfig: 'tsconfig.json', // For TypeScript projects, path to tsconfig.json file\n  jsConfig: 'jsconfig.json', // For JavaScript projects, path to jsconfig.json file\n  port: 3000, // Development server port number\n  open: false, // Whether to open browser automatically\n  protocol: 'none', // Ad protocol to use (none, mraid, or dapi)\n  network: 'preview', // Target Ad network\n  filename: '{app}_{name}_{version}_{date}_{language}_{network}', // Template for output filename\n  app: 'AppName', // Application name used in build filename and BUILD_APP define\n  name: 'ConceptName', // Concept name used in build filename and BUILD_NAME define\n  version: 'v1', // Version name used in build filename and BUILD_VERSION define\n  language: 'en', // Language code for localization\n  google_play_url: 'https://play.google.com/store/games', // Google Play Store URL\n  app_store_url: 'https://www.apple.com/app-store/', // App Store URL\n  dev: undefined, // Development mode flag\n  skipRecommendedMeta: undefined, // Skip recommended meta tags injection\n  debugger: undefined, // URL of debugger script to inject\n  defines: {} // Defines options\n};\n```\n\n### Configuration\n\n```javascript\nconst { options, mergeOptions, parseArgvOptions } = require('@smoud/playable-scripts');\n\n// Merge custom options with defaults\nconst customOptions = mergeOptions(options, {\n  outDir: 'custom-dist',\n  network: 'applovin'\n});\n\n// Parse CLI arguments\nconst newOptions = parseArgvOptions([\n  {\n    name: 'custom-option',\n    hasValue: true,\n    defaultValue: 'default'\n  }\n]);\n\n// Change build options\nnewOptions.app = 'Example';\nnewOptions.version = 'v4';\n\n// Change defines options\nnewOptions.defines = {\n  APP_STORE_URL: JSON.stringify('https://www.apple.com/app-store/');\n  __DEV__: JSON.stringify(false);\n}\n\n// Merge new options with defaults\nconst finalOptions = mergeOptions(options, newOptions);\n```\n\n### Webpack Configuration\n\n```javascript\nconst { makeWebpackDevConfig, makeWebpackBuildConfig } = require('@smoud/playable-scripts');\nconst { webpackCommonConfig } = require('@smoud/playable-scripts');\nconst { merge } = require('webpack-merge');\n\n// Create development configuration\nconst devConfig = makeWebpackDevConfig(customOptions);\n\n// Create production configuration\nconst buildConfig = makeWebpackBuildConfig();\n\n// Create production configuration with custom definitions\nconst buildConfig2 = makeWebpackBuildConfig(customOptions, customDefinitions);\n\n// Create production configuration with custom definitions and custom webpack config to merge\nconst buildConfig3 = makeWebpackBuildConfig(customOptions, customDefinitions, customWebpackConfig);\n\n// Create your own webpack config, based on webpackCommonConfig\nconst customConfig = merge(webpackCommonConfig, {\n  // ...\n});\n```\n\n### Development Server\n\n```javascript\nconst { runDev } = require('@smoud/playable-scripts');\n\n// Start development server with custom config\nrunDev(webpackDevConfig);\n\n// Start development server with default config\nrunDev();\n\n// Start development server with custom definitions\nrunDev(null, null, customDefines);\n```\n\n### Production Build\n\n```javascript\nconst { runBuild } = require('@smoud/playable-scripts');\n\n// Run production build with custom config\nrunBuild(webpackBuildConfig);\n\n// Run production build with default config\nrunBuild();\n\n// Run production build with custom options\nrunBuild(null, customOptions);\n```\n\n### Plugins\n\nThe package includes several webpack plugins for ad network integration:\n\n```javascript\nconst { ExitAPIInjectorPlugin, DebuggerInjectionPlugin } = require('@smoud/playable-scripts');\n\n// Google Ads ExitAPI integration\nnew ExitAPIInjectorPlugin();\n\n// Custom debugger integration\nnew DebuggerInjectionPlugin('http://debugger-url');\n```\n\n## Demo Projects\n\nGet started quickly with our template projects:\n\n- [playable-template-base](https://github.com/smoudjs/playable-template-base) - Clean TypeScript starter with minimal dependencies\n- [playable-template-base-js](https://github.com/smoudjs/playable-template-base-js) - Clean JavaScript starter with minimal dependencies\n- [playable-template-pixi](https://github.com/smoudjs/playable-template-pixi) - PixiJS template for 2D playable ads\n- [playable-template-three](https://github.com/smoudjs/playable-template-three) - Three.js template for 3D playable ads\n- [playable-template-phaser](https://github.com/smoudjs/playable-template-phaser) - Phaser template for 2D playable ads\n\n## Issues\n\nReport issues at [GitHub Issues](https://github.com/smoudjs/playable-scripts/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmoudjs%2Fplayable-scripts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmoudjs%2Fplayable-scripts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmoudjs%2Fplayable-scripts/lists"}