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

package/dist/core/src/AdExecuteManager.d.ts

@@ -0,0 +1,252 @@
+export default AdExecuteManager;
+export type IAdInstance = {
+    /**
+     * 超时时间
+     */
+    _adTimeoutTime: number;
+    /**
+     * 初始化广告
+     */
+    initialize: (ctx: unknown) => IAdInstance;
+    /**
+     * 显示广告
+     */
+    ad: (options: unknown, ctx: unknown, recovered: unknown) => Promise<unknown>;
+    clear: () => void;
+};
+export type IRewordAdConfig = import("./typings/ad.js").IRewordAdConfig;
+export type CallbackCollection = import("./typings/ad.js").CallbackCollection;
+export type AdTask = {
+    /**
+     * RewardAdFather的子类实例
+     */
+    adInstance: IAdInstance;
+    /**
+     * 广告执行选项
+     */
+    options: IRewordAdConfig;
+    /**
+     * 回调集合
+     */
+    callbackCollection: CallbackCollection;
+    /**
+     * 广告执行成功的回调函数
+     */
+    resolve: Function;
+    /**
+     * 广告执行失败的回调函数
+     */
+    reject: Function;
+    /**
+     * 广告任务的唯一标识符
+     */
+    id: string;
+    /**
+     * 广告任务是否已成功解决
+     */
+    _isResolved: boolean;
+    /**
+     * 广告任务是否已被拒绝
+     */
+    _isRejected: boolean;
+    /**
+     * 广告任务后台恢复前台时预估重试次数
+     */
+    _retryCount: number;
+    /**
+     * 广告任务后台恢复前台时预估重试次数的原因
+     */
+    _retryMsg: string;
+};
+export type ErrorRetryStrategy = {
+    /**
+     * 是否重试超时错误
+     */
+    timeout?: boolean;
+    /**
+     * 是否重试后台错误
+     */
+    background?: boolean;
+};
+export type IConstructArgs = {
+    /**
+     * 广告执行选项
+     */
+    options?: object;
+    /**
+     * 是否打印日志
+     */
+    log?: boolean;
+    /**
+     * 是否启用前后台监听, 进入后台时候未执行的任务放入任务栈，等待进入前台恢复执行
+     */
+    enableVisibilityListener?: boolean;
+    /**
+     * 最大重试次数, 默认为1 0表示不重试
+     */
+    maxRetryCount?: number;
+    /**
+     * 进入后台时广告展示错误时重试策略
+     */
+    errorRetryStrategy?: ErrorRetryStrategy;
+};
+declare class AdExecuteManager {
+    /**
+     * 单例实例
+     * @type {AdExecuteManager|null}
+     */
+    static _instance: AdExecuteManager | null;
+    /**
+     * 获取单例实例
+     * @param {IConstructArgs} [args]
+     * @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}
+     */
+    static getSafeInstance(): AdExecuteManager;
+    /**
+     *
+     * @param {IConstructArgs} args
+     * @returns
+     */
+    constructor(args: IConstructArgs);
+    /**
+     * @type {Array.<AdTask>}
+     */
+    _taskStack: Array<AdTask>;
+    /**
+     * @type {Array.<AdTask>}
+     */
+    _currentBatchTasks: Array<AdTask>;
+    /**
+     * @type {boolean}
+     */
+    _isRunning: boolean;
+    /**
+     * @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 {IAdInstance} adInstance RewardAdFather的子类实例
+     * @param {Object} ctx 广告执行上下文
+     * @param {IRewordAdConfig} ctx.options 广告执行选项
+     * @param {CallbackCollection} ctx.collection 回调集合
+     * @returns {Promise} 广告执行结果的Promise
+     */
+    addTask(adInstance: IAdInstance, ctx: {
+        options: IRewordAdConfig;
+        collection: CallbackCollection;
+    }): Promise<any>;
+    /**
+     * 组合所有任务
+     * @private
+     */
+    private _compose;
+    /**
+     * 清空任务栈并取消所有任务（包括正在执行的任务和middleware链中等待执行的任务）
+     */
+    clearTasks(): void;
+    /**
+     * 获取当前未完成的任务总数
+     * 包括任务栈中待执行的任务、中间件链中未完成的任务和重试队列中的任务
+     * @returns {number} 未完成的任务数量
+     */
+    getTaskCount(): number;
+    /**
+     * 是否有任务正在运行
+     * @returns {boolean}
+     */
+    isRunning(): boolean;
+    /**
+     * 获取当前执行的任务ID
+     * @returns {string|null} 当前任务ID
+     */
+    getCurrentTaskId(): string | null;
+    /**
+     * 返回一个Promise，当任务队列中的所有任务都完成时resolve
+     * @returns {Promise<void>} 当所有任务完成时resolve的Promise
+     */
+    whenAllTasksComplete(): Promise<void>;
+}
+import { Logger } from '@ad-execute-manager/helper';

package/dist/core/src/_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/core/{index.d.ts → src/index.d.ts}

@@ -1,2 +1 @@
-export { default as compose } from "./compose.js";
 export { default as AdExecuteManager } from "./AdExecuteManager.js";

package/dist/core/src/typings/ad.d.ts

@@ -0,0 +1,208 @@
+export type IRewordAdConfig = {
+    /**
+     * 激励视频广告id - 必填
+     */
+    adUnitId: string;
+    /**
+     * 是否开启进度提醒。开启时广告文案为「再看 n 个xxx」，关闭时为「再看 1 个xxx」。其中 n 表示用户当前还需额外观看广告的次数
+     */
+    progressTip?: boolean | undefined;
+    /**
+     * - 再得广告的奖励文案，用户每看完一个广告都会展示，multiton 为 true 时必填。
+     * - 文案完整内容为「再看 1 个xxx」，其中 xxx 是 multitonRewardMsg 配置的文案内容，最大长度为 7，
+     * - 文案内容根据 multitonRewardMsg 的配置按顺序展示。若 multitonRewardMsg 长度小于 multitonRewardTimes ，
+     * - 则后续的激励再得广告文案取 multitonRewardMsg 数组最后一个。
+     */
+    multitonRewardMsg?: Array<string> | undefined;
+    /**
+     * 是否开启激励再得广告
+     */
+    multiton?: boolean | undefined;
+    /**
+     * 额外观看广告的次数，合法的数据范围为 1～4，multiton 为 true 时必填
+     */
+    multitonRewardTimes?: number | undefined;
+    /**
+     * 场景值 - 自用参数，非tt API要求的参数
+     */
+    scene?: number | undefined;
+    /**
+     * 广告超时时间 单位ms - 自用参数，非tt API要求的参数
+     */
+    timeout?: number | undefined;
+    /**
+     * 重试次数 - 自用参数 ，非tt API要求的参数
+     */
+    retry: number;
+    /**
+     * 是否绑定永远的错误事件 - 自用参数，非tt API要求的参数
+     */
+    foreverErrorBind?: boolean | undefined;
+};
+export type InterstitialAdConfig = {
+    /**
+     * 单个广告单元的 id。可从「开放平台控制台-进入对应小程序-运营-商业化变现-广告管理」中获取 - 必填
+     */
+    adUnitId: string;
+    /**
+     * 场景值 - 自用参数
+     */
+    scene?: number | undefined;
+};
+export type IExeCallbackArgs = {
+    /**
+     * 广告执行场景
+     */
+    scene: number;
+    /**
+     * 是否看完
+     */
+    isEnded: boolean;
+    /**
+     * 完整观看次数
+     */
+    count: number;
+    /**
+     * 剩余观看次数
+     */
+    remain?: number;
+};
+export type CallbackCollection = {
+    /**
+     * 每次外部回调
+     */
+    always?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 完整看完广告外部回调 不管一个还是几个
+     */
+    finished?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 半途退出广告外部回调
+     */
+    halfway?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 完成广告外部回调 不管看不看完
+     */
+    complete?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 取消广告外部回调
+     */
+    onCancel?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 展示广告外部回调
+     */
+    before?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 展示广告成功外部回调
+     */
+    success?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 计时回调
+     */
+    prelude?: (ctx?: unknown) => void;
+};
+export type RecoveredInfo = {
+    /**
+     * 恢复重试次数
+     */
+    count: number;
+    /**
+     * 是否恢复重试
+     */
+    retry: boolean;
+    /**
+     * 恢复重试原因
+     */
+    message: string;
+};
+export type ICallbackArgs = {
+    /**
+     * 广告执行场景
+     */
+    scene: number;
+    /**
+     * 是否看完
+     */
+    isEnded: boolean;
+    /**
+     * 完整观看次数
+     */
+    count: number;
+    /**
+     * 剩余观看次数
+     */
+    remain?: number;
+    /**
+     * 执行下一个任务的回调函数，手动调用以继续执行流程[end]
+     */
+    end?: () => void;
+    /**
+     * 执行下一个任务的回调函数， 手动调用以继续执行流程[circle]
+     */
+    circle?: (args: {
+        ignoreRemain: boolean;
+        scene: number;
+    }) => void;
+};
+export type IConnection = {
+    /**
+     * 广告中途退出回调
+     */
+    onHalfway?: (args: ICallbackArgs) => void;
+    /**
+     * 广告展示回调
+     */
+    onShow?: (args: ICallbackArgs) => void;
+    /**
+     * 广告执行成功回调
+     */
+    onFinish?: (args: ICallbackArgs) => void;
+    /**
+     * 广告执行失败回调
+     */
+    onError?: (e: unknown) => void;
+};
+export type IConstructArgs = {
+    /**
+     * 初始化标识
+     */
+    sign: string;
+    /**
+     * 是否开启日志
+     */
+    log?: boolean | undefined;
+    /**
+     * 重试次数
+     */
+    retry: number;
+    /**
+     * 是否保留tt激励视频广告实例
+     */
+    preserveOnEnd: boolean;
+    /**
+     * 激励视频参数 (可选)
+     */
+    adConfig?: IRewordAdConfig | undefined;
+    /**
+     * 回调集合
+     */
+    collection?: IConnection | undefined;
+};
+/**
+ * 广告场景类型映射对象
+ */
+export type SceneTypeMap = {
+    readonly [x: number]: string;
+};
+/**
+ * 广告场景类型文本映射对象（反向映射）
+ */
+export type SceneTextMap = { readonly [K in SceneTypeMap[keyof SceneTypeMap]]: { [P in keyof SceneTypeMap]: SceneTypeMap[P] extends K ? P : never; }[keyof SceneTypeMap]; };
+/**
+ * 场景值枚举 可持续添加
+ */
+export type RewardAdTriggerScene = keyof SceneTextMap;
+/**
+ * 场景值枚举 可持续添加
+ */
+export type RewardAdTriggerSceneType = keyof SceneTypeMap;

package/dist/core/typings/ad.d.ts

@@ -0,0 +1,208 @@
+export type IRewordAdConfig = {
+    /**
+     * 激励视频广告id - 必填
+     */
+    adUnitId: string;
+    /**
+     * 是否开启进度提醒。开启时广告文案为「再看 n 个xxx」，关闭时为「再看 1 个xxx」。其中 n 表示用户当前还需额外观看广告的次数
+     */
+    progressTip?: boolean | undefined;
+    /**
+     * - 再得广告的奖励文案，用户每看完一个广告都会展示，multiton 为 true 时必填。
+     * - 文案完整内容为「再看 1 个xxx」，其中 xxx 是 multitonRewardMsg 配置的文案内容，最大长度为 7，
+     * - 文案内容根据 multitonRewardMsg 的配置按顺序展示。若 multitonRewardMsg 长度小于 multitonRewardTimes ，
+     * - 则后续的激励再得广告文案取 multitonRewardMsg 数组最后一个。
+     */
+    multitonRewardMsg?: Array<string> | undefined;
+    /**
+     * 是否开启激励再得广告
+     */
+    multiton?: boolean | undefined;
+    /**
+     * 额外观看广告的次数，合法的数据范围为 1～4，multiton 为 true 时必填
+     */
+    multitonRewardTimes?: number | undefined;
+    /**
+     * 场景值 - 自用参数，非tt API要求的参数
+     */
+    scene?: number | undefined;
+    /**
+     * 广告超时时间 单位ms - 自用参数，非tt API要求的参数
+     */
+    timeout?: number | undefined;
+    /**
+     * 重试次数 - 自用参数 ，非tt API要求的参数
+     */
+    retry: number;
+    /**
+     * 是否绑定永远的错误事件 - 自用参数，非tt API要求的参数
+     */
+    foreverErrorBind?: boolean | undefined;
+};
+export type InterstitialAdConfig = {
+    /**
+     * 单个广告单元的 id。可从「开放平台控制台-进入对应小程序-运营-商业化变现-广告管理」中获取 - 必填
+     */
+    adUnitId: string;
+    /**
+     * 场景值 - 自用参数
+     */
+    scene?: number | undefined;
+};
+export type IExeCallbackArgs = {
+    /**
+     * 广告执行场景
+     */
+    scene: number;
+    /**
+     * 是否看完
+     */
+    isEnded: boolean;
+    /**
+     * 完整观看次数
+     */
+    count: number;
+    /**
+     * 剩余观看次数
+     */
+    remain?: number;
+};
+export type CallbackCollection = {
+    /**
+     * 每次外部回调
+     */
+    always?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 完整看完广告外部回调 不管一个还是几个
+     */
+    finished?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 半途退出广告外部回调
+     */
+    halfway?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 完成广告外部回调 不管看不看完
+     */
+    complete?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 取消广告外部回调
+     */
+    onCancel?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 展示广告外部回调
+     */
+    before?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 展示广告成功外部回调
+     */
+    success?: (ctx?: IExeCallbackArgs) => void;
+    /**
+     * 计时回调
+     */
+    prelude?: (ctx?: unknown) => void;
+};
+export type RecoveredInfo = {
+    /**
+     * 恢复重试次数
+     */
+    count: number;
+    /**
+     * 是否恢复重试
+     */
+    retry: boolean;
+    /**
+     * 恢复重试原因
+     */
+    message: string;
+};
+export type ICallbackArgs = {
+    /**
+     * 广告执行场景
+     */
+    scene: number;
+    /**
+     * 是否看完
+     */
+    isEnded: boolean;
+    /**
+     * 完整观看次数
+     */
+    count: number;
+    /**
+     * 剩余观看次数
+     */
+    remain?: number;
+    /**
+     * 执行下一个任务的回调函数，手动调用以继续执行流程[end]
+     */
+    end?: () => void;
+    /**
+     * 执行下一个任务的回调函数， 手动调用以继续执行流程[circle]
+     */
+    circle?: (args: {
+        ignoreRemain: boolean;
+        scene: number;
+    }) => void;
+};
+export type IConnection = {
+    /**
+     * 广告中途退出回调
+     */
+    onHalfway?: (args: ICallbackArgs) => void;
+    /**
+     * 广告展示回调
+     */
+    onShow?: (args: ICallbackArgs) => void;
+    /**
+     * 广告执行成功回调
+     */
+    onFinish?: (args: ICallbackArgs) => void;
+    /**
+     * 广告执行失败回调
+     */
+    onError?: (e: unknown) => void;
+};
+export type IConstructArgs = {
+    /**
+     * 初始化标识
+     */
+    sign: string;
+    /**
+     * 是否开启日志
+     */
+    log?: boolean | undefined;
+    /**
+     * 重试次数
+     */
+    retry: number;
+    /**
+     * 是否保留tt激励视频广告实例
+     */
+    preserveOnEnd: boolean;
+    /**
+     * 激励视频参数 (可选)
+     */
+    adConfig?: IRewordAdConfig | undefined;
+    /**
+     * 回调集合
+     */
+    collection?: IConnection | undefined;
+};
+/**
+ * 广告场景类型映射对象
+ */
+export type SceneTypeMap = {
+    readonly [x: number]: string;
+};
+/**
+ * 广告场景类型文本映射对象（反向映射）
+ */
+export type SceneTextMap = { readonly [K in SceneTypeMap[keyof SceneTypeMap]]: { [P in keyof SceneTypeMap]: SceneTypeMap[P] extends K ? P : never; }[keyof SceneTypeMap]; };
+/**
+ * 场景值枚举 可持续添加
+ */
+export type RewardAdTriggerScene = keyof SceneTextMap;
+/**
+ * 场景值枚举 可持续添加
+ */
+export type RewardAdTriggerSceneType = keyof SceneTypeMap;

package/dist/helper/dist/index.d.cts

@@ -0,0 +1 @@
+export const __esModule: boolean;