@playcraft/adsdk 1.0.2-2.beta.1

package/dist/index.d.mts

@@ -0,0 +1,385 @@
+/**
+ * i18n 数据结构（仅 runtime，SDK 只处理游戏内运行时多语言）
+ *   runtime: { [key]: { [langCode]: "文案" } }
+ *
+ * 当传入数组时，按顺序深度合并（后面的优先级更高），
+ * 支持全局 i18n + 主题级 i18n 分文件管理：
+ *   runtime: [I18nRuntime, themeI18n]  // 主题级覆盖全局
+ *
+ * xplatform（配置平台 UI 标题）由外部配置平台自行解析，不传入 SDK。
+ */
+type I18nRecord = {
+    runtime?: Record<string, Record<string, string>> | Record<string, Record<string, string>>[];
+};
+
+type EventName = 'playcraftInit' | 'playcraftReady' | 'playcraftStart' | 'playcraftInteractive' | 'playcraftInteraction' | 'playcraftChallengeStart' | 'playcraftChallengeProgress' | 'playcraftChallengeSuccess' | 'playcraftChallengeFailed' | 'playcraftResize' | 'playcraftPause' | 'playcraftResume' | 'playcraftVolume' | 'playcraftRetry' | 'playcraftFinish' | 'playcraftInstall';
+
+/**
+ * 自定义鼠标指针模块。
+ *
+ * 默认挂载到 `document.body`，把整页的默认光标替换为内置的手指图标：
+ * - 悬浮时显示 FingerHovering
+ * - 按下时显示 FingerPressing
+ *
+ * 图片以 base64 dataURL 形式内置到产物中，无需额外加载资源。
+ */
+interface CursorOptions {
+    /** 目标元素，未传则默认挂载到 document.body */
+    target?: HTMLElement;
+    /** 光标尺寸（像素），默认 64。热点固定为 size 的 1/8 */
+    size?: number;
+    /**
+     * 自定义鼠标悬浮态图片（URL 或 dataURL）。
+     * 传入后覆盖内置的手指图标。
+     */
+    hoverImage?: string;
+    /**
+     * 自定义鼠标按压态图片（URL 或 dataURL）。
+     * 仅当同时传了 hoverImage 时生效。
+     * 未传时按压态复用 hoverImage，无状态切换效果。
+     */
+    pressImage?: string;
+}
+/**
+ * 启用自定义鼠标指针。默认挂载到 `document.body`，作用于整个页面。
+ *
+ * 多次调用时，会先清理上一次的状态再重新绑定。
+ *
+ * @returns 清理函数，调用后会恢复默认光标并解除事件监听。
+ */
+declare function enableCustomCursor(opts?: CursorOptions): () => void;
+/**
+ * 关闭自定义鼠标指针，恢复默认光标。
+ */
+declare function disableCustomCursor(): void;
+
+type InitCallbackType = (maxWidth: number, maxHeight: number) => void;
+/**
+ * Main SDK class providing playable ad functionality and state management.
+ * Handles initialization, lifecycle events, and interactions across different ad networks.
+ */
+declare class sdk {
+    /** Current version of the SDK */
+    static version: string;
+    /** Current maximum width of the playable ad container in pixels */
+    static maxWidth: number;
+    /** Current maximum height of the playable ad container in pixels */
+    static maxHeight: number;
+    /** Indicates if the current orientation is landscape (width > height) */
+    static isLandscape: boolean;
+    /** Indicates if the Ad Network is ready and playable ad can be initialized */
+    static isReady: boolean;
+    /** Indicates if all playable ad resources are loaded and gameplay has started */
+    static isStarted: boolean;
+    /** Indicates if the playable ad is currently paused */
+    static isPaused: boolean;
+    /** Indicates if the playable ad has finished */
+    static isFinished: boolean;
+    /** Current volume level (0-1) */
+    static volume: number;
+    /** Number of user interactions with the playable ad (auto-incremented on each touch/click) */
+    static interactions: 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
+     * @example
+     * // Basic initialization
+     * sdk.playcraftInit();
+     *
+     * // Initialization with callback
+     * sdk.playcraftInit((width, height) => {
+     *   new App(width, height)
+     * });
+     *
+     * @fires playcraftInit When SDK initialization starts
+     * @fires playcraftReady When game instance is created and ready to load resources
+     */
+    static playcraftInit(callback?: InitCallbackType, options?: {
+        customCursor?: boolean | CursorOptions;
+    }): void;
+    /**
+     * Starts the playable ad experience.
+     * Should be called after all resources are loaded and first frame is rendered.
+     *
+     * @example
+     * sdk.playcraftStart();
+     *
+     * @fires playcraftStart When the playable ad starts
+     * @fires playcraftResize When the ad container is initially sized
+     */
+    static playcraftStart(): 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
+     * create() {
+     *   // ... all initialization code ...
+     *   sdk.playcraftInteractive();
+     * }
+     *
+     * @fires playcraftInteractive When the main scene is ready for user interaction
+     */
+    static playcraftInteractive(): void;
+    /**
+     * Marks the challenge as started.
+     * Should be called by business logic when the user actually starts playing.
+     *
+     * @example
+     * onFirstClick() {
+     *   sdk.playcraftChallengeStart();
+     * }
+     *
+     * @fires playcraftChallengeStart When the challenge starts
+     */
+    static playcraftChallengeStart(): void;
+    /**
+     * Marks the playable ad as finished.
+     *
+     * @example
+     * sdk.playcraftFinish();
+     *
+     * @fires playcraftFinish When the playable ad is marked as finished
+     */
+    static playcraftFinish(): void;
+    /**
+     * Triggers a retry/restart of the playable ad.
+     *
+     * @example
+     * retryButton.onclick = () => sdk.playcraftRetry();
+     *
+     * @fires playcraftRetry When a retry is triggered
+     */
+    static playcraftRetry(): void;
+    /**
+     * Triggers the install/download action for the advertised app.
+     *
+     * @example
+     * installButton.onclick = () => sdk.playcraftInstall();
+     *
+     * @fires playcraftFinish If the ad hasn't been marked as finished
+     * @fires playcraftInstall When the install action is triggered
+     */
+    static playcraftInstall(params?: {
+        action_type: 'auto' | 'click';
+        timeout: number;
+    }): void;
+    /**
+     * Trigger force resize event
+     *
+     * @example
+     * sdk.playcraftResize();
+     *
+     * @fires playcraftResize With current maxWidth and maxHeight
+     */
+    static playcraftResize(): void;
+    /**
+     * Records playable ad challenge progress (0-100).
+     * Triggers channel-specific milestone events based on the progress value.
+     * Milestones are not re-triggered once fired.
+     *
+     * @param percent Progress percentage (0-100)
+     *
+     * @example
+     * // Report 50% progress
+     * sdk.recordPlaycraftChallengeProgress(50);
+     *
+     * @fires playcraftChallengeProgress With the progress percentage value
+     */
+    static recordPlaycraftChallengeProgress(percent: number): void;
+    /**
+     * Records a game success/completion event.
+     * Sends platform-specific success tracking events:
+     * - AppLovin: CHALLENGE_SOLVED
+     * - Bigabid: complete
+     * - InMobi: Gameplay_Complete
+     *
+     * @example
+     * onLevelComplete() {
+     *   sdk.playcraftRecordSuccess();
+     * }
+     */
+    static playcraftRecordSuccess(): void;
+    /**
+     * Records a game failure event.
+     * Sends platform-specific failure tracking events:
+     * - AppLovin: CHALLENGE_FAILED
+     *
+     * @example
+     * onLevelFailed() {
+     *   sdk.playcraftRecordFailed();
+     * }
+     */
+    static playcraftRecordFailed(): void;
+    /**
+     * Forces the playable ad into a paused state.
+     *
+     * @example
+     * pauseButton.onclick = () => sdk.playcraftPause();
+     *
+     * @fires playcraftPause When the ad enters paused state
+     */
+    static playcraftPause(): void;
+    /**
+     * Resumes the playable ad from a forced pause state.
+     *
+     * @example
+     * resumeButton.onclick = () => sdk.playcraftResume();
+     *
+     * @fires playcraftResume When the ad resumes from pause
+     */
+    static playcraftResume(): void;
+    /**
+     * Registers an event listener.
+     *
+     * @param event Name of the event to listen for
+     * @param fn Callback function to execute when event occurs
+     * @param context Optional 'this' context for the callback
+     *
+     * @example
+     * sdk.on('playcraftInteraction', (count) => {
+     *   console.log(`User interaction #${count}`);
+     * });
+     */
+    static on(event: EventName, fn: Function, context?: any): void;
+    /**
+     * Registers a one-time event listener that removes itself after execution.
+     *
+     * @param event Name of the event to listen for
+     * @param fn Callback function to execute when event occurs
+     * @param context Optional 'this' context for the callback
+     *
+     * @example
+     * sdk.once('playcraftInteraction', () => {
+     *   console.log('First user interaction occurred!');
+     * });
+     */
+    static once(event: EventName, fn: Function, context?: any): void;
+    /**
+     * Removes an event listener.
+     *
+     * @param event Name of the event to stop listening for
+     * @param fn Optional callback function to remove
+     * @param context Optional 'this' context to match when removing
+     *
+     * @example
+     * sdk.off('playcraftInteraction', handler);
+     */
+    static off(event: EventName, fn?: Function, context?: any): void;
+    /**
+     * @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;
+    /**
+     * 获取当前用户语言的 i18n 简码。
+     * 多源探测（querystring → localStorage → cookie → navigator → html tag）。
+     *
+     * @returns i18n 简码：en | zh | ja | ko | de | fr | es | pt | it | hi | bn | ur | ar | tr | ru | ms | id，默认 'en'
+     *
+     * @example
+     * const langCode = sdk.getLanguageCode(); // 'zh'
+     */
+    static getLanguageCode(): string;
+    /**
+     * 设置主题配置，支持传入多份 JSON5 配置。
+     * 每一份配置都可以是 JSON Schema（带 $schema 字段），会自动提取其中的 default 值。
+     * 所有配置按顺序依次深度合并，后面的优先级更高。
+     *
+     * @param configList - 配置数组，每一项可以是：
+     *   - JSON Schema（带 $schema 字段）：自动提取 default 值后参与合并
+     *   - 普通配置对象：直接参与合并
+     * @param config - 额外配置项
+     *   - config.assetRecordByPath: 相对路径到已解析 URL 的映射
+     *
+     * @example
+     * sdk.setConfig(
+     *   [schemaA, schemaB, themeData],
+     *   { assetRecordByPath: imageAssets }
+     * );
+     */
+    static setConfig(configList: any[], config: {
+        assetRecordByPath: Record<string, string>;
+        i18nRecord?: I18nRecord;
+    }): void;
+    /**
+     * 获取合并后的主题配置。
+     * 返回 schema 默认值与用户主题数据深度合并后的结果。
+     * 必须先调用 sdk.setConfig() 才能使用此方法。
+     *
+     * @returns 合并后的主题配置对象
+     *
+     * @example
+     * const config = sdk.getConfig();
+     * console.log(config.primaryColor); // '#ff0000'
+     */
+    static getConfig(): Record<string, any>;
+    /**
+     * 启用自定义鼠标指针。默认挂载到 `document.body`，作用于整个页面。
+     * 悬浮显示手指图标，按下时切换为按压态图标。
+     * 多次调用会先清理上一次的状态再重新绑定。
+     *
+     * @param opts 可选配置
+     *   - opts.target: 目标元素，未传则默认 document.body
+     *   - opts.size: 光标尺寸（像素），默认 64，热点固定为 size 的 1/8
+     * @returns 清理函数，调用后会恢复默认光标并解除事件监听
+     *
+     * @example
+     * sdk.enableCustomCursor();
+     * sdk.enableCustomCursor({ size: 96 });
+     */
+    static enableCustomCursor(opts?: CursorOptions): () => void;
+    /**
+     * 关闭自定义鼠标指针，恢复默认光标。
+     *
+     * @example
+     * sdk.disableCustomCursor();
+     */
+    static disableCustomCursor(): void;
+}
+
+/**
+ * 微信浏览器引导遮罩层
+ * 当用户在微信中点击 Install 按钮时显示，引导用户在浏览器中打开
+ */
+/**
+ * 创建并显示微信浏览器引导遮罩
+ */
+declare function showWechatGuide(): void;
+/**
+ * 隐藏微信浏览器引导遮罩
+ */
+declare function hideWechatGuide(): void;
+/**
+ * 移除微信浏览器引导遮罩
+ */
+declare function removeWechatGuide(): void;
+
+/**
+ * 语言检测模块（零外部依赖）。
+ *
+ * 提供两个层级的语言获取：
+ *   - getLanguageCode()  → i18n 简码（en / zh / ja / ko …），用于 i18n.runtime 查表
+ *   - getLanguage()      → 业务语言代号（EN / CN_S / CN_T / DE …），用于游戏内资源选择
+ *
+ * 探测优先级（与 i18next-browser-languagedetector 保持一致）：
+ *   1. URL querystring (?lng=xx)
+ *   2. localStorage (i18nextLng)
+ *   3. cookie (i18next)
+ *   4. navigator.languages / navigator.language
+ *   5. <html lang="xx">
+ */
+/**
+ * 多源探测当前用户语言，并归一化为 i18n 简码。
+ *
+ * @returns i18n 简码：en | zh | zh-TW | ja | ko | de | fr | es | pt | it | hi | bn | ur | ar | tr | ru | ms | id，默认 'en'
+ */
+declare function getLanguageCode(): string;
+
+export { type CursorOptions, type I18nRecord, sdk as default, disableCustomCursor, enableCustomCursor, getLanguageCode, hideWechatGuide, removeWechatGuide, sdk, showWechatGuide };