@quicktvui/tv-ad-unlock

TV 广告解锁组件 — 用于 QuickTVUI 框架的电视端广告解锁功能。

功能特性

• 电视端扫码观看广告，自动解锁
• 内置广告弹窗页面（二维码 + 状态展示）
• 积分信用体系（每日解锁 / 永久解锁 / 按次扣费）
• 通过 Vue 插件注册，零配置路由

安装

pnpm add @quicktvui/tv-ad-unlock

Peer Dependencies（需项目已安装）：

• vue ^3.0.0
• @extscreen/es3-core >=3.0.0
• @extscreen/es3-router >=3.0.0

快速开始

1. 注册插件 & 路由（main-native.ts）

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: '积分已发放，请返回游戏'
  }
})

2. 在页面中使用（页面 setup 中调用）

<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>

API 参考

插件选项 TVAdUnlockPluginOptions

app.use(tvAdUnlockPlugin, options) 的第二个参数：

| 字段 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | packageName | string | 是 | - | 应用包名，用于存储 key 隔离 | | requestManager | RequestManager | 是 | - | 请求管理器，需实现 post 和 get | | superRequestBaseUrl | string | 否 | https://superapi.extscreen.com/extscreenapi/api | 广告接口基地址 | | pageConfig | TVAdUnlockPageConfig | 否 | 见下方 | 广告弹窗页面 UI 文案配置 | | trackEvent | (event) => void | 否 | - | 埋点回调 |

页面文案配置 TVAdUnlockPageConfig

| 字段 | 默认值 | 说明 | |------|--------|------| | title | '观看30秒广告 当日解锁' | TV 弹窗标题（页面展示） | | subTitle | '手机打开【微信】扫码' | TV 弹窗副标题（页面展示） | | scanTitle | '观看奖励' | 手机端扫码页标题（API 参数） | | scanContent | '观看广告后可获得奖励' | 手机端扫码页内容（API 参数） | | scanToast | '奖励已获得，请前往电视端观看' | 手机端观看后提示（API 参数） | | invalidCodeImage | 内置图片 | 二维码失效时展示的图片 URL | | scannedCodeImage | 内置图片 | 已扫码状态展示的图片 URL |

路由配置 createTVAdRoute()

返回一条广告弹窗路由对象，需推入路由表：

const adRoute = createTVAdRoute()
// 返回: { path: '/ad', name: 'ad', component: TVAdUnlockView, type: 1 }
routes.push({ ...adRoute, launchMode: 'standard' })

导航器 useTVAdNavigator(config)

在页面 setup() 中调用，按规则自动判断是否需要弹广告：

const adNavigator = useTVAdNavigator({
  packageName: string       // 必填，应用包名
  initialCredits?: number   // 初始积分，默认 5
  creditsPerAd?: number     // 每次广告获得积分，默认 5
  dailyUnlockEnabled?: boolean                // 每日解锁，默认 true
  permanentUnlockAfterTotalAds?: number       // 永久解锁阈值，默认 10
})

判断规则（按优先级）：

1. 永久解锁 → 放行（不弹广告）
2. 今日已解锁 → 放行
3. 积分 > 0 → 扣 1 分，放行
4. 兜底 → 跳转广告页

返回方法：

| 方法 | 返回类型 | 说明 | |------|----------|------| | 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> | 今日已看广告次数 |

存储管理 useTVAdUnlockStorage(storage, keys, initialCredits?)

底层存储操作，一般不直接使用。高级场景可通过 createStorageKeys(packageName) 生成 key 集合后手动操作。

类型定义

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
}

完整示例

// 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: '积分已发放，请返回游戏'
  }
})

<!-- 页面中使用 -->
<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

MIT