{"id":26590151,"url":"https://github.com/smoudjs/playable-sdk","last_synced_at":"2025-03-23T13:21:20.916Z","repository":{"id":282300716,"uuid":"946232000","full_name":"smoudjs/playable-sdk","owner":"smoudjs","description":"It's unified Playable SDK that supports MRAID, Google, Facebook, Vungle, and many more, simplifying playable ad development with a standardized interface for seamless cross-network compatibility. 🚀","archived":false,"fork":false,"pushed_at":"2025-03-21T11:11:36.000Z","size":458,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-21T12:25:35.091Z","etag":null,"topics":["ad-network","ads","applovin","dapi","facebook","google","html5","ironsource","mintegral","mraid","playable","playable-sdk","playablesdk","sdk","unity","vungle"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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":"LICENSE","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-10T20:23:07.000Z","updated_at":"2025-03-21T11:11:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"038fdb6c-123c-45d3-81fe-02b0e2f14f70","html_url":"https://github.com/smoudjs/playable-sdk","commit_stats":null,"previous_names":["smoudjs/playable-sdk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoudjs%2Fplayable-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoudjs%2Fplayable-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoudjs%2Fplayable-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoudjs%2Fplayable-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smoudjs","download_url":"https://codeload.github.com/smoudjs/playable-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245105527,"owners_count":20561540,"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-network","ads","applovin","dapi","facebook","google","html5","ironsource","mintegral","mraid","playable","playable-sdk","playablesdk","sdk","unity","vungle"],"created_at":"2025-03-23T13:21:20.213Z","updated_at":"2025-03-23T13:21:20.880Z","avatar_url":"https://github.com/smoudjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @smoud/playable-sdk\n\n[![npm version](https://img.shields.io/npm/v/@smoud/playable-sdk)](https://www.npmjs.com/package/@smoud/playable-sdk)\n[![npm downloads](https://badgen.net/npm/dw/@smoud/playable-sdk)](https://www.npmjs.com/package/@smoud/playable-sdk)\n[![build size](https://badgen.net/bundlephobia/min/@smoud/playable-sdk)](https://www.npmjs.com/package/@smoud/playable-sdk)\n[![DeepScan grade](https://deepscan.io/api/teams/19616/projects/29066/branches/935410/badge/grade.svg)](https://github.com/smoudjs/playable-sdk)\n[![License](https://img.shields.io/npm/l/@smoud/playable-sdk)](https://github.com/smoudjs/playable-sdk/blob/master/LICENSE)\n\nIt's powerful, unified SDK that seamlessly integrates multiple ad network SDKs, including MRAID, Google, Facebook, Vungle, and many more. Designed for effortless playable ad development, it provides a standardized interface, ensuring compatibility, optimization, and easy deployment across various platforms. With `@smoud/playable-sdk`, you can streamline your workflow, maximize reach, and focus on crafting engaging interactive ads without worrying about SDK fragmentation. 🚀\n\n## Features\n\n- 🌐 **Universal Compatibility**: Works with all major ad networks\n- 🔄 **Standardized Interface**: Single API for all supported networks\n- 📱 **Responsive Design**: Automatic handling of orientation and resize events\n- 🎮 **Game State Management**: Built-in pause/resume and lifecycle management\n- 🔊 **Audio Control**: Volume management across different networks\n- 📊 **Interaction Tracking**: Built-in user interaction monitoring\n- ⚡ **Lightweight**: No external dependencies\n\n## Supported Ad Networks\n\n### Ad Network supports\n\n- IronSource (MRAID/DAPI)\n- AppLovin\n- Unity Ads\n- Google Ads\n- Meta (Facebook)\n- Moloco\n- Mintegral\n- Vungle\n- TapJoy\n- Snapchat\n- TikTok\n- Appreciate\n- Pangle\n- Liftoff\n- Chartboost\n- AdColony\n- MyTarget\n\n### Protocol Support\n\nThe SDK automatically detects and adapts to the appropriate ad network protocol:\n\n- MRAID Protocol (v2/v3)\n- DAPI Protocol (Display Ad Protocol Interface)\n- Network-specific protocols (Facebook, Google, etc.)\n\n## Installation\n\n```bash\nnpm install @smoud/playable-sdk\n```\n\n## Quick Start\n\n```javascript\nimport { sdk } from '@smoud/playable-sdk';\n\n// Initialize the SDK as early as possible\nsdk.init((width, height) =\u003e {\n  // Initialize your game/app with container dimensions\n  new Game(width, height);\n});\n```\n\n```javascript\n// Listen for events\nsdk.on('resize', (width, height) =\u003e {\n  game.resize(width, height);\n});\n\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\nsdk.on('interaction', (count) =\u003e {\n  console.log(`User interaction count: ${count}`);\n});\n```\n\n```javascript\n// Start the playable when resources are loaded\nsdk.start();\n```\n\n```javascript\n// Mark playable as complete\nsdk.finish();\n\n// Handle install/download action\ninstallButton.onclick = () =\u003e sdk.install();\n```\n\n## Build\n\n### @smoud/playable-scripts\n\n`@smoud/playable-sdk` works best with the [`@smoud/playable-scripts`](https://www.npmjs.com/package/@smoud/playable-scripts) package, which helps you prepare **playable ad builds** that are ready for multiple ad networks. Using `playable-scripts` provides key benefits:\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### 🔧 Quick Start\n\n#### 1️⃣ Install `@smoud/playable-scripts`\n\nInstall the package in your project:\n\n```sh\nnpm i --save-dev @smoud/playable-scripts\n```\n\n#### 2️⃣ Update `package.json`\n\nModify your `package.json` file to include the following scripts:\n\n```json\n\"scripts\": {\n  \"dev\": \"playable-scripts dev\",\n  \"build\": \"playable-scripts build\"\n}\n```\n\n#### 3️⃣ Run the development server\n\nStart a local development server with live reloading:\n\n```sh\nnpm run dev\n```\n\n#### 4️⃣ Build for a specific ad network\n\nTo generate a playable ad ready for an ad network, use the build command:\n\n```sh\nnpm run build \u003cad-network\u003e\n```\n\nSupported **Ad Networks**:\n\n- `applovin`\n- `unity`\n- `google`\n- `ironsource`\n- `facebook`\n- `moloco`\n- `adcolony`\n- `mintegral`\n- `vungle`\n- `tapjoy`\n- `snapchat`\n- `tiktok`\n- `appreciate`\n- `chartboost`\n- `pangle`\n- `mytarget`\n- `liftoff`\n\nSee more details in [`GitHub repository.`](https://github.com/smoudjs/playable-scripts?tab=readme-ov-file#installation)\n\n### Custom Build Pipeline\n\nBefore setting up a custom pipeline, consider using `@smoud/playable-scripts`. It provides an API to extend the standard build function and simplifies the process. See more details [here](https://github.com/smoudjs/playable-scripts?tab=readme-ov-file#api-reference).\n\nIf you still prefer a fully custom build, you need to manage the following aspects yourself:\n\n#### 1️⃣ Define Required Variables\n\nYour build script should replace or define these variables within the `window` object before the rest of your code executes:\n\n```ts\nAD_NETWORK = 'applovin'; // Replace with your target network\nAD_PROTOCOL = 'mraid'; // Options: 'mraid', 'dapi', 'none'\nGOOGLE_PLAY_URL = 'https://play.google.com/store/apps/details?id=com.example';\nAPP_STORE_URL = 'https://apps.apple.com/app/id123456789';\nBUILD_HASH = 'random-build-hash';\n```\n\n#### 2️⃣ Applying Ad-Specific Adjustments\n\nCertain networks use different ad protocols. Ensure that your build includes or removes code based on the network.\n\nCheck [Ad Network Resources \u0026 Requirements](#Ad-Network-Resources-\u0026-Requirements) for more details.\n\n#### 3️⃣ Minification \u0026 Optimization\n\nTo ensure the best performance, your build should include a **JavaScript minimizer** to remove unnecessary code.\n\n##### Recommended Tools:\n\n- [Terser](https://github.com/terser/terser) – Best for JS minification.\n- [UglifyJS](https://github.com/mishoo/UglifyJS) – Alternative for JS compression.\n\n## SDK API Reference\n\n### Lifecycle management \u0026 typical usage\n\nThe SDK provides a comprehensive set of functions to manage the playable ad lifecycle. Functions should be called in the following order:\n\n1. **Initialization \u0026 Setup**\n\n   ```javascript\n   // Initialize SDK (required first call)\n   sdk.init((width, height) =\u003e {\n     // Setup your app with container dimensions\n   });\n   ```\n\n2. **Listen for needed events**\n\n   #### **RECOMMENDED** events For best user experience\n\n   ```javascript\n   sdk.on('resize', (width, height) =\u003e {\n     // Update game layout on container resize\n     game.updateLayout(width, height);\n     ui.repositionElements();\n   });\n\n   sdk.on('pause', () =\u003e {\n     // Pause gameplay when ad container loses focus\n     game.pauseGameplay();\n     ui.showPauseOverlay();\n   });\n\n   sdk.on('resume', () =\u003e {\n     // Resume gameplay when focus returns\n     game.resumeGameplay();\n     ui.hidePauseOverlay();\n   });\n\n   sdk.on('volume', (level) =\u003e {\n     // Adjust game audio when container volume changes\n     audio.setVolume(level);\n     ui.updateVolumeIndicator(level);\n\n     //   if (level === 0) audio.muteGlobal();\n     //   else audio.unMuteGlobal();\n   });\n\n   sdk.on('finish', () =\u003e {\n     // Show end screen when playable is marked complete\n     game.stopGameplay();\n     ui.showEndScreen();\n   });\n   ```\n\n   #### Optional events\n\n   ```javascript\n   sdk.on('init', () =\u003e {\n     // Show loading screen while SDK initializes\n     loadingScreen.show();\n   });\n\n   sdk.on('ready', () =\u003e {\n     // You should use either init callback function or this event to initialize your game\n     // They are performing just in the same condition, so avoid creating game instance duplication\n     new Game(sdk.maxWidth, sdk.maxHeight);\n   });\n\n   sdk.on('start', () =\u003e {\n     // Begin gameplay/animation when playable officially starts\n     game.startGameplay();\n     loadingScreen.hide();\n   });\n\n   sdk.on('interaction', (count) =\u003e {\n     // Track user engagement\n     analytics.logInteraction(count);\n     if (count \u003e= 3) {\n       // Show CTA after sufficient engagement\n       game.showCallToAction();\n     }\n   });\n\n   sdk.on('retry', () =\u003e {\n     // Reset game state for replay\n     game.reset();\n     ui.hideEndScreen();\n     game.startGameplay();\n   });\n\n   sdk.on('install', () =\u003e {\n     // Track conversion when install/store action triggered\n     analytics.logConversion();\n   });\n   ```\n\n3. **Mark all resources are preloaded and gameplay is started**\n\n   ```javascript\n   // Start playable after resources are loaded\n   sdk.start();\n   ```\n\n4. **Completion \u0026 Installation**\n\n   ```javascript\n   // Mark playable as complete\n   sdk.finish();\n   ```\n\n   ```javascript\n   // Trigger install/store redirect\n   sdk.install();\n   ```\n\n### Event System\n\nEvents are emitted throughout the playable lifecycle and can be handled using:\n\n```javascript\n// Regular event listener\nsdk.on('eventName', callback, [context]);\n\n// One-time event listener\nsdk.once('eventName', callback, [context]);\n\n// Remove listener(s)\nsdk.off('eventName', [callback], [context]);\n```\n\n#### Available Events\n\n| Event         | Parameters      | Description                                | Typical Usage            |\n| ------------- | --------------- | ------------------------------------------ | ------------------------ |\n| `init`        | -               | SDK initialization started                 | Setup loading screen     |\n| `boot`        | -               | Ad container is ready `pre` init callback  | Initialize core systems  |\n| `ready`       | -               | Ad container is ready `post` init callback | Start resource loading   |\n| `start`       | -               | Playable experience started                | Begin gameplay/animation |\n| `interaction` | `count`         | User interaction occurred                  | Track engagement         |\n| `resize`      | `width, height` | Container size changed                     | Update layout            |\n| `pause`       | -               | Playable entered pause state               | Pause gameplay           |\n| `resume`      | -               | Playable resumed from pause                | Resume gameplay          |\n| `volume`      | `level`         | Volume level changed (0-1)                 | Adjust audio             |\n| `retry`       | -               | Retry/restart triggered                    | Reset game state         |\n| `finish`      | -               | Playable marked as complete                | Show end screen          |\n| `install`     | -               | Install action triggered                   | Track conversion         |\n\n### Properties\n\n| Property           | Type    | Description                                            |\n| ------------------ | ------- | ------------------------------------------------------ |\n| `sdk.version`      | string  | Current SDK version                                    |\n| `sdk.maxWidth`     | number  | Container width in pixels                              |\n| `sdk.maxHeight`    | number  | Container height in pixels                             |\n| `sdk.isLandscape`  | boolean | Current device orientation state                       |\n| `sdk.isReady`      | boolean | Ad container ready state                               |\n| `sdk.isStarted`    | boolean | All resources are loaded and playable started state    |\n| `sdk.isPaused`     | boolean | Current pause state                                    |\n| `sdk.isFinished`   | boolean | Completion state                                       |\n| `sdk.volume`       | number  | Default volume level (0-1), when muting/unmuting audio |\n| `sdk.interactions` | number  | User interaction count                                 |\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## References\n\n### Ad Network Resources \u0026 Requirements\n\n#### MRAID Networks\n\n- [MRAID 3.0](https://www.iab.com/wp-content/uploads/2017/07/MRAID_3.0_FINAL.pdf)\n- [IronSource - MRAID requirements](https://developers.is.com/ironsource-mobile/general/mraid-requirements/#step-1)\n- [IronSource - Interactive ad creative requirements](https://developers.is.com/ironsource-mobile/general/interactive-requirements/#step-1)\n- [Unity Ads Documentation](https://docs.unity.com/acquire/en-us/manual/playable-ads-specifications)\n- [Chartboost Integration](https://docs.chartboost.com/en/advertising/creatives/creative-assets/)\n\n#### Proprietary Networks\n\n- [Google HTML5 / Playable Ads](https://support.google.com/google-ads/answer/9981650?hl=en)\n- [Meta (Facebook) Playable Ads](https://www.facebook.com/business/help/412951382532338)\n- [Mintegral Integration](https://www.playturbo.com/review/doc)\n\n### Testing Tools\n\n#### Network Testing Tools\n\n- Applovin Playable [Web](https://p.applov.in/playablePreview?create=1\u0026;qr=1) / [iOS](https://install.appcenter.ms/orgs/iosdeveloper-dbmy/apps/ios-playable-preview/distribution_groups/all-users-of-ios-playable-preview) / [Android](https://install.appcenter.ms/orgs/iosdeveloper-dbmy/apps/android-playable-preview/distribution_groups/all-users-of-android-playable-preview)\n- Unity Ad Testing [iOS](https://apps.apple.com/us/app/ad-testing/id1463016906) / [Android](https://play.google.com/store/apps/details?id=com.unity3d.auicreativetestapp)\n- [Vungle Creative QA](https://vungle.com/creative-verifier/)\n- [Facebook Playable Preview Tool](https://developers.facebook.com/tools/playable-preview/)\n- [Google HTML5 Validator](https://h5validator.appspot.com/adwords/asset)\n- [IronSource Integration Validation](https://developers.is.com/ironsource-mobile/general/test-suite/)\n- [Mintegral Testing Tool](https://www.playturbo.com/review)\n\n## Issues\n\nReport issues at [GitHub Issues](https://github.com/smoudjs/playable-sdk/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmoudjs%2Fplayable-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmoudjs%2Fplayable-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmoudjs%2Fplayable-sdk/lists"}