@ad-execute-manager/tools

A collection of utility tools for ad execution management including LovelUnlockManager, RewardAdSceneTriggerManager, and RewardAdGlobalRecorder.

Installation

npm install @ad-execute-manager/tools

Features

• LovelUnlockManager: A manager for handling novel chapter unlocking logic with threshold-based unlocking
• RewardAdSceneTriggerManager: A manager for tracking and managing ad trigger scenes
• RewardAdGlobalRecorder: A global recorder for tracking ad execution statistics

Usage

LovelUnlockManager

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

// Create unlock manager instance
const unlockManager = LovelUnlockManager.new({
  sign: 'reader',
  unlockChapterThreshold: 2000,
  unlockChapterNum: 30,
  unlockChapterWaterLevel: 15
});

// Set drama detail data
unlockManager.drama = [
  { episodeId: 'chapter1', flagTag: 1, albumId: 'Chapter 1' },
  { episodeId: 'chapter2', flagTag: 0, albumId: 'Chapter 2' }
];

// Check if ready to unlock
unlockManager.ready(
  () => console.log('Not reached threshold'),
  (ids) => console.log('Unlocked chapters:', ids),
  'chapter1'
);

// Update reading progress
unlockManager.onProcessUpdate(
  { chapterId: 'chapter1', percent: 50 },
  (ids) => console.log('Unlocked chapters:', ids)
);

// Handle chapter change
unlockManager.onChapterChange(
  { currentChapterId: 'chapter1', nextChapterId: 'chapter2' },
  (ids) => console.log('Unlocked chapters:', ids)
);

// Unlock all chapters
unlockManager.unlockAll();

RewardAdSceneTriggerManager

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

// Create scene trigger manager instance
const sceneManager = RewardAdSceneTriggerManager.new({
  sign: 'app',
  log: true,
  sceneTypeObj: {
    1: 'home_page',
    2: 'reader_page',
    3: 'book_detail_page'
  }
});

// Add scene by value
sceneManager.addScene('home_page');

// Add scene by type
sceneManager.addSceneType(1);

// Get current scene
const currentScene = sceneManager.getCurrentScene();
console.log('Current scene:', currentScene);

RewardAdGlobalRecorder

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

// Create global recorder instance
const recorder = RewardAdGlobalRecorder.new({
  sign: 'app'
});

// Record ad execution
recorder.record({
  type: 'halfway',
  scene: 1
});

recorder.record({
  type: 'finished',
  scene: 2
});

// Get record count
const halfwayCount = recorder.get({
  type: 'halfway',
  scenes: [1, 2]
});

const finishedCount = recorder.get({
  type: 'finished'
});

console.log('Halfway count:', halfwayCount);
console.log('Finished count:', finishedCount);

// Reset records
recorder.rest('halfway');
recorder.rest('finished');

Examples

实际应用场景示例

1. 小说章节解锁管理

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

// 创建解锁管理器
const unlockManager = LovelUnlockManager.new({
  sign: 'reader',
  unlockChapterThreshold: 2000,
  unlockChapterNum: 30,
  unlockChapterWaterLevel: 15
});

// 设置章节列表
const chapters = [
  { episodeId: 'ch1', flagTag: 1, albumId: '第一章' },
  { episodeId: 'ch2', flagTag: 0, albumId: '第二章' },
  { episodeId: 'ch3', flagTag: 0, albumId: '第三章' }
];
unlockManager.drama = chapters;

// 根据阈值判断解锁逻辑
function handleUnlockRequest(chapterId) {
  unlockManager.ready(
    () => {
      // 未达到阈值，执行原逻辑
      console.log('Unlocking single chapter:', chapterId);
    },
    (unlockedIds) => {
      // 达到阈值，执行批量解锁逻辑
      console.log('Batch unlocking chapters:', unlockedIds);
    },
    chapterId
  );
}

// 用户点击解锁按钮时调用
handleUnlockRequest('ch2');

2. 广告场景追踪

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

// 创建场景触发管理器
const sceneManager = RewardAdSceneTriggerManager.new({
  sign: 'app',
  log: true,
  sceneTypeObj: {
    1: 'home_page',
    2: 'reader_page',
    3: 'book_detail_page',
    4: 'profile_page'
  }
});

// 页面跳转时记录场景
function onPageChange(pageType) {
  sceneManager.addSceneType(pageType);
  const currentScene = sceneManager.getCurrentScene();
  console.log('Current scene:', currentScene);
  
  // 根据场景决定是否展示广告
  if (shouldShowAd(currentScene)) {
    showAd();
  }
}

// 页面跳转
onPageChange(1); // 首页
onPageChange(2); // 阅读页
onPageChange(3); // 书籍详情页

3. 广告执行统计

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

// 创建全局记录器
const recorder = RewardAdGlobalRecorder.new({
  sign: 'app'
});

// 广告执行中途记录
function onAdHalfway(scene) {
  recorder.record({
    type: 'halfway',
    scene: scene
  });
}

// 广告执行完成记录
function onAdFinished(scene) {
  recorder.record({
    type: 'finished',
    scene: scene
  });
}

// 获取特定场景的统计数据
function getSceneStats(scenes) {
  const halfwayCount = recorder.get({
    type: 'halfway',
    scenes: scenes
  });
  const finishedCount = recorder.get({
    type: 'finished',
    scenes: scenes
  });
  
  return {
    halfway: halfwayCount,
    finished: finishedCount,
    completionRate: finishedCount / (halfwayCount || 1)
  };
}

// 使用示例
onAdHalfway(1);
onAdFinished(1);

const stats = getSceneStats([1, 2]);
console.log('Scene stats:', stats);

API

LovelUnlockManager

Constructor

new LovelUnlockManager(args)

• args (Object): 构造函数参数
  • sign (String): 初始化标识，可选值: 'bookStore', 'reader', 'bookIntro'
  • unlockChapterThreshold (Number): 单次解锁章节阈值，默认 2000
  • unlockChapterNum (Number): 解锁章节数，默认 30
  • unlockChapterWaterLevel (Number): 解锁章节水滴阈值，默认 15

Properties

• drama (Array): 剧情详情数据
  • episodeId (String): 章节 ID
  • flagTag (Number|null): 1 已解锁，0 未解锁，null 未解锁
  • albumId (String): 章节名称

Methods

• ready(callback, callbackThreshold, chapterId): 判断是否达到解锁阈值，走不同的逻辑

  • callback (Function): 原逻辑【达到阈值前】回调函数
  • callbackThreshold (Function, optional): 新逻辑【达到阈值后】回调函数
  • chapterId (String, optional): 章节 ID

• onProcessUpdate(r, callback): 章节阅读进度更新

  • r (Object): 当前章节的阅读进度
    • chapterId (String): 章节 ID
    • percent (Number): 当前章节的阅读进度
  • callback (Function): 达到阈值后回调函数

• onChapterChange(r, callback): 章节变化

  • r (Object): 当前章节的阅读进度
    • currentChapterId (String): 变化前的章节 ID
    • nextChapterId (String): 变化后的章节 ID
    • nextOutChapterId (String, optional): 开发者自己的章节 ID
  • callback (Function): 达到阈值后回调函数

• unlockAll(): 解锁所有章节

• static build(args): 获取单例实例

  • args (Object): 构造函数参数
  • 返回: LovelUnlockManager 实例

• static getInstance(): 获取单例实例

  • 返回: LovelUnlockManager 实例

• static new(args): 创建新实例

  • args (Object): 构造函数参数
  • 返回: LovelUnlockManager 实例

RewardAdSceneTriggerManager

Constructor

new RewardAdSceneTriggerManager(args)

• args (Object): 构造函数参数
  • sign (String): 初始化标识
  • log (Boolean, optional): 是否开启日志，默认 true
  • sceneTypeObj (Object): 当前场景 sceneTypeMap 场景值类型映射表

Methods

• initialize(args): 初始化方法

  • args (Object): 初始化参数

• addScene(value): 添加场景值

  • value (String): 场景值
  • 返回: RewardAdSceneTriggerManager 实例

• addSceneType(value): 添加场景类型

  • value (Number): 场景值类型
  • 返回: RewardAdSceneTriggerManager 实例

• getCurrentScene(): 获取当前场景值

  • 返回: 当前场景值

• placeholder(): 站位方法，没有任何作用

  • 返回: null

• static build(args): 获取单例实例

  • args (Object): 构造函数参数
  • 返回: RewardAdSceneTriggerManager 实例

• static getInstance(): 获取单例实例

  • 返回: RewardAdSceneTriggerManager 实例

RewardAdGlobalRecorder

Constructor

new RewardAdGlobalRecorder(args)

• args (Object): 构造函数参数
  • sign (String): 初始化标识

Methods

• initialize(args): 初始化方法

  • args (Object): 初始化参数

• record(args): 记录广告执行数据

  • args (Object): 记录参数
    • type (String): 记录类型，可选值: 'halfway', 'finished'
    • scene (Number): 场景值

• get(args): 获取记录数据

  • args (Object): 查询参数
    • type (String): 记录类型，可选值: 'halfway', 'finished'
    • scenes (Array, optional): 场景值数组
  • 返回: Number，记录总数

• rest(type): 重置记录数据

  • type (String): 记录类型，可选值: 'halfway', 'finished'

• placeholder(): 站位方法，没有任何作用

  • 返回: null

• static build(args): 获取单例实例

  • args (Object): 构造函数参数
  • 返回: RewardAdGlobalRecorder 实例

• static getInstance(): 获取单例实例

  • 返回: RewardAdGlobalRecorder 实例

License

MIT