1.0.19 • Published 3 months ago

@smoud/playable-sdk v1.0.19

Weekly downloads
-
License
MIT
Repository
github
Last release
3 months ago

@smoud/playable-sdk

npm version npm downloads build size DeepScan grade License

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

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

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

EventParametersDescriptionTypical Usage
init-DOM Content loaded and SDK initialization startedSetup loading screen
boot-Ad container is ready pre init callbackInitialize core systems
ready-Ad container is ready post init callbackStart resource loading
start-Playable experience startedBegin gameplay/animation
interactioncountUser interaction occurredTrack engagement
resizewidth, heightContainer size changedUpdate layout
pause-Playable entered pause statePause gameplay
resume-Playable resumed from pauseResume gameplay
volumelevelVolume level changed (0-1)Adjust audio
retry-Retry/restart triggeredReset game state
finish-Playable marked as completeShow end screen
install-Install action triggeredTrack conversion

Properties

PropertyTypeDescription
sdk.versionstringCurrent SDK version
sdk.maxWidthnumberContainer width in pixels
sdk.maxHeightnumberContainer height in pixels
sdk.isLandscapebooleanCurrent device orientation state
sdk.isReadybooleanAd container ready state
sdk.isStartedbooleanAll resources are loaded and playable started state
sdk.isPausedbooleanCurrent pause state
sdk.isFinishedbooleanCompletion state
sdk.volumenumberDefault volume level (0-1), when muting/unmuting audio
sdk.interactionsnumberUser interaction count

Demo Projects

Get started quickly with our template projects:

References

Ad Network Resources & Requirements

MRAID Networks

Proprietary Networks

Testing Tools

Network Testing Tools

Issues

Report issues at GitHub Issues