@quicktvui/tv-ad-unlock 1.1.1 → 1.1.3

package/README.md

@@ -1,13 +1,13 @@
 # @quicktvui/tv-ad-unlock
 
-TV广告解锁组件，用于QuickTVUI框架的电视端广告解锁功能。
+TV 广告解锁组件 — 用于 QuickTVUI 框架的电视端广告解锁功能。
 
 ## 功能特性
 
-- 生成电视端广告二维码
-- 轮询广告观看状态
-- 自动管理解锁状态
-- 支持自定义配置
+- 电视端扫码观看广告，自动解锁
+- 内置广告弹窗页面（二维码 + 状态展示）
+- 积分信用体系（每日解锁 / 永久解锁 / 按次扣费）
+- 通过 Vue 插件注册，零配置路由
 
 ## 安装
 
@@ -15,139 +15,215 @@ TV广告解锁组件，用于QuickTVUI框架的电视端广告解锁功能。
 pnpm add @quicktvui/tv-ad-unlock
 ```
 
-## 使用方法
+**Peer Dependencies**（需项目已安装）：
 
-### 1. 基础使用
+- `vue ^3.0.0`
+- `@extscreen/es3-core >=3.0.0`
+- `@extscreen/es3-router >=3.0.0`
 
-```vue
-<template>
-  <TVAdUnlock
-    :config="adConfig"
-    :storageKeys="storageKeys"
-    :requestManager="requestManager"
-    @unlockSuccess="onUnlockSuccess"
-    @unlockFailed="onUnlockFailed"
-  />
-</template>
-
-<script setup lang="ts">
-import { TVAdUnlock, useTVAdUnlockStorage } from '@quicktvui/tv-ad-unlock'
-import type { TVAdUnlockConfig, TVAdUnlockStorageKeys, RequestManager } from '@quicktvui/tv-ad-unlock'
-
-const adConfig: TVAdUnlockConfig = {
-  packageName: 'com.example.app',
-  superRequestBaseUrl: 'https://superapi.extscreen.com/extscreenapi/api',
-  invalidTimeout: 300000,
-  pollInterval: 1000
-}
+## 快速开始
 
-const storageKeys: TVAdUnlockStorageKeys = {
-  playCountKey: 'app_play_count',
-  unlockDateKey: 'app_ad_unlock_date',
-  unlockedTodayKey: 'app_ad_unlocked_today'
-}
+### 1. 注册插件 & 路由（main-native.ts）
 
-const requestManager: RequestManager = {
-  post: async (url, data) => { /* 实现请求逻辑 */ },
-  get: async (url, data) => { /* 实现请求逻辑 */ }
-}
+```typescript
+import { createESRouter } from '@extscreen/es3-router'
+import { createESApp } from '@extscreen/es3-core'
+import { tvAdUnlockPlugin, createTVAdRoute } from '@quicktvui/tv-ad-unlock'
+import routes from './routes'
+
+// 将广告路由加入路由表
+const adRoute = createTVAdRoute()
+routes.push({ ...adRoute, launchMode: 'standard' })
+
+const router = createESRouter({ main: 'index', error: 'error', limit: 10, routes })
+const app = createESApp(App, router)
+
+// 注册广告解锁插件
+app.use(tvAdUnlockPlugin, {
+  packageName: 'com.example.myapp', // 必填，应用包名，用于存储 key 隔离
+  requestManager: myRequestManager, // 必填，实现 post/get 的请求管理器
+  // superRequestBaseUrl: 'https://superapi.extscreen.com/extscreenapi/api', // 可选，这是默认值
+  pageConfig: {
+    scanTitle: '观看广告获得积分',
+    scanContent: '观看广告后可获得5积分，用于游戏提示',
+    scanToast: '积分已发放，请返回游戏'
+  }
+})
+```
 
-function onUnlockSuccess() {
-  console.log('解锁成功')
-}
+### 2. 在页面中使用（页面 setup 中调用）
 
-function onUnlockFailed(error: Error) {
-  console.error('解锁失败', error)
-}
+```vue
+<script lang="ts">
+import { defineComponent } from 'vue'
+import { useTVAdNavigator } from '@quicktvui/tv-ad-unlock'
+
+export default defineComponent({
+  setup() {
+    const adNavigator = useTVAdNavigator({
+      packageName: 'com.example.myapp',
+      initialCredits: 0,     // 初始积分（默认 5）
+      creditsPerAd: 5,       // 每次看广告获得积分（默认 5）
+      dailyUnlockEnabled: true,            // 每日解锁开关（默认 true）
+      permanentUnlockAfterTotalAds: 10     // 看满N次广告永久解锁（默认 10，设0关闭）
+    })
+
+    // 在需要弹广告的地方调用
+    async function onNeedFeature() {
+      const showedAd = await adNavigator.consumeAndNavigate()
+      if (!showedAd) {
+        // 未弹广告（有积分或已解锁），直接执行业务逻辑
+      }
+      // showedAd === true 表示已跳转广告页，广告观看完成后会自动返回
+    }
+
+    return { onNeedFeature }
+  }
+})
 </script>
 ```
 
-### 2. 使用 Composable
+## API 参考
 
-```typescript
-import { useTVAdUnlock, useTVAdUnlockStorage } from '@quicktvui/tv-ad-unlock'
-import { useESLocalStorage } from '@extscreen/es3-core'
+### 插件选项 `TVAdUnlockPluginOptions`
 
-const storage = useESLocalStorage()
+`app.use(tvAdUnlockPlugin, options)` 的第二个参数：
 
-const storageKeys = {
-  playCountKey: 'app_play_count',
-  unlockDateKey: 'app_ad_unlock_date',
-  unlockedTodayKey: 'app_ad_unlocked_today'
-}
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `packageName` | `string` | 是 | - | 应用包名，用于存储 key 隔离 |
+| `requestManager` | `RequestManager` | 是 | - | 请求管理器，需实现 `post` 和 `get` |
+| `superRequestBaseUrl` | `string` | 否 | `https://superapi.extscreen.com/extscreenapi/api` | 广告接口基地址 |
+| `pageConfig` | `TVAdUnlockPageConfig` | 否 | 见下方 | 广告弹窗页面 UI 文案配置 |
+| `trackEvent` | `(event) => void` | 否 | - | 埋点回调 |
 
-const adStorage = useTVAdUnlockStorage(storage, storageKeys, 32)
+### 页面文案配置 `TVAdUnlockPageConfig`
 
-async function checkNeedShowAd() {
-  const needAd = await adStorage.checkNeedAd()
-  if (needAd) {
-    router.push({ name: 'ad' })
-  }
-}
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `title` | `'观看30秒广告 当日解锁'` | 弹窗标题 |
+| `subTitle` | `'手机打开【微信】扫码'` | 弹窗副标题 |
+| `scanTitle` | `'观看奖励'` | 手机端扫码页标题 |
+| `scanContent` | `'观看广告后可获得奖励'` | 手机端扫码页内容 |
+| `scanToast` | `'奖励已获得，请前往电视端观看'` | 手机端观看后提示 |
+| `invalidCodeImage` | 内置图片 | 二维码失效时展示的图片 URL |
+| `scannedCodeImage` | 内置图片 | 已扫码状态展示的图片 URL |
+
+### 路由配置 `createTVAdRoute()`
+
+返回一条广告弹窗路由对象，需推入路由表：
+
+```typescript
+const adRoute = createTVAdRoute()
+// 返回: { path: '/ad', name: 'ad', component: TVAdUnlockView, type: 1 }
+routes.push({ ...adRoute, launchMode: 'standard' })
 ```
 
-### 3. 路由配置
+### 导航器 `useTVAdNavigator(config)`
+
+在页面 `setup()` 中调用，按规则自动判断是否需要弹广告：
 
 ```typescript
-import { ESRouteType } from '@extscreen/es3-router'
-
-const routes = [
-  {
-    path: '/ad',
-    name: 'ad',
-    component: () => import('./views/ad/index.vue'),
-    type: ESRouteType.ES_ROUTE_TYPE_DIALOG
-  }
-]
+const adNavigator = useTVAdNavigator({
+  packageName: string       // 必填，应用包名
+  initialCredits?: number   // 初始积分，默认 5
+  creditsPerAd?: number     // 每次广告获得积分，默认 5
+  dailyUnlockEnabled?: boolean                // 每日解锁，默认 true
+  permanentUnlockAfterTotalAds?: number       // 永久解锁阈值，默认 10
+})
 ```
 
-## API
+**判断规则（按优先级）**：
 
-### Props
+1. 永久解锁 → 放行（不弹广告）
+2. 今日已解锁 → 放行
+3. 积分 > 0 → 扣 1 分，放行
+4. 兜底 → 跳转广告页
 
-| 属性 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| config | TVAdUnlockConfig | 是 | - | 广告配置 |
-| storageKeys | TVAdUnlockStorageKeys | 是 | - | 存储键名配置 |
-| requestManager | RequestManager | 是 | - | 请求管理器 |
-| title | string | 否 | '观看30秒广告 当日解锁' | 标题文字 |
-| subTitle | string | 否 | '手机打开【微信】扫码' | 副标题文字 |
-| invalidCodeImage | string | 否 | '' | 二维码失效图片 |
-| scannedCodeImage | string | 否 | '' | 已扫码图片 |
-| scanTitle | string | 否 | '观看奖励' | 扫码标题 |
-| scanContent | string | 否 | '观看广告后可获得奖励' | 扫码内容 |
-| scanToast | string | 否 | '奖励已获得，请前往电视端观看' | 扫码提示 |
-
-### Events
-
-| 事件名 | 参数 | 说明 |
-|--------|------|------|
-| unlockSuccess | - | 解锁成功 |
-| unlockFailed | error: Error | 解锁失败 |
-| qrCodeInvalid | - | 二维码失效 |
-| qrCodeScanned | - | 二维码已扫码 |
-
-### Types
+**返回方法**：
 
-```typescript
-interface TVAdUnlockConfig {
-  packageName: string
-  superRequestBaseUrl: string
-  trackBaseUrl?: string
-  invalidTimeout?: number
-  pollInterval?: number
-}
+| 方法 | 返回类型 | 说明 |
+|------|----------|------|
+| `consumeAndNavigate()` | `Promise<boolean>` | 核心方法。返回 `true` 表示已跳转广告页，`false` 表示放行 |
+| `consume(amount)` | `Promise<{success, consumed}>` | 手动扣减指定积分 |
+| `consumeAll()` | `Promise<number>` | 扣减全部积分，返回扣减值 |
+| `addCredits(amount)` | `Promise<void>` | 增加积分 |
+| `getCredits()` | `Promise<number>` | 查询当前积分 |
+| `isPermanentlyUnlocked()` | `Promise<boolean>` | 是否已永久解锁 |
+| `getTodayAdCount()` | `Promise<number>` | 今日已看广告次数 |
 
-interface TVAdUnlockStorageKeys {
-  playCountKey: string
-  unlockDateKey: string
-  unlockedTodayKey: string
-}
+### 存储管理 `useTVAdUnlockStorage(storage, keys, initialCredits?)`
+
+底层存储操作，一般不直接使用。高级场景可通过 `createStorageKeys(packageName)` 生成 key 集合后手动操作。
+
+### 类型定义
 
+```typescript
 interface RequestManager {
   post(url: string, data: Record<string, any>): Promise<any>
   get(url: string, data: string): Promise<any>
 }
+
+interface TVAdUnlockTrackEvent {
+  type: 'page' | 'click'
+  name: string
+  assetId?: string
+  assetName?: string
+  fromId?: string
+  fromName?: string
+}
+```
+
+## 完整示例
+
+```typescript
+// main-native.ts
+import { tvAdUnlockPlugin, createTVAdRoute } from '@quicktvui/tv-ad-unlock'
+import { createRequestManager } from './api/request/RequestManager'
+import routes from './routes'
+
+const adRoute = createTVAdRoute()
+routes.push({ ...adRoute, launchMode: 'standard' })
+
+const requestManager = createRequestManager()
+app.use(tvAdUnlockPlugin, {
+  packageName: 'com.example.app',
+  requestManager,
+  pageConfig: {
+    title: '观看广告 解锁功能',
+    scanTitle: '观看广告获得积分',
+    scanContent: '观看广告后可获得5积分',
+    scanToast: '积分已发放，请返回游戏'
+  }
+})
+```
+
+```vue
+<!-- 页面中使用 -->
+<script lang="ts">
+import { defineComponent } from 'vue'
+import { useTVAdNavigator } from '@quicktvui/tv-ad-unlock'
+
+export default defineComponent({
+  setup() {
+    const adNavigator = useTVAdNavigator({
+      packageName: 'com.example.app',
+      initialCredits: 0,
+      creditsPerAd: 5
+    })
+
+    function onShowHint() {
+      adNavigator.consumeAndNavigate().then(showedAd => {
+        if (!showedAd) {
+          // 直接显示提示
+        }
+      })
+    }
+
+    return { onShowHint }
+  }
+})
+</script>
 ```
 
 ## License

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+import type { InjectionKey } from 'vue';
+import type { TVAdUnlockPluginProvided } from './types';
+export declare const TV_AD_UNLOCK_KEY: InjectionKey<TVAdUnlockPluginProvided>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,KAAK,CAAA;AACvC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAEvD,eAAO,MAAM,gBAAgB,EAAE,YAAY,CAAC,wBAAwB,CAAwB,CAAA"}