@singcl/ad-execute-manager 2.0.0-alpha.0 → 2.0.0

package/dist/ad/InterstitialAdFather.d.ts

@@ -2,6 +2,10 @@ export default InterstitialAdFather;
 export type IRewordAdConfig = import("../typings/ad.js").IRewordAdConfig;
 export type CallbackCollection = import("../typings/ad.js").CallbackCollection;
 export type IConstructArgs = import("../typings/ad.js").IConstructArgs;
+/**
+ * 激励视频实例
+ */
+export type InterstitialAd = import("../typings/create-interstitial-ad.js").InterstitialAd;
 export type IRewardedVideoAd = {
     /**
      * 显示激励视频广告
@@ -24,23 +28,32 @@ declare class InterstitialAdFather {
      * @param {Object} adInstance 广告实例
      * @param {Object} ctx 上下文对象，用于传递数据和状态
      * @param {Object} ctx.options 广告执行选项
-     * @param {Object} ctx.options.log 是否打印日志
      * @param {Object} ctx.collection 回调集合
      * @returns {Promise} 广告执行结果的Promise
      */
     static executeWithManager(adInstance: any, ctx: {
-        options: {
-            log: any;
-        };
+        options: any;
         collection: any;
     }): Promise<any>;
     /**
      * @param {IConstructArgs} args
      */
     constructor(args: IConstructArgs);
+    /** @private  */
+    /** @type {Logger} */
+    _logger: Logger;
     _initSign: string;
     _preserveOnEnd: boolean;
-    _interstitialAd: any;
+    /**
+     * 激励视频实例
+     * @type {InterstitialAd | null}
+     */
+    _interstitialAd: InterstitialAd | null;
+    /**
+     * 激励视频实例
+     * @type {InterstitialAd | null}
+     */
+    __ad__: InterstitialAd | null;
     _ttErrorMsgs: string[];
     _ttErrorCodes: number[];
     _adConfig: {};
@@ -88,8 +101,26 @@ declare class InterstitialAdFather {
      * 任务执行完成后始终执行的一个方法
      * @abstract 任务执行完成后始终执行的一个方法，子类需要用到时实现此方法
      * @param {object} [_args] 执行结果信息
-     */
-    record(_args?: object): this;
+     * @param {number} [_args.scene] 场景信息
+     * @param {string} _args.id 任务id
+     * @param {object} [_args.apiError] 广告api错误信息
+     * @param {number} [_args.adTypeR] 广告类型 1 激励视频 2插屏广告
+     * @param {object} _args.recovered 后台恢复重试
+     * @param {boolean} [_args.recovered.retry] 后台恢复预估是否重试
+     * @param {number} [_args.recovered.count] 后台恢复预估重试次数
+     * @param {string} [_args.recovered.message] 后台恢复预估重试原因
+     */
+    record(_args?: {
+        scene?: number;
+        id: string;
+        apiError?: object;
+        adTypeR?: number;
+        recovered: {
+            retry?: boolean;
+            count?: number;
+            message?: string;
+        };
+    }): this;
     /**
      *
      * @param {({isEnded: boolean, count: number}) => void} callback
@@ -129,3 +160,4 @@ declare class InterstitialAdFather {
      */
     placeholder(): any;
 }
+import { Logger } from '../helper/Logger';

package/dist/ad/InterstitialAdNovel.d.ts

@@ -339,6 +339,8 @@ declare class InterstitialAdNovel extends InterstitialAdFather {
         collection?: import("../typings/ad.js").CallbackCollection;
     }): Promise<(IEndArgs & ICloseArgs) | undefined>;
     /**
+     * ATTENTION: 应用一旦进入后台，90%概率.show() 方法的.then() 回调将不会被执行, .catch() 回调也不会被执行。
+     * 此时将进入超时处理逻辑
      * @override
      * @param {object} [ctx] 广告执行上下文
      * @param {import('../typings/ad.js').IRewordAdConfig} [ctx.options] 广告执行选项
@@ -351,6 +353,8 @@ declare class InterstitialAdNovel extends InterstitialAdFather {
         collection?: import("../typings/ad.js").CallbackCollection;
     }, next?: Function): Promise<(IEndArgs & ICloseArgs) | undefined>;
     /**
+     * ATTENTION: 应用一旦进入后台，90%概率.show() 方法的.then() 回调将不会被执行, .catch() 回调也不会被执行。
+     * 此时将进入超时处理逻辑
      * @param {object} [ctx] 广告执行上下文
      * @param {object} [ctx.options] 广告执行选项
      * @param {number} [ctx.options.scene] 广告执行场景

package/dist/ad/RewardAdFather.d.ts

@@ -1,7 +1,9 @@
 export default RewardAdFather;
 export type IRewordAdConfig = import("../typings/ad.js").IRewordAdConfig;
 export type CallbackCollection = import("../typings/ad.js").CallbackCollection;
+export type RecoveredInfo = import("../typings/ad.js").RecoveredInfo;
 export type IConstructArgs = import("../typings/ad.js").IConstructArgs;
+export type RewardedVideoAd = import("../typings/create-rewarded-video-ad.js").RewardedVideoAd;
 export type IRewardedVideoAd = {
     /**
      * 显示激励视频广告
@@ -24,25 +26,36 @@ declare class RewardAdFather {
      * @param {Object} adInstance 广告实例
      * @param {Object} ctx 上下文对象，用于传递数据和状态
      * @param {Object} ctx.options 广告执行选项
-     * @param {Object} ctx.options.log 是否打印日志
      * @param {Object} ctx.collection 回调集合
      * @returns {Promise} 广告执行结果的Promise
      */
     static executeWithManager(adInstance: any, ctx: {
-        options: {
-            log: any;
-        };
+        options: any;
         collection: any;
     }): Promise<any>;
     /**
      * @param {IConstructArgs} args
      */
     constructor(args: IConstructArgs);
+    /** @private  */
+    /** @type {Logger} */
+    _logger: Logger;
+    _adTimeoutTime: number;
     _initSign: string;
     _preserveOnEnd: boolean;
-    _rewardAd: any;
+    /**
+     * 激励视频实例
+     * @type {RewardedVideoAd | null}
+     */
+    _rewardAd: RewardedVideoAd | null;
+    /**
+     * 激励视频实例
+     * @type {RewardedVideoAd | null}
+     */
+    __ad__: RewardedVideoAd | null;
     _ttErrorMsgs: string[];
     _ttErrorCodes: number[];
+    __bindAdErrorForeverHandler: any;
     _adConfig: {};
     /**
      * 初始化
@@ -53,12 +66,29 @@ declare class RewardAdFather {
      */
     initialize(params: IRewordAdConfig, callback?: (v: IRewardedVideoAd) => void): this;
     initialized(): boolean;
+    /**
+     * 激励视频展示失败时始终执行的一个方法
+     * @private
+     * @param {{errMsg: string; errCode: number}} e 错误信息
+     */
+    private __adErrorForeverHandler;
+    /**
+     * 激励视频展示失败时始终执行的一个方法
+     * @abstract 激励视频展示失败时始终执行的一个方法，子类需要用到时实现此方法
+     * @param {{errMsg: string; errCode: number}} _e 错误信息
+     * @returns
+     */
+    adErrorForeverHandler(_e: {
+        errMsg: string;
+        errCode: number;
+    }): any;
     /**
      * 执行广告展示
      * @abstract
      * @param {Object} [ctx] 上下文对象，用于传递数据和状态
      * @param {IRewordAdConfig} [ctx.options] 广告执行选项
      * @param {CallbackCollection} [ctx.collection] 回调集合
+     * @param {RecoveredInfo} [ctx.recovered] 恢复重试信息
      * @param {Function} next 执行下一个任务的回调函数，在洋葱模型中手动调用以继续执行流程
      * @returns {Promise<unknown>} 广告执行结果的Promise
      * @throws {Error} 子类必须实现此方法
@@ -66,6 +96,7 @@ declare class RewardAdFather {
     ad(ctx?: {
         options?: IRewordAdConfig;
         collection?: CallbackCollection;
+        recovered?: RecoveredInfo;
     }, next?: Function): Promise<unknown>;
     /**
      * 确保广告按顺序执行
@@ -88,8 +119,26 @@ declare class RewardAdFather {
      * 任务执行完成后始终执行的一个方法
      * @abstract 任务执行完成后始终执行的一个方法，子类需要用到时实现此方法
      * @param {object} [_args] 执行结果信息
-     */
-    record(_args?: object): this;
+     * @param {number} [_args.scene] 场景信息
+     * @param {string} _args.id 任务id
+     * @param {object} [_args.apiError] 广告api错误信息
+     * @param {number} [_args.adTypeR] 广告类型 1 激励视频 2插屏广告
+     * @param {object} _args.recovered 后台恢复重试
+     * @param {boolean} [_args.recovered.retry] 后台恢复预估是否重试
+     * @param {number} [_args.recovered.count] 后台恢复预估重试次数
+     * @param {string} [_args.recovered.message] 后台恢复预估重试原因
+     */
+    record(_args?: {
+        scene?: number;
+        id: string;
+        apiError?: object;
+        adTypeR?: number;
+        recovered: {
+            retry?: boolean;
+            count?: number;
+            message?: string;
+        };
+    }): this;
     /**
      *
      * @param {({isEnded: boolean, count: number}) => void} callback
@@ -129,3 +178,4 @@ declare class RewardAdFather {
      */
     placeholder(): any;
 }
+import { Logger } from '../helper/Logger';

package/dist/ad/RewardAdNovel.d.ts

@@ -52,6 +52,10 @@ export type IConstructArgs = {
      * 初始化标识
      */
     sign?: string;
+    /**
+     * 是否开启日志
+     */
+    log?: boolean;
     /**
      * 是否保留tt激励视频广告实例
      */
@@ -60,6 +64,10 @@ export type IConstructArgs = {
      * 是否需要在超时情况下结束广告
      */
     needEndOnTimeout?: boolean;
+    /**
+     * 关闭广告时候是否需要主动结束任务
+     */
+    proactive?: boolean;
     /**
      * 激励视频参数 (可选)
      */
@@ -126,8 +134,10 @@ export type IRewardedVideoAd = {
 /**
  * @typedef IConstructArgs
  * @property {string} [sign] 初始化标识
+ * @property {boolean} [log] 是否开启日志
  * @property {boolean} [preserveOnEnd] 是否保留tt激励视频广告实例
  * @property {boolean} [needEndOnTimeout] 是否需要在超时情况下结束广告
+ * @property {boolean} [proactive] 关闭广告时候是否需要主动结束任务
  * @property {IRewordAdConfig=} [adConfig] 激励视频参数 (可选)
  * @property {IConnection=} [collection] 回调集合
  */
@@ -185,7 +195,6 @@ declare class RewardAdNovel extends RewardAdFather {
     _scene: number;
     _adTypeR: 1;
     _adTimeout: any;
-    _adTimeoutTime: number;
     _adBeforeShowTimer: any;
     _adBeforeShowTime: number;
     _adSpeedCloseTimer: any;
@@ -193,6 +202,10 @@ declare class RewardAdNovel extends RewardAdFather {
     _needEndOnTimeout: boolean;
     /** @deprecated TODO 移除 */
     _needSpeedEndOnTimeout: boolean;
+    /**
+     * @description 关闭广告时候是否需要主动结束任务
+     */
+    _proactive: boolean;
     bindAdCloseLister: any;
     bindAdErrorLister: any;
     bindAdLoadLister: any;
@@ -217,7 +230,18 @@ declare class RewardAdNovel extends RewardAdFather {
     }): void;
     novelConfig: RewardAdNovelConfig;
     _onInnerExecuteBefore(): any;
-    _onInnerAdShowSuccess(): any;
+    /**
+     * @param {object} _args
+     * @param {string} _args.scene 广告执行场景 必填
+     * @param {number} [_args.result] 广告执行成功结果 必填
+     * @param {import('../typings/ad.js').RecoveredInfo} [_args.recovered] 恢复重试信息
+     * @returns
+     */
+    _onInnerAdShowSuccess(_args: {
+        scene: string;
+        result?: number;
+        recovered?: import("../typings/ad.js").RecoveredInfo;
+    }): any;
     /**
      * 广告展示超时设置
      * @param {object} args
@@ -230,6 +254,20 @@ declare class RewardAdNovel extends RewardAdFather {
         timeout?: number;
         end: Function;
     }): void;
+    /**
+     * 子类可以选择覆盖此方法
+     * 添加超时情况下结束任务前的回调
+     * @param {object} args
+     * @param {string} args.scene 广告执行场景 必填
+     * @param {number} args.timeout 广告超时时间 单位ms 必填
+     */
+    _adTimeoutBeforeEnd(args: {
+        scene: string;
+        timeout: number;
+    }): {
+        scene: string;
+        timeout: number;
+    };
     /**
      * 广告展示前定时器
      * @param {object} args
@@ -259,13 +297,15 @@ declare class RewardAdNovel extends RewardAdFather {
      * @param {object} _args
      * @param {string} _args.scene 广告执行场景 必填
      * @param {string} [_args.msg] 广告执行成功原因
-     * @param {0|1} _args.result 广告执行成功结果
+     * @param {0|1} _args.result 广告执行成功结果 必填
+     * @param {import('../typings/ad.js').RecoveredInfo} [_args.recovered] 恢复重试信息
      * @returns
      */
     protected _adShowSuccessAnalytics(_args: {
         scene: string;
         msg?: string;
         result: 0 | 1;
+        recovered?: import("../typings/ad.js").RecoveredInfo;
     }): any;
     /**
      * 广告展示失败分析
@@ -291,13 +331,20 @@ declare class RewardAdNovel extends RewardAdFather {
      * @param {object} _args
      * @param {string} _args.scene 广告执行场景 必填
      * @param {string} [_args.msg] 广告执行成功原因
-     * @param {0|1} _args.result 广告执行成功结果
+     * @param {0|1} _args.result 广告执行成功结果 必填
+     * @param {object} [_args.frequency] 广告执行重试参数
+     * @param {number} _args.frequency.total 广告执行总次数 必填
+     * @param {number} _args.frequency.current 广告执行当前次数 必填
      * @returns
      */
     protected _adLoadSuccessAnalytics(_args: {
         scene: string;
         msg?: string;
         result: 0 | 1;
+        frequency?: {
+            total: number;
+            current: number;
+        };
     }): any;
     /**
      * 广告加载失败分析
@@ -329,7 +376,7 @@ declare class RewardAdNovel extends RewardAdFather {
         ad_is_completed: number;
         ad_count: number;
     }): any;
-    get rewardAd(): any;
+    get rewardAd(): import("../typings/create-rewarded-video-ad.js").RewardedVideoAd;
     /**
      * 确保广告按顺序执行
      * @override
@@ -347,19 +394,23 @@ declare class RewardAdNovel extends RewardAdFather {
      * @param {object} [ctx] 广告执行上下文
      * @param {import('../typings/ad.js').IRewordAdConfig} [ctx.options] 广告执行选项
      * @param {import('../typings/ad.js').CallbackCollection} [ctx.collection] 回调集合
+     * @param {import('../typings/ad.js').RecoveredInfo} [ctx.recovered] 恢复重试信息
      * @param {Function} next 执行下一个任务的回调函数，手动调用以继续执行流程
      * @returns {Promise.<IEndArgs & ICloseArgs | Undefined>}
      */
     override ad(ctx?: {
         options?: import("../typings/ad.js").IRewordAdConfig;
         collection?: import("../typings/ad.js").CallbackCollection;
+        recovered?: import("../typings/ad.js").RecoveredInfo;
     }, next?: Function): Promise<(IEndArgs & ICloseArgs) | undefined>;
+    _recovered: import("../typings/ad.js").RecoveredInfo;
     /**
      * @param {object} [ctx] 广告执行上下文
      * @param {object} [ctx.options] 广告执行选项
      * @param {number} [ctx.options.scene] 广告执行场景 必填
      * @param {number} [ctx.options.timeout] 广告超时时间 单位ms
      * @param {object} ctx.collection 回调集合
+     * @param {import('../typings/ad.js').RecoveredInfo} [ctx.recovered] 恢复重试信息
      * @param {(v?: unknown) => void} ctx.collection.resolve 广告执行成功的回调函数
      * @param {(v?: unknown) => void} [ctx.collection.reject] 广告执行失败的回调函数
      * @param {(v?: unknown) => void} [ctx.collection.before] 广告执行前的回调函数
@@ -372,16 +423,11 @@ declare class RewardAdNovel extends RewardAdFather {
             scene?: number;
             timeout?: number;
         };
-        collection: {
-            resolve: (v?: unknown) => void;
-            reject?: (v?: unknown) => void;
-            before?: (v?: unknown) => void;
-            success?: (v?: unknown) => void;
-            prelude?: (v?: unknown) => void;
-        };
+        collection: object;
+        recovered?: import("../typings/ad.js").RecoveredInfo;
     }, next?: Function): void;
-    _before: (v?: unknown) => void;
-    _success: (v?: unknown) => void;
+    _before: any;
+    _success: any;
     /**
      * 广告加载
      * @returns
@@ -397,10 +443,24 @@ declare class RewardAdNovel extends RewardAdFather {
     _outerFinishedCallback(args: any): void;
     /**
      * 关闭激励视频
-     * 子类重写该方法时，必须调用this._clearAdTimeout();清除超时定时器
      * @param {ICloseArgs} args
      */
-    adCloseLister(args: ICloseArgs): void;
+    __adCloseLister__(args: ICloseArgs): void;
+    /**
+     * 关闭激励视频结束任务
+     * 子类可以重写该方法，如果子类不提供该方法，则使用默认实现
+     * 如果子类需要主动结束任务，则需要设置proactive为true，同时主动调用end方法
+     * @param {object} args
+     * @param {(ctx: object) => void} args.end 结束任务  如果proactive为true，则需要主动调用end方法，否则不需要调用
+     * @param {(ctx: object) => void} args.conn 调用传入的回调函数 如果proactive为true，则需要主动调用conn方法，否则不需要调用
+     */
+    adCloseLister(args: {
+        end: (ctx: object) => void;
+        conn: (ctx: object) => void;
+    }): {
+        end: (ctx: object) => void;
+        conn: (ctx: object) => void;
+    };
     adErrorLister(e: any): void;
     apiAdErrorLister(e: any): void;
     /**

package/dist/{helper → analytics}/AdAnalyticsJS.d.ts

@@ -7,6 +7,10 @@ export type IConstructorArgs = {
      * 初始化标识
      */
     sign: string;
+    /**
+     * 是否开启日志
+     */
+    log?: boolean;
     /**
      * 是否需要上报
      */
@@ -25,6 +29,7 @@ export type ICommonInfo = {
 /**
  * @typedef {object} IConstructorArgs
  * @property {string} sign 初始化标识
+ * @property {boolean} [log] 是否开启日志
  * @property {boolean} [needReport] 是否需要上报
  * @property {ICommonInfo} [commonConfig] 公共用户信息
  *
@@ -56,6 +61,9 @@ declare class AdAnalyticsJS {
      * @param {IConstructorArgs} args
      */
     constructor(args: IConstructorArgs);
+    /** @private  */
+    /** @type {Logger} */
+    _logger: Logger;
     _initSign: string;
     _needReport: boolean;
     /** @type {ICommonInfo | null}  */
@@ -130,3 +138,4 @@ declare class AdAnalyticsJS {
      */
     placeholder(): any;
 }
+import { Logger } from '../helper/Logger';

package/dist/core/AdExecuteManager.d.ts

@@ -32,6 +32,24 @@ export type AdTask = {
      * 广告任务是否已被拒绝
      */
     _isRejected: boolean;
+    /**
+     * 广告任务后台恢复前台时预估重试次数
+     */
+    _retryCount: number;
+    /**
+     * 广告任务后台恢复前台时预估重试次数的原因
+     */
+    _retryMsg: string;
+};
+export type ErrorRetryStrategy = {
+    /**
+     * 是否重试超时错误
+     */
+    timeout?: boolean;
+    /**
+     * 是否重试后台错误
+     */
+    background?: boolean;
 };
 export type IConstructArgs = {
     /**
@@ -42,6 +60,18 @@ export type IConstructArgs = {
      * 是否打印日志
      */
     log?: boolean;
+    /**
+     * 是否启用前后台监听, 进入后台时候未执行的任务放入任务栈，等待进入前台恢复执行
+     */
+    enableVisibilityListener?: boolean;
+    /**
+     * 最大重试次数, 默认为1 0表示不重试
+     */
+    maxRetryCount?: number;
+    /**
+     * 进入后台时广告展示错误时重试策略
+     */
+    errorRetryStrategy?: ErrorRetryStrategy;
 };
 declare class AdExecuteManager {
     /**
@@ -55,6 +85,18 @@ declare class AdExecuteManager {
      * @returns {AdExecuteManager}
      */
     static getInstance(args?: IConstructArgs): AdExecuteManager;
+    /**
+     * 获取单例实例
+     * @param {IConstructArgs} [args]
+     * @returns {AdExecuteManager}
+     */
+    static build(args?: IConstructArgs): AdExecuteManager;
+    /**
+     * 获取单例实例
+     * @param {IConstructArgs} [args]
+     * @returns {AdExecuteManager}
+     */
+    static "new"(args?: IConstructArgs): AdExecuteManager;
     /**
      * 获取单例实例
      * @returns {AdExecuteManager}
@@ -82,7 +124,71 @@ declare class AdExecuteManager {
      * @type {AdTask|null}
      */
     _currentTask: AdTask | null;
+    /**
+     * @type {boolean}
+     */
+    _isForeground: boolean;
+    /**
+     * @type {Function|null}
+     */
+    _appShowListener: Function | null;
+    /**
+     * @type {Function|null}
+     */
+    _appHideListener: Function | null;
+    /**
+     * @type {boolean}
+     */
+    _enableVisibilityListener: boolean;
+    /**
+     * @type {number}
+     */
+    _maxRetryCount: number;
+    /**
+     * @type {Array.<AdTask>}
+     */
+    _retryQueue: Array<AdTask>;
+    /**
+     * 进入后台时广告展示错误时重试策略
+     */
+    _errorRetryStrategy: {
+        timeout: boolean;
+        background: boolean;
+    };
     logger: Logger;
+    initialize(_args: any): this;
+    /**
+     * 初始化前后台监听器
+     * @private
+     */
+    private _initVisibilityListener;
+    /**
+     * 处理应用进入后台
+     * @private
+     */
+    private _handleAppHide;
+    /**
+     * 处理应用进入前台
+     * @private
+     */
+    private _handleAppShow;
+    /**
+     * 销毁前后台监听器
+     */
+    destroyVisibilityListener(): void;
+    /**
+     * 启用前后台监听
+     */
+    enableVisibilityListener(): void;
+    /**
+     * 禁用前后台监听
+     */
+    disableVisibilityListener(): void;
+    /**
+     * 获取前后台监听器状态
+     * @returns {boolean} 是否启用
+     */
+    isVisibilityListenerEnabled(): boolean;
     /**
      * 添加广告任务
      * @param {import('../ad/RewardAdFather.js').default} adInstance RewardAdFather的子类实例
@@ -106,7 +212,7 @@ declare class AdExecuteManager {
     clearTasks(): void;
     /**
      * 获取当前未完成的任务总数
-     * 包括任务栈中待执行的任务和中间件链中未完成的任务
+     * 包括任务栈中待执行的任务、中间件链中未完成的任务和重试队列中的任务
      * @returns {number} 未完成的任务数量
      */
     getTaskCount(): number;

package/dist/core/_util.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 判断是否需要重试
+ * @param {object} param
+ * @param {object} param.apiError 广告错误信息
+ * @param {number} param.configuredAdTimeout 配置的广告超时时间
+ * @param {object} [param.errorRetryStrategy] 错误重试策略
+ * @param {boolean} [param.errorRetryStrategy.timeout] 是否需要重试超时错误
+ * @param {boolean} [param.errorRetryStrategy.background] 是否需要重试后台错误
+ * @returns
+ */
+export function needRetryAdError({ apiError, configuredAdTimeout, errorRetryStrategy }: {
+    apiError: object;
+    configuredAdTimeout: number;
+    errorRetryStrategy?: {
+        timeout?: boolean;
+        background?: boolean;
+    };
+}): boolean;

package/dist/helper/SerializableError.d.ts

@@ -1,9 +1,13 @@
 export class SerializableError extends Error {
-    constructor(message: any);
+    constructor(message: any, options?: {});
     stack: string;
+    errMsg: any;
+    errorCode: any;
     toJSON(): {
         name: string;
         message: string;
         stack: string;
+        errMsg: any;
+        errorCode: any;
     };
 }