@playcraft/adsdk 1.0.7 → 1.0.9

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-type EventName = 'init' | 'boot' | 'ready' | 'start' | 'interaction' | 'resize' | 'pause' | 'resume' | 'volume' | 'retry' | 'finish' | 'install';
+type EventName = 'init' | 'ready' | 'start' | 'interactive' | 'interaction' | 'success' | 'resize' | 'pause' | 'resume' | 'volume' | 'retry' | 'finish' | 'install';
 
 type InitCallbackType = (maxWidth: number, maxHeight: number) => void;
 /**
@@ -24,13 +24,23 @@ declare class sdk {
     static isFinished: boolean;
     /** Current volume level (0-1) */
     static volume: number;
-    /** Number of user interactions with the playable ad */
+    /** Number of user interactions with the playable ad (auto-incremented on each touch/click) */
     static interactions: number;
+    /** Number of successful game actions (e.g., successful matches, level clears).
+     * Controlled by calling sdk.recordSuccessCount(), NOT auto-incremented.
+     */
+    static successCount: number;
     /**
      * Initializes the SDK and sets up protocol-specific handlers.
      * This must be called as earlier as possible.
      *
      * @param callback Optional function called when ad container is ready
+     * @param options Optional configuration options
+     * @param options.totalSuccessCount Total number of successful actions expected for progress tracking.
+     *   When set, the SDK will track success progress as a percentage and trigger
+     *   channel-specific milestone events (e.g., AppLovin: CHALLENGE_PASS_25/50/75, CHALLENGE_SOLVED).
+     *   Different channels monitor different percentage thresholds independently.
+     *   Set to 0 or omit to disable progress tracking.
      * @example
      * // Basic initialization
      * sdk.init();
@@ -40,11 +50,17 @@ declare class sdk {
      *   new App(width, height)
      * });
      *
-     * @fires init When initialization starts
-     * @fires boot When the ad begins booting
-     * @fires ready When Ad Network is ready and playable ad can be initialized
+     * // Initialization with success count progress tracking
+     * sdk.init((width, height) => {
+     *   new App(width, height)
+     * }, { totalSuccessCount: 20 });
+     *
+     * @fires loading When SDK initialization starts
+     * @fires loaded When game instance is created and ready to load resources
      */
-    static init(callback?: InitCallbackType): void;
+    static init(callback?: InitCallbackType, options?: {
+        totalSuccessCount?: number;
+    }): void;
     /**
      * Starts the playable ad experience.
      * Should be called after all resources are loaded and first frame is rendered.
@@ -57,6 +73,20 @@ declare class sdk {
      * @fires resize When the ad container is initially sized
      */
     static start(): void;
+    /**
+     * Marks the main scene as fully loaded and ready for user interaction.
+     * Should be called at the end of your main game scene's create() method.
+     *
+     * @example
+     * // In Phaser MainScene.create()
+     * create() {
+     *   // ... all initialization code ...
+     *   sdk.interactive();
+     * }
+     *
+     * @fires interactive When the main scene is ready for user interaction
+     */
+    static interactive(): void;
     /**
      * Marks the playable ad as finished.
      * This triggers network-specific completion handlers.
@@ -104,6 +134,53 @@ declare class sdk {
      * @fires resize With current maxWidth and maxHeight
      */
     static resize(): void;
+    /**
+     * Records successful game actions (e.g., successful match, level clear).
+     * This should be called by game logic when a meaningful success occurs.
+     * This count is used for progress tracking (e.g., AppLovin milestone events).
+     *
+     * @param count Optional success count to add (default: 1)
+     *
+     * @example
+     * // Record single success when match completes
+     * onMatchSuccess() {
+     *   sdk.recordSuccessCount();
+     * }
+     *
+     * // Record multiple successes at once
+     * onComboMatch(comboCount) {
+     *   sdk.recordSuccessCount(comboCount);
+     * }
+     *
+     * @fires success With updated success count (triggers progress tracking)
+     */
+    static recordSuccessCount(count?: number): void;
+    /**
+     * Records a game success/completion event.
+     * Sends platform-specific success tracking events:
+     * - AppLovin: CHALLENGE_SOLVED
+     * - Bigabid: complete
+     * - InMobi: Gameplay_Complete
+     *
+     * @example
+     * // When player completes the level
+     * onLevelComplete() {
+     *   sdk.recordSuccess();
+     * }
+     */
+    static recordSuccess(): void;
+    /**
+     * Records a game failure event.
+     * Sends platform-specific failure tracking events:
+     * - AppLovin: CHALLENGE_FAILED
+     *
+     * @example
+     * // When player fails the level
+     * onLevelFailed() {
+     *   sdk.recordFailed();
+     * }
+     */
+    static recordFailed(): void;
     /**
      * Forces the playable ad into a paused state.
      *
@@ -179,6 +256,10 @@ declare class sdk {
      * @returns 当前渠道
      */
     static getCurChannel(): "applovin" | "ironsource" | "unity" | "mintegral" | "preview" | "google" | "facebook" | "moloco" | "vungle" | "adcolony" | "tapjoy" | "snapchat" | "tiktok" | "appreciate" | "chartboost" | "pangle" | "mytarget" | "liftoff" | "smadex" | "adikteev" | "bigabid" | "inmobi" | "bigoads";
+    /**
+     * 判断是否是 Google
+     */
+    static isGoogle(): boolean;
 }
 
 /**
@@ -198,4 +279,138 @@ declare function hideWechatGuide(): void;
  */
 declare function removeWechatGuide(): void;
 
-export { sdk as default, hideWechatGuide, removeWechatGuide, sdk, showWechatGuide };
+/**
+ * 设置交互总数
+ */
+declare function setTotalInteractions(total: number): void;
+/**
+ * 检查交互进度，触发对应里程碑
+ */
+declare function checkInteractionProgress(currentInteractions: number): void;
+/**
+ * init 事件：SDK 初始化开始
+ * 渠道埋点: Bigabid:mraid_viewable | InMobi:Ad_Load_Start | AppLovin:LOADING
+ * 同时初始化进度里程碑
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onInit(adNetwork?: string): void;
+/**
+ * start 事件：游戏资源加载完成
+ * 渠道埋点: Bigabid:game_viewable | InMobi:Ad_Viewable | AppLovin:LOADED
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onStart(adNetwork?: string): void;
+/**
+ * interactive 事件：主场景就绪，用户可交互
+ * 渠道埋点: AppLovin:DISPLAYED
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onInteractive(adNetwork?: string): void;
+/**
+ * interaction 事件：首次交互
+ * 渠道埋点: Bigabid:engagement | InMobi:First_Engagement | AppLovin:CHALLENGE_STARTED
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onInteraction(adNetwork?: string): void;
+/**
+ * success 事件：成功计数（用于进度百分比追踪）
+ */
+declare function _onSuccess(successCount: number): void;
+/**
+ * finish 事件：游戏结束
+ * 渠道埋点: Bigabid:complete | InMobi:Gameplay_Complete | AppLovin:ENDCARD_SHOWN
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onFinish(adNetwork?: string): void;
+/**
+ * install 事件：点击安装
+ * 渠道埋点: Bigabid:click | InMobi:DSP_Click | AppLovin:CTA_CLICKED
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onInstall(adNetwork?: string): void;
+/**
+ * retry 事件：重试游戏
+ * 渠道埋点: AppLovin:CHALLENGE_RETRY
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onRetry(adNetwork?: string): void;
+/**
+ * 触发游戏成功事件
+ * 不同渠道发送对应的成功埋点
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _trackChallengeSuccess(adNetwork?: string): void;
+/**
+ * 触发游戏失败事件
+ * 不同渠道发送对应的失败埋点
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _trackChallengeFailed(adNetwork?: string): void;
+/**
+ * 统一的埋点追踪对象
+ * 包含所有 SDK 事件的埋点方法
+ */
+declare const tracking: {
+    /**
+     * SDK 初始化开始
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onInit: typeof _onInit;
+    /**
+     * 游戏资源加载完成
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onStart: typeof _onStart;
+    /**
+     * 主场景就绪，用户可交互
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onInteractive: typeof _onInteractive;
+    /**
+     * 首次交互
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onInteraction: typeof _onInteraction;
+    /**
+     * 成功计数（用于进度百分比追踪）
+     * @param successCount - 当前成功次数
+     */
+    onSuccess: typeof _onSuccess;
+    /**
+     * 游戏结束
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onFinish: typeof _onFinish;
+    /**
+     * 点击安装
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onInstall: typeof _onInstall;
+    /**
+     * 重试游戏
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onRetry: typeof _onRetry;
+    /**
+     * 设置交互总数（用于进度百分比计算）
+     * @param total - 交互总数
+     */
+    setTotalInteractions: typeof setTotalInteractions;
+    /**
+     * 检查交互进度
+     * @param currentInteractions - 当前交互次数
+     */
+    checkInteractionProgress: typeof checkInteractionProgress;
+    /**
+     * 触发游戏成功事件
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    trackChallengeSuccess: typeof _trackChallengeSuccess;
+    /**
+     * 触发游戏失败事件
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    trackChallengeFailed: typeof _trackChallengeFailed;
+};
+
+export { sdk as default, hideWechatGuide, removeWechatGuide, sdk, showWechatGuide, tracking };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-type EventName = 'init' | 'boot' | 'ready' | 'start' | 'interaction' | 'resize' | 'pause' | 'resume' | 'volume' | 'retry' | 'finish' | 'install';
+type EventName = 'init' | 'ready' | 'start' | 'interactive' | 'interaction' | 'success' | 'resize' | 'pause' | 'resume' | 'volume' | 'retry' | 'finish' | 'install';
 
 type InitCallbackType = (maxWidth: number, maxHeight: number) => void;
 /**
@@ -24,13 +24,23 @@ declare class sdk {
     static isFinished: boolean;
     /** Current volume level (0-1) */
     static volume: number;
-    /** Number of user interactions with the playable ad */
+    /** Number of user interactions with the playable ad (auto-incremented on each touch/click) */
     static interactions: number;
+    /** Number of successful game actions (e.g., successful matches, level clears).
+     * Controlled by calling sdk.recordSuccessCount(), NOT auto-incremented.
+     */
+    static successCount: number;
     /**
      * Initializes the SDK and sets up protocol-specific handlers.
      * This must be called as earlier as possible.
      *
      * @param callback Optional function called when ad container is ready
+     * @param options Optional configuration options
+     * @param options.totalSuccessCount Total number of successful actions expected for progress tracking.
+     *   When set, the SDK will track success progress as a percentage and trigger
+     *   channel-specific milestone events (e.g., AppLovin: CHALLENGE_PASS_25/50/75, CHALLENGE_SOLVED).
+     *   Different channels monitor different percentage thresholds independently.
+     *   Set to 0 or omit to disable progress tracking.
      * @example
      * // Basic initialization
      * sdk.init();
@@ -40,11 +50,17 @@ declare class sdk {
      *   new App(width, height)
      * });
      *
-     * @fires init When initialization starts
-     * @fires boot When the ad begins booting
-     * @fires ready When Ad Network is ready and playable ad can be initialized
+     * // Initialization with success count progress tracking
+     * sdk.init((width, height) => {
+     *   new App(width, height)
+     * }, { totalSuccessCount: 20 });
+     *
+     * @fires loading When SDK initialization starts
+     * @fires loaded When game instance is created and ready to load resources
      */
-    static init(callback?: InitCallbackType): void;
+    static init(callback?: InitCallbackType, options?: {
+        totalSuccessCount?: number;
+    }): void;
     /**
      * Starts the playable ad experience.
      * Should be called after all resources are loaded and first frame is rendered.
@@ -57,6 +73,20 @@ declare class sdk {
      * @fires resize When the ad container is initially sized
      */
     static start(): void;
+    /**
+     * Marks the main scene as fully loaded and ready for user interaction.
+     * Should be called at the end of your main game scene's create() method.
+     *
+     * @example
+     * // In Phaser MainScene.create()
+     * create() {
+     *   // ... all initialization code ...
+     *   sdk.interactive();
+     * }
+     *
+     * @fires interactive When the main scene is ready for user interaction
+     */
+    static interactive(): void;
     /**
      * Marks the playable ad as finished.
      * This triggers network-specific completion handlers.
@@ -104,6 +134,53 @@ declare class sdk {
      * @fires resize With current maxWidth and maxHeight
      */
     static resize(): void;
+    /**
+     * Records successful game actions (e.g., successful match, level clear).
+     * This should be called by game logic when a meaningful success occurs.
+     * This count is used for progress tracking (e.g., AppLovin milestone events).
+     *
+     * @param count Optional success count to add (default: 1)
+     *
+     * @example
+     * // Record single success when match completes
+     * onMatchSuccess() {
+     *   sdk.recordSuccessCount();
+     * }
+     *
+     * // Record multiple successes at once
+     * onComboMatch(comboCount) {
+     *   sdk.recordSuccessCount(comboCount);
+     * }
+     *
+     * @fires success With updated success count (triggers progress tracking)
+     */
+    static recordSuccessCount(count?: number): void;
+    /**
+     * Records a game success/completion event.
+     * Sends platform-specific success tracking events:
+     * - AppLovin: CHALLENGE_SOLVED
+     * - Bigabid: complete
+     * - InMobi: Gameplay_Complete
+     *
+     * @example
+     * // When player completes the level
+     * onLevelComplete() {
+     *   sdk.recordSuccess();
+     * }
+     */
+    static recordSuccess(): void;
+    /**
+     * Records a game failure event.
+     * Sends platform-specific failure tracking events:
+     * - AppLovin: CHALLENGE_FAILED
+     *
+     * @example
+     * // When player fails the level
+     * onLevelFailed() {
+     *   sdk.recordFailed();
+     * }
+     */
+    static recordFailed(): void;
     /**
      * Forces the playable ad into a paused state.
      *
@@ -179,6 +256,10 @@ declare class sdk {
      * @returns 当前渠道
      */
     static getCurChannel(): "applovin" | "ironsource" | "unity" | "mintegral" | "preview" | "google" | "facebook" | "moloco" | "vungle" | "adcolony" | "tapjoy" | "snapchat" | "tiktok" | "appreciate" | "chartboost" | "pangle" | "mytarget" | "liftoff" | "smadex" | "adikteev" | "bigabid" | "inmobi" | "bigoads";
+    /**
+     * 判断是否是 Google
+     */
+    static isGoogle(): boolean;
 }
 
 /**
@@ -198,4 +279,138 @@ declare function hideWechatGuide(): void;
  */
 declare function removeWechatGuide(): void;
 
-export { sdk as default, hideWechatGuide, removeWechatGuide, sdk, showWechatGuide };
+/**
+ * 设置交互总数
+ */
+declare function setTotalInteractions(total: number): void;
+/**
+ * 检查交互进度，触发对应里程碑
+ */
+declare function checkInteractionProgress(currentInteractions: number): void;
+/**
+ * init 事件：SDK 初始化开始
+ * 渠道埋点: Bigabid:mraid_viewable | InMobi:Ad_Load_Start | AppLovin:LOADING
+ * 同时初始化进度里程碑
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onInit(adNetwork?: string): void;
+/**
+ * start 事件：游戏资源加载完成
+ * 渠道埋点: Bigabid:game_viewable | InMobi:Ad_Viewable | AppLovin:LOADED
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onStart(adNetwork?: string): void;
+/**
+ * interactive 事件：主场景就绪，用户可交互
+ * 渠道埋点: AppLovin:DISPLAYED
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onInteractive(adNetwork?: string): void;
+/**
+ * interaction 事件：首次交互
+ * 渠道埋点: Bigabid:engagement | InMobi:First_Engagement | AppLovin:CHALLENGE_STARTED
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onInteraction(adNetwork?: string): void;
+/**
+ * success 事件：成功计数（用于进度百分比追踪）
+ */
+declare function _onSuccess(successCount: number): void;
+/**
+ * finish 事件：游戏结束
+ * 渠道埋点: Bigabid:complete | InMobi:Gameplay_Complete | AppLovin:ENDCARD_SHOWN
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onFinish(adNetwork?: string): void;
+/**
+ * install 事件：点击安装
+ * 渠道埋点: Bigabid:click | InMobi:DSP_Click | AppLovin:CTA_CLICKED
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onInstall(adNetwork?: string): void;
+/**
+ * retry 事件：重试游戏
+ * 渠道埋点: AppLovin:CHALLENGE_RETRY
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _onRetry(adNetwork?: string): void;
+/**
+ * 触发游戏成功事件
+ * 不同渠道发送对应的成功埋点
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _trackChallengeSuccess(adNetwork?: string): void;
+/**
+ * 触发游戏失败事件
+ * 不同渠道发送对应的失败埋点
+ * @param adNetwork - 可选的广告渠道名称，不传则使用全局 AD_NETWORK
+ */
+declare function _trackChallengeFailed(adNetwork?: string): void;
+/**
+ * 统一的埋点追踪对象
+ * 包含所有 SDK 事件的埋点方法
+ */
+declare const tracking: {
+    /**
+     * SDK 初始化开始
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onInit: typeof _onInit;
+    /**
+     * 游戏资源加载完成
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onStart: typeof _onStart;
+    /**
+     * 主场景就绪，用户可交互
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onInteractive: typeof _onInteractive;
+    /**
+     * 首次交互
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onInteraction: typeof _onInteraction;
+    /**
+     * 成功计数（用于进度百分比追踪）
+     * @param successCount - 当前成功次数
+     */
+    onSuccess: typeof _onSuccess;
+    /**
+     * 游戏结束
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onFinish: typeof _onFinish;
+    /**
+     * 点击安装
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onInstall: typeof _onInstall;
+    /**
+     * 重试游戏
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    onRetry: typeof _onRetry;
+    /**
+     * 设置交互总数（用于进度百分比计算）
+     * @param total - 交互总数
+     */
+    setTotalInteractions: typeof setTotalInteractions;
+    /**
+     * 检查交互进度
+     * @param currentInteractions - 当前交互次数
+     */
+    checkInteractionProgress: typeof checkInteractionProgress;
+    /**
+     * 触发游戏成功事件
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    trackChallengeSuccess: typeof _trackChallengeSuccess;
+    /**
+     * 触发游戏失败事件
+     * @param adNetwork - 可选的广告渠道名称
+     */
+    trackChallengeFailed: typeof _trackChallengeFailed;
+};
+
+export { sdk as default, hideWechatGuide, removeWechatGuide, sdk, showWechatGuide, tracking };