@ad-execute-manager/ad

Ad-related classes including InterstitialAdFather, InterstitialAdNovel, RewardAdFather, and RewardAdNovel for ad management.

Installation

npm install @ad-execute-manager/ad

Features

• InterstitialAdFather: Base class for interstitial ads with common functionality
• InterstitialAdNovel: Novel-specific interstitial ad implementation with enhanced features
• RewardAdFather: Base class for reward ads with common functionality
• RewardAdNovel: Novel-specific reward ad implementation with enhanced features

Usage

InterstitialAdNovel

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

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);

RewardAdNovel

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

const rewardAd = RewardAdNovel.new({
  sign: 'novel_reward',
  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
rewardAd.initialize({
  adUnitId: 'your-ad-unit-id',
  retry: 3
});

// Show ad
const result = await rewardAd.addExecuteManager({
  options: {
    scene: 2,
    timeout: 10000
  }
});

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

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;
}

RewardAdFather

Base class for reward ads with common functionality.

RewardAdNovel

class RewardAdNovel extends RewardAdFather {
  /**
   * Builds and returns an instance of RewardAdNovel
   * @param args Construction arguments
   * @returns Instance of RewardAdNovel
   */
  static build(args: IConstructArgs): RewardAdNovel;
  
  /**
   * Gets the singleton instance of RewardAdNovel
   * @returns Singleton instance of RewardAdNovel
   */
  static getInstance(): RewardAdNovel;
  
  /**
   * Creates a new instance of RewardAdNovel
   * @param args Construction arguments
   * @returns New instance of RewardAdNovel
   */
  static new(args: IConstructArgs): RewardAdNovel;
  
  /**
   * 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: Basic Interstitial Ad Usage

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

// 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();

Example 2: Reward Ad for Premium Content

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

// Create reward ad instance
const rewardAd = RewardAdNovel.new({
  sign: 'premium_content_reward',
  preserveOnEnd: true,
  needEndOnTimeout: true,
  collection: {
    onFinish: (args) => {
      console.log('Reward ad finished, unlocking premium content');
      // Unlock premium content logic here
      unlockPremiumContent();
    },
    onError: (error) => {
      console.error('Reward ad error:', error);
      // Show error message to user
      showErrorMessage('Failed to load ad. Please try again later.');
    }
  }
});

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

// Function to unlock premium content
function unlockPremiumContent() {
  // Logic to unlock premium content
  console.log('Premium content unlocked!');
}

// Function to show error message
function showErrorMessage(message) {
  // Logic to show error message
  console.log('Error:', message);
}

// Show reward ad to unlock premium content
async function showRewardAdForPremium() {
  try {
    const result = await rewardAd.addExecuteManager({ 
      options: { 
        scene: 2, 
        timeout: 15000 
      } 
    });
    console.log('Reward ad result:', result);
  } catch (error) {
    console.error('Reward ad execution error:', error);
  }
}

// Usage
// showRewardAdForPremium();

Example 3: Ad Instance Management

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

// Create ad instances
const interstitialAd = InterstitialAdNovel.new({ sign: 'interstitial' });
const rewardAd = RewardAdNovel.new({ sign: 'reward' });

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

// Function to show appropriate ad based on user action
async function showAdBasedOnAction(action) {
  try {
    switch (action) {
      case 'chapter_end':
        return await interstitialAd.addExecuteManager({ options: { scene: 1 } });
      case 'unlock_premium':
        return await rewardAd.addExecuteManager({ options: { scene: 2 } });
      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('unlock_premium');

License

MIT