@ad-execute-manager/ad-interstitial

Interstitial ad-related classes including InterstitialAdFather and InterstitialAdNovel for ad management.

Installation

npm install @ad-execute-manager/ad-interstitial

Features

• InterstitialAdFather: Base class for interstitial ads with common functionality
• InterstitialAdNovel: Novel-specific interstitial ad implementation with enhanced features
• AdExecuteManager: Core ad execution management from @ad-execute-manager/core
• TypeScript Support: Includes TypeScript type definitions
• Event Callbacks: Comprehensive event callback system for ad lifecycle events
• Error Handling: Built-in error handling and retry mechanisms
• Scene Support: Scene-based ad configuration for different contexts

Usage

InterstitialAdNovel

import { InterstitialAdNovel } from '@ad-execute-manager/ad-interstitial';

const interstitialAd = InterstitialAdNovel.new({
  sign: 'novel_interstitial',
  preserveOnEnd: false,
  needEndOnTimeout: true,
  collection: {
    onHalfway: (args) => {
      console.log('Ad halfway:', args);
    },
    onShow: (args) => {
      console.log('Ad shown:', args);
    },
    onFinish: (args) => {
      console.log('Ad finished:', args);
    },
    onAlways: (args) => {
      console.log('Ad always:', args);
    },
    onError: (error) => {
      console.error('Ad error:', error);
    }
  }
});

// Initialize ad
interstitialAd.initialize({
  adUnitId: 'your-ad-unit-id',
  retry: 3
});

// Show ad
const result = await interstitialAd.addExecuteManager({
  options: {
    scene: 1
  }
});

console.log('Ad result:', result);

Basic Interstitial Ad Usage

import { InterstitialAdNovel } from '@ad-execute-manager/ad-interstitial';

// Create ad instance
const interstitialAd = InterstitialAdNovel.new({
  sign: 'chapter_end_interstitial',
  preserveOnEnd: false,
  needEndOnTimeout: true,
  collection: {
    onFinish: () => {
      console.log('Interstitial ad finished, proceeding to next chapter');
      // Proceed to next chapter logic here
    },
    onError: (error) => {
      console.error('Interstitial ad error:', error);
      // Handle error gracefully, maybe skip ad
    }
  }
});

// Initialize and show ad
interstitialAd.initialize({ adUnitId: 'ca-app-pub-xxx/xxx', retry: 2 });

// Show ad at chapter end
async function showAdAtChapterEnd() {
  try {
    const result = await interstitialAd.addExecuteManager({ options: { scene: 1 } });
    console.log('Ad result:', result);
  } catch (error) {
    console.error('Ad execution error:', error);
  }
}

// Usage
// showAdAtChapterEnd();

Ad Instance Management

import { InterstitialAdNovel } from '@ad-execute-manager/ad-interstitial';

// Create ad instance
const interstitialAd = InterstitialAdNovel.new({ sign: 'interstitial' });

// Initialize ad
interstitialAd.initialize({ adUnitId: 'ca-app-pub-xxx/xxx', retry: 2 });

// Function to show ad based on user action
async function showAdBasedOnAction(action) {
  try {
    switch (action) {
      case 'chapter_end':
        return await interstitialAd.addExecuteManager({ options: { scene: 1 } });
      case 'app_start':
        return await interstitialAd.addExecuteManager({ options: { scene: 2 } });
      case 'level_complete':
        return await interstitialAd.addExecuteManager({ options: { scene: 3 } });
      default:
        throw new Error('Invalid ad action');
    }
  } catch (error) {
    console.error('Ad error:', error);
    return { success: false, error: error.message };
  }
}

// Usage examples
// showAdBasedOnAction('chapter_end');
// showAdBasedOnAction('app_start');
// showAdBasedOnAction('level_complete');

API

InterstitialAdFather

Base class for interstitial ads with common functionality.

InterstitialAdNovel

class InterstitialAdNovel extends InterstitialAdFather {
  /**
   * Builds and returns an instance of InterstitialAdNovel
   * @param args Construction arguments
   * @returns Instance of InterstitialAdNovel
   */
  static build(args: IConstructArgs): InterstitialAdNovel;
  
  /**
   * Gets the singleton instance of InterstitialAdNovel
   * @returns Singleton instance of InterstitialAdNovel
   */
  static getInstance(): InterstitialAdNovel;
  
  /**
   * Creates a new instance of InterstitialAdNovel
   * @param args Construction arguments
   * @returns New instance of InterstitialAdNovel
   */
  static new(args: IConstructArgs): InterstitialAdNovel;
  
  /**
   * Initializes the ad with configuration
   * @param params Ad configuration parameters
   * @param callback Optional callback function
   * @returns Current instance for method chaining
   */
  initialize(params: IRewordAdConfig, callback?: (v: IRewardedVideoAd) => void): this;
  
  /**
   * Adds execute manager and runs the ad
   * @param ctx Context object with options
   * @returns Promise with ad execution result
   */
  addExecuteManager(ctx: any): Promise<any>;
  
  /**
   * Clears the ad instance
   */
  clear(): void;
  
  /**
   * Shifts the ad instance
   */
  shift(): void;
}

Configuration

Construction Arguments

When creating an ad instance, you can pass the following configuration options:

• sign: Unique identifier for the ad instance
• preserveOnEnd: Whether to preserve the instance after ad ends
• needEndOnTimeout: Whether to end the ad on timeout
• collection: Event collection object with callback functions
  • onHalfway: Called when ad reaches halfway point
  • onShow: Called when ad is shown
  • onFinish: Called when ad finishes
  • onAlways: Called always after ad operation
  • onError: Called when ad encounters error

Initialize Parameters

When initializing an ad, you can pass the following parameters:

• adUnitId: Unique identifier for the ad unit
• retry: Number of retry attempts on ad error

Examples

Example 1: Chapter End Interstitial Ad

import { InterstitialAdNovel } from '@ad-execute-manager/ad-interstitial';

// Create ad instance for chapter end
const chapterEndAd = InterstitialAdNovel.new({
  sign: 'chapter_end_interstitial',
  preserveOnEnd: false,
  needEndOnTimeout: true,
  collection: {
    onShow: () => {
      console.log('Chapter end interstitial ad shown');
      // Track ad show event
    },
    onFinish: () => {
      console.log('Chapter end interstitial ad finished');
      // Proceed to next chapter
      nextChapter();
    },
    onError: (error) => {
      console.error('Chapter end interstitial ad error:', error);
      // Skip ad and proceed
      nextChapter();
    }
  }
});

// Initialize ad
chapterEndAd.initialize({ 
  adUnitId: 'your-ad-unit-id', 
  retry: 2 
});

// Function to proceed to next chapter
function nextChapter() {
  console.log('Proceeding to next chapter...');
  // Next chapter logic here
}

// Show ad when chapter ends
async function showChapterEndAd() {
  console.log('Showing chapter end interstitial ad...');
  try {
    await chapterEndAd.addExecuteManager({ 
      options: { 
        scene: 1 // Chapter end scene
      } 
    });
  } catch (error) {
    console.error('Error showing chapter end ad:', error);
    nextChapter();
  }
}

Example 2: App Start Interstitial Ad

import { InterstitialAdNovel } from '@ad-execute-manager/ad-interstitial';

// Create ad instance for app start
const appStartAd = InterstitialAdNovel.new({
  sign: 'app_start_interstitial',
  preserveOnEnd: true,
  needEndOnTimeout: true,
  collection: {
    onShow: () => {
      console.log('App start interstitial ad shown');
      // Track app start ad event
    },
    onFinish: () => {
      console.log('App start interstitial ad finished');
      // Continue app initialization
      continueAppInit();
    },
    onError: (error) => {
      console.error('App start interstitial ad error:', error);
      // Continue app initialization despite error
      continueAppInit();
    }
  }
});

// Initialize ad
appStartAd.initialize({ 
  adUnitId: 'your-ad-unit-id', 
  retry: 1 
});

// Function to continue app initialization
function continueAppInit() {
  console.log('Continuing app initialization...');
  // App initialization logic here
}

// Show ad on app start
async function showAppStartAd() {
  console.log('Showing app start interstitial ad...');
  try {
    await appStartAd.addExecuteManager({ 
      options: { 
        scene: 2 // App start scene
      } 
    });
  } catch (error) {
    console.error('Error showing app start ad:', error);
    continueAppInit();
  }
}

Example 3: Level Complete Interstitial Ad

import { InterstitialAdNovel } from '@ad-execute-manager/ad-interstitial';

// Create ad instance for level complete
const levelCompleteAd = InterstitialAdNovel.new({
  sign: 'level_complete_interstitial',
  preserveOnEnd: false,
  needEndOnTimeout: true,
  collection: {
    onShow: () => {
      console.log('Level complete interstitial ad shown');
      // Track level complete ad event
    },
    onFinish: () => {
      console.log('Level complete interstitial ad finished');
      // Show level complete screen
      showLevelCompleteScreen();
    },
    onError: (error) => {
      console.error('Level complete interstitial ad error:', error);
      // Show level complete screen despite error
      showLevelCompleteScreen();
    }
  }
});

// Initialize ad
levelCompleteAd.initialize({ 
  adUnitId: 'your-ad-unit-id', 
  retry: 2 
});

// Function to show level complete screen
function showLevelCompleteScreen() {
  console.log('Showing level complete screen...');
  // Level complete screen logic here
}

// Show ad when level completes
async function showLevelCompleteAd() {
  console.log('Showing level complete interstitial ad...');
  try {
    await levelCompleteAd.addExecuteManager({ 
      options: { 
        scene: 3 // Level complete scene
      } 
    });
  } catch (error) {
    console.error('Error showing level complete ad:', error);
    showLevelCompleteScreen();
  }
}

Dependencies

• @ad-execute-manager/core: Core ad execution management
• @ad-execute-manager/logger: Logging utility
• @ad-execute-manager/serializable-error: Serializable error implementation

License

MIT