@smoud/playable-sdk
Version:
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.
177 lines (174 loc) • 6.06 kB
text/typescript
type EventName = 'init' | 'boot' | 'ready' | 'start' | 'interaction' | 'resize' | 'pause' | 'resume' | 'volume' | 'retry' | 'finish' | 'install';
type InitCallbackType = (maxWidth: number, maxHeight: number) => void;
/**
* Main SDK class providing playable ad functionality and state management.
* Handles initialization, lifecycle events, and interactions across different ad networks.
*/
declare class sdk {
/** Current version of the SDK */
static version: string;
/** Current maximum width of the playable ad container in pixels */
static maxWidth: number;
/** Current maximum height of the playable ad container in pixels */
static maxHeight: number;
/** Indicates if the current orientation is landscape (width > height) */
static isLandscape: boolean;
/** Indicates if the Ad Network is ready and playable ad can be initialized */
static isReady: boolean;
/** Indicates if all playable ad resources are loaded and gameplay has started */
static isStarted: boolean;
/** Indicates if the playable ad is currently paused */
static isPaused: boolean;
/** Indicates if the playable ad has finished */
static isFinished: boolean;
/** Current volume level (0-1) */
static volume: number;
/** Number of user interactions with the playable ad */
static interactions: number;
/**
* Initializes the SDK and sets up protocol-specific handlers.
* This must be called as earlier as possible.
*
* @param callback Optional function called when ad container is ready
* @example
* // Basic initialization
* sdk.init();
*
* // Initialization with callback
* sdk.init((width, height) => {
* new App(width, height)
* });
*
* @fires init When initialization starts
* @fires boot When the ad begins booting
* @fires ready When Ad Network is ready and playable ad can be initialized
*/
static init(callback?: InitCallbackType): void;
/**
* Starts the playable ad experience.
* Should be called after all resources are loaded and first frame is rendered.
*
* @example
* // Call just after all resources are preloaded and first frame is rendered
* sdk.start();
*
* @fires start When the playable ad starts
* @fires resize When the ad container is initially sized
*/
static start(): void;
/**
* Marks the playable ad as finished.
* This triggers network-specific completion handlers.
*
* @example
* // Call when game/experience is complete
* sdk.finish();
*
* @fires finish When the playable ad is marked as finished
*/
static finish(): void;
/**
* Triggers a retry/restart of the playable ad.
* Behavior varies by ad network.
*
* @example
* // Allow user to try again
* retryButton.onclick = () => sdk.retry();
*
* @fires retry When a retry is triggered
*/
static retry(): void;
/**
* Triggers the install/download action for the advertised app.
* Handles different store opening methods across ad networks.
*
* @example
* // Call when user wants to install
* installButton.onclick = () => sdk.install();
*
* @fires finish If the ad hasn't been marked as finished
* @fires install When the install action is triggered
*/
static install(): void;
/**
* Trigger force resize event
* Useful when container size changes need to be manually propagated.
*
* @example
* sdk.resize();
*
* @fires resize With current maxWidth and maxHeight
*/
static resize(): void;
/**
* Forces the playable ad into a paused state.
*
* @example
* // Pause the experience
* pauseButton.onclick = () => sdk.pause();
*
* @fires pause When the ad enters paused state
*/
static pause(): void;
/**
* Resumes the playable ad from a forced pause state.
* Only works if the ad was paused via sdk.pause().
*
* @example
* // Resume from pause
* resumeButton.onclick = () => sdk.resume();
*
* @fires resume When the ad resumes from pause
*/
static resume(): void;
/**
* Registers an event listener.
*
* @param event Name of the event to listen for
* @param fn Callback function to execute when event occurs
* @param context Optional 'this' context for the callback
*
* @example
* // Listen for user interactions
* sdk.on('interaction', (count) => {
* console.log(`User interaction #${count}`);
* });
*
* // Listen for resize with context
* sdk.on('resize', function(width, height) {
* this.updateLayout(width, height);
* }, gameInstance);
*/
static on(event: EventName, fn: Function, context?: any): void;
/**
* Registers a one-time event listener that removes itself after execution.
*
* @param event Name of the event to listen for
* @param fn Callback function to execute when event occurs
* @param context Optional 'this' context for the callback
*
* @example
* // Listen for first interaction only
* sdk.once('interaction', () => {
* console.log('First user interaction occurred!');
* });
*/
static once(event: EventName, fn: Function, context?: any): void;
/**
* Removes an event listener.
*
* @param event Name of the event to stop listening for
* @param fn Optional callback function to remove (if not provided, removes all listeners for the event)
* @param context Optional 'this' context to match when removing
*
* @example
* // Remove specific listener
* const handler = () => console.log('Interaction');
* sdk.off('interaction', handler);
*
* // Remove all listeners for an event
* sdk.off('interaction');
*/
static off(event: EventName, fn?: Function, context?: any): void;
}
export { sdk as default, sdk };