@smoud/playable-sdk

It'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. 🚀

Features

• 🌐 Universal Compatibility: Works with all major ad networks
• 🔄 Standardized Interface: Single API for all supported networks
• 📱 Responsive Design: Automatic handling of orientation and resize events
• 🎮 Game State Management: Built-in pause/resume and lifecycle management
• 🔊 Audio Control: Volume management across different networks
• 📊 Interaction Tracking: Built-in user interaction monitoring
• ⚡ Lightweight: No external dependencies

Supported Ad Networks

Ad Network supports

• IronSource (MRAID/DAPI)
• AppLovin
• Unity Ads
• Google Ads
• Meta (Facebook)
• Moloco
• Mintegral
• Vungle
• TapJoy
• Snapchat
• TikTok
• Appreciate
• Pangle
• Liftoff
• Chartboost
• AdColony
• MyTarget
• Smadex
• Adikteev
• Bigabid
• inMobi

Protocol Support

The SDK automatically detects and adapts to the appropriate ad network protocol:

• MRAID Protocol (v2/v3)
• DAPI Protocol (Display Ad Protocol Interface)
• Network-specific protocols (Facebook, Google, etc.)

Installation

npm install @smoud/playable-sdk

Quick Start

import { sdk } from '@smoud/playable-sdk';

// Initialize the SDK as early as possible
sdk.init((width, height) => {
  // Initialize your game/app with container dimensions
  new Game(width, height);
});

// Listen for events
sdk.on('resize', (width, height) => {
  game.resize(width, height);
});

sdk.on('pause', game.pause, game);
sdk.on('resume', game.resume, game);
sdk.on('volume', game.volume, game);
sdk.on('finish', game.finish, game);

sdk.on('interaction', (count) => {
  console.log(`User interaction count: ${count}`);
});

// Start the playable when resources are loaded
sdk.start();

// Mark playable as complete
sdk.finish();

// Handle install/download action
installButton.onclick = () => sdk.install();

Build

@smoud/playable-scripts

@smoud/playable-sdk works best with the @smoud/playable-scripts package, which helps you prepare playable ad builds that are ready for multiple ad networks. Using playable-scripts provides key benefits:

• 🚀 One-Command Build Process – Easily generate builds for different ad networks.
• ⚡ Automatic Optimizations – Includes minification, tree-shaking, and dead code elimination.
• 🎯 Pre-configured for Major Ad Networks – Works out of the box with Google Ads, Meta (Facebook), AppLovin, Unity, IronSource, Vungle, Mintegral, and many more.
• 🛠️ Customizable – Extend the default build pipeline as needed.

🔧 Quick Start

1️⃣ Install @smoud/playable-scripts

Install the package in your project:

npm i --save-dev @smoud/playable-scripts

2️⃣ Update package.json

Modify your package.json file to include the following scripts:

"scripts": {
  "dev": "playable-scripts dev",
  "build": "playable-scripts build"
}

3️⃣ Run the development server

Start a local development server with live reloading:

npm run dev

4️⃣ Build for a specific ad network

To generate a playable ad ready for an ad network, use the build command:

npm run build <ad-network>

Supported Ad Networks:

• applovin
• unity
• google
• ironsource
• facebook
• moloco
• adcolony
• mintegral
• vungle
• tapjoy
• snapchat
• tiktok
• appreciate
• chartboost
• pangle
• mytarget
• liftoff
• smadex
• adikteev
• bigabid
• inmobi

See more details in GitHub repository.

Custom Build Pipeline

Before 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.

If you still prefer a fully custom build, you need to manage the following aspects yourself:

1️⃣ Define Required Variables

Your build script should replace or define these variables within the window object before the rest of your code executes:

AD_NETWORK = 'applovin'; // Replace with your target network
AD_PROTOCOL = 'mraid'; // Options: 'mraid', 'dapi', 'none'
GOOGLE_PLAY_URL = 'https://play.google.com/store/apps/details?id=com.example';
APP_STORE_URL = 'https://apps.apple.com/app/id123456789';
BUILD_HASH = 'random-build-hash';

2️⃣ Applying Ad-Specific Adjustments

Certain networks use different ad protocols. Ensure that your build includes or removes code based on the network.

Check Ad Network Resources & Requirements for more details.

3️⃣ Minification & Optimization

To ensure the best performance, your build should include a JavaScript minimizer to remove unnecessary code.

Recommended Tools:

• Terser – Best for JS minification.
• UglifyJS – Alternative for JS compression.

SDK API Reference

Lifecycle management & typical usage

The SDK provides a comprehensive set of functions to manage the playable ad lifecycle. Functions should be called in the following order:

1. Initialization & Setup

   // Initialize SDK (required first call)
   sdk.init((width, height) => {
     // Setup your app with container dimensions
   });

2. Listen for needed events

   RECOMMENDED events For best user experience

   sdk.on('resize', (width, height) => {
     // Update game layout on container resize
     game.updateLayout(width, height);
     ui.repositionElements();
   });
   
   sdk.on('pause', () => {
     // Pause gameplay when ad container loses focus
     game.pauseGameplay();
     ui.showPauseOverlay();
   });
   
   sdk.on('resume', () => {
     // Resume gameplay when focus returns
     game.resumeGameplay();
     ui.hidePauseOverlay();
   });
   
   sdk.on('volume', (level) => {
     // Adjust game audio when container volume changes
     audio.setVolume(level);
     ui.updateVolumeIndicator(level);
   
     //   if (level === 0) audio.muteGlobal();
     //   else audio.unMuteGlobal();
   });
   
   sdk.on('finish', () => {
     // Show end screen when playable is marked complete
     game.stopGameplay();
     ui.showEndScreen();
   });

   Optional events

   sdk.on('init', () => {
     // Show loading screen while SDK initializes
     loadingScreen.show();
   });
   
   sdk.on('ready', () => {
     // You should use either init callback function or this event to initialize your game
     // They are performing just in the same condition, so avoid creating game instance duplication
     new Game(sdk.maxWidth, sdk.maxHeight);
   });
   
   sdk.on('start', () => {
     // Begin gameplay/animation when playable officially starts
     game.startGameplay();
     loadingScreen.hide();
   });
   
   sdk.on('interaction', (count) => {
     // Track user engagement
     analytics.logInteraction(count);
     if (count >= 3) {
       // Show CTA after sufficient engagement
       game.showCallToAction();
     }
   });
   
   sdk.on('retry', () => {
     // Reset game state for replay
     game.reset();
     ui.hideEndScreen();
     game.startGameplay();
   });
   
   sdk.on('install', () => {
     // Track conversion when install/store action triggered
     analytics.logConversion();
   });

3. Mark all resources are preloaded and gameplay is started

   // Start playable after resources are loaded
   sdk.start();

4. Completion & Installation

   // Mark playable as complete
   sdk.finish();

   // Trigger install/store redirect
   sdk.install();

Event System

Events are emitted throughout the playable lifecycle and can be handled using:

// Regular event listener
sdk.on('eventName', callback, [context]);

// One-time event listener
sdk.once('eventName', callback, [context]);

// Remove listener(s)
sdk.off('eventName', [callback], [context]);

Available Events

| Event | Parameters | Description | Typical Usage | | ------------- | --------------- | ------------------------------------------------- | ------------------------ | | init | - | DOM Content loaded and SDK initialization started | Setup loading screen | | boot | - | Ad container is ready pre init callback | Initialize core systems | | ready | - | Ad container is ready post init callback | Start resource loading | | start | - | Playable experience started | Begin gameplay/animation | | interaction | count | User interaction occurred | Track engagement | | resize | width, height | Container size changed | Update layout | | pause | - | Playable entered pause state | Pause gameplay | | resume | - | Playable resumed from pause | Resume gameplay | | volume | level | Volume level changed (0-1) | Adjust audio | | retry | - | Retry/restart triggered | Reset game state | | finish | - | Playable marked as complete | Show end screen | | install | - | Install action triggered | Track conversion |

Properties

| Property | Type | Description | | ------------------ | ------- | ------------------------------------------------------ | | sdk.version | string | Current SDK version | | sdk.maxWidth | number | Container width in pixels | | sdk.maxHeight | number | Container height in pixels | | sdk.isLandscape | boolean | Current device orientation state | | sdk.isReady | boolean | Ad container ready state | | sdk.isStarted | boolean | All resources are loaded and playable started state | | sdk.isPaused | boolean | Current pause state | | sdk.isFinished | boolean | Completion state | | sdk.volume | number | Default volume level (0-1), when muting/unmuting audio | | sdk.interactions | number | User interaction count |

Demo Projects

Get started quickly with our template projects:

• playable-template-base - Clean TypeScript starter with minimal dependencies
• playable-template-base-js - Clean JavaScript starter with minimal dependencies
• playable-template-pixi - PixiJS template for 2D playable ads
• playable-template-three - Three.js template for 3D playable ads
• playable-template-phaser - Phaser template for 2D playable ads

References

Ad Network Resources & Requirements

MRAID Networks

• MRAID 3.0
• IronSource - Interactive ad creative requirements
• IronSource - MRAID requirements
• IronSource - DAPI requirements
• Unity Ads Documentation
• Chartboost Integration
• Adikteev specifications for external creatives

Proprietary Networks

• Google HTML5 / Playable Ads
• Meta (Facebook) Playable Ads
• Moloco Requirements
• Mintegral Integration

Testing Tools

Network Testing Tools

• Applovin Playable Web / iOS / Android
• Unity Ad Testing iOS / Android
• Vungle Creative QA
• Facebook Playable Preview Tool
• Google HTML5 Validator
• IronSource - Submit an HTML asset for review
• Mintegral Testing Tool

Issues

Report issues at GitHub Issues