It's unified Playable SDK that supports MRAID, Google, Facebook, Vungle, and many more Ad Networks, simplifying playable ad development with a standardized interface for seamless cross-network compatibility.
npm install @smoud/playable-sdk@smoud/playable-sdk, you can streamline your workflow, maximize reach, and focus on crafting engaging interactive ads without worrying about SDK fragmentation. 🚀
bash
npm install @smoud/playable-sdk
`
Quick Start
`javascript
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);
});
`
`javascript
// 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});
});
`
`javascript
// Start the playable when resources are loaded
sdk.start();
`
`javascript
// Mark playable as complete
sdk.finish();
// Handle install/download action
installButton.onclick = () => sdk.install();
`
Build
$3
@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.
$3
#### 1️⃣ Install @smoud/playable-scripts
Install the package in your project:
`sh
npm i --save-dev @smoud/playable-scripts
`
#### 2️⃣ Update package.json
Modify your package.json file to include the following scripts:
`json
"scripts": {
"dev": "playable-scripts dev",
"build": "playable-scripts build"
}
`
#### 3️⃣ Run the development server
Start a local development server with live reloading:
`sh
npm run dev
`
#### 4️⃣ Build for a specific ad network
To generate a playable ad ready for an ad network, use the build command:
`sh
npm run build
`
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.
$3
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:
`ts
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
$3
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
`javascript
// 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
`javascript
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
`javascript
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
`javascript
// Start playable after resources are loaded
sdk.start();
`
4. Completion & Installation
`javascript
// Mark playable as complete
sdk.finish();
`
`javascript
// Trigger install/store redirect
sdk.install();
`
$3
Events are emitted throughout the playable lifecycle and can be handled using:
`javascript
// 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 |
$3
| 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 |