更新记录

1.0.6（2025-07-02）

无

1.0.5（2025-06-30）

更新日志

v1.0.5 (2024-06-25)

✨ 新增功能

插屏广告完整回调机制

• ✅ 新增setInterstitialCallbacks方法，支持插屏广告完整生命周期回调
• ✅ 支持6种关键事件回调：
  • onShow - 开始展示回调，广告开始显示时触发
  • onVideoStart - 视频开始播放回调（视频广告专用）
  • onVideoEnd - 视频播放结束回调（视频广告专用）
  • onVideoError - 视频播放失败回调，提供错误信息
  • onClosed - 广告关闭回调，用户关闭广告时触发
  • onClicked - 广告点击回调，用户点击广告时触发

横幅广告完整回调机制

• ✅ 新增setBannerCallbacks方法，支持横幅广告完整生命周期回调
• ✅ 支持6种关键事件回调：
  • onLoaded - 加载成功回调，广告加载完成时触发
  • onShow - 开始展示回调，广告开始显示时触发
  • onClicked - 广告点击回调，用户点击广告时触发
  • onClosed - 广告关闭回调，用户关闭广告时触发
  • onAutoRefreshed - 自动刷新回调，广告自动刷新成功时触发
  • onAutoRefreshFail - 自动刷新失败回调，提供错误信息

1.0.1（2025-06-25）

更新日志

v1.0.1 (2024-06-25)

平台兼容性

云端兼容性

uni-app(4.66)

uni-app x(4.62)

塔库广告 SDK UniApp UTS 插件

交流及售后群：115692274

微信：cnshaoyu

塔库广告（TakuAd）是一个专业的移动广告聚合SDK，支持多种广告形式。本插件为 UniApp 平台提供了完整的 UTS 原生插件实现。

🚀 功能特性

• ✅ 激励视频广告 - 用户观看完整视频后获得奖励，支持完整回调机制（6种回调）
• ✅ 插屏广告 - 在应用切换时展示的全屏广告，支持完整回调机制（6种回调）
• ✅ 横幅广告 - 固定位置的横幅展示广告，支持完整回调机制（6种回调）
• ✅ 开屏广告 - 应用启动时的全屏广告
• ✅ 智能预加载 - 自动预加载下一个广告提升展示成功率
• ✅ 场景统计 - 支持场景到达率统计优化变现
• ✅ 错误处理 - 完善的错误处理和日志记录

📦 安装配置

1. 插件集成

1. 将 uni_modules/moko-takuad 目录复制到你的项目中
2. 在 HBuilderX 中刷新项目结构
3. 插件会自动注册到项目中

2. 应用配置

在 manifest.json 中配置应用权限（Android）：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.INTERNET\" />",
          "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" />",
          "<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\" />",
          "<uses-permission android:name=\"android.permission.READ_PHONE_STATE\" />",
          "<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\" />",
          "<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" />",
          "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" />"
        ]
      }
    }
  }
}

3. 获取配置信息

前往 塔库广告开发者平台 注册账号并创建应用，获取：

• AppID: 应用唯一标识
• AppKey: 应用密钥
• PlacementID: 各广告位的ID

🔧 API 接口

SDK 基础管理

initSDKWithConfig(appId, appKey)

初始化SDK

import { initSDKWithConfig } from '@/uni_modules/moko-takuad'

// 初始化SDK
initSDKWithConfig('你的AppID', '你的AppKey')

setDebugMode(debug)

设置调试模式

import { setDebugMode } from '@/uni_modules/moko-takuad'

// 开启调试模式（发布时请关闭）
setDebugMode(true)

getSDKVersion()

获取SDK版本

import { getSDKVersion } from '@/uni_modules/moko-takuad'

const version = getSDKVersion()
console.log('SDK版本:', version)

激励视频广告

1. 设置业务回调（v1.0.3+新增）

import { setRewardVideoCallbacks } from '@/uni_modules/moko-takuad'

// 设置完整的业务回调（按参数顺序）
setRewardVideoCallbacks(
  () => {
    // onPlayStart - 开始播放回调
    console.log('🎬 激励视频开始播放')
    this.onVideoStarted()
  },
  () => {
    // onPlayEnd - 播放结束回调
    console.log('🏁 激励视频播放结束')
    this.onVideoCompleted()
  },
  (error) => {
    // onPlayFailed - 播放失败回调
    console.log('❌ 激励视频播放失败:', error)
    this.onVideoFailed(error)
  },
  () => {
    // onClosed - 广告关闭回调
    console.log('🚪 激励视频广告关闭')
    this.onVideoClosed()
  },
  () => {
    // onClicked - 广告点击回调
    console.log('👆 激励视频广告被点击')
    this.onVideoClicked()
  },
  () => {
    // onRewarded - 奖励发放回调
    console.log('🎁 激励视频奖励发放')
    this.onRewardGiven()
  }
)

2. 初始化激励视频

import { initRewardVideo } from '@/uni_modules/moko-takuad'

// 初始化激励视频（先设置回调，再初始化）
initRewardVideo('你的激励视频广告位ID', 'demo')

3. 加载广告

import { loadRewardVideo } from '@/uni_modules/moko-takuad'

loadRewardVideo('用户ID', '用户数据')

4. 检查广告状态

import { isRewardVideoReady } from '@/uni_modules/moko-takuad'

if (isRewardVideoReady()) {
  console.log('激励视频已准备好')
}

5. 展示广告

import { showRewardVideo } from '@/uni_modules/moko-takuad'

const success = showRewardVideo()
if (success) {
  console.log('激励视频展示成功')
}

6. 销毁广告

import { destroyRewardVideo } from '@/uni_modules/moko-takuad'

destroyRewardVideo()

7. 完整业务流程示例 🆕

// 完整的激励视频业务流程
export default {
  methods: {
    // 初始化激励视频
    async initRewardAd() {
      // 1. 先设置所有业务回调（按参数顺序传入）
      setRewardVideoCallbacks(
        this.handleVideoStarted,   // onPlayStart
        this.handleVideoCompleted, // onPlayEnd
        this.handleVideoFailed,    // onPlayFailed
        this.handleVideoClosed,    // onClosed
        this.handleVideoClicked,   // onClicked
        this.handleRewardGiven     // onRewarded
      )

      // 2. 初始化广告
      initRewardVideo('your_placement_id', 'demo')
    },

    // 处理播放开始
    handleVideoStarted() {
      console.log('🎬 视频开始播放')
      this.isPlaying = true
      // 可以暂停游戏音乐、显示播放状态等
    },

    // 处理播放结束
    handleVideoCompleted() {
      console.log('🏁 视频播放结束')
      this.isPlaying = false
      // 可以恢复游戏音乐、隐藏播放状态等
    },

    // 处理播放失败
    handleVideoFailed(error) {
      console.error('❌ 视频播放失败:', error)
      uni.showToast({
        title: '视频播放失败，请重试',
        icon: 'error'
      })
    },

    // 处理广告关闭
    handleVideoClosed() {
      console.log('🚪 广告关闭')
      this.isPlaying = false
      // 处理用户提前关闭的情况
    },

    // 处理广告点击
    handleVideoClicked() {
      console.log('👆 广告被点击')
      // 统计点击数据
      this.trackAdClick('reward_video')
    },

    // 处理奖励发放
    async handleRewardGiven() {
      try {
        console.log('🎁 开始发放奖励')

        // 1. 验证用户状态
        if (!this.isUserValid()) {
          throw new Error('用户状态无效')
        }

        // 2. 调用API发放奖励
        const result = await this.callRewardAPI({
          type: 'coins',
          amount: 100,
          source: 'reward_video'
        })

        if (result.success) {
          // 3. 更新本地状态
          this.userCoins += result.amount

          // 4. 显示奖励
          uni.showToast({
            title: `🎉 获得 ${result.amount} 金币！`,
            icon: 'success'
          })

          // 5. 触发其他业务逻辑
          this.refreshUserData()
        }

      } catch (error) {
        console.error('奖励发放失败:', error)
        uni.showToast({
          title: '奖励发放失败',
          icon: 'error'
        })
      }
    }
  }
}

插屏广告

1. 设置插屏广告回调（推荐）

为了更好地处理插屏广告各个生命周期事件的业务逻辑，建议在初始化前先设置回调：

import { setInterstitialCallbacks, initInterstitial } from '@/uni_modules/moko-takuad'

// 1. 设置插屏广告回调（按参数顺序）
setInterstitialCallbacks(
  () => { 
    // onShow - 开始展示回调
    console.log('插屏广告开始展示')
    // 可以在这里暂停游戏、显示加载状态等
  },
  () => { 
    // onVideoStart - 视频开始播放回调（如果是视频广告）
    console.log('插屏广告视频开始播放')
  },
  () => { 
    // onVideoEnd - 视频播放结束回调（如果是视频广告）
    console.log('插屏广告视频播放结束')
  },
  (error) => { 
    // onVideoError - 视频播放失败回调
    console.log('插屏广告视频播放失败:', error)
  },
  () => { 
    // onClosed - 广告关闭回调
    console.log('插屏广告关闭')
    // 可以在这里恢复游戏、隐藏加载状态等
  },
  () => { 
    // onClicked - 广告点击回调
    console.log('插屏广告被点击')
    // 可以在这里统计点击数据
  }
)

// 2. 初始化插屏广告
initInterstitial('your_placement_id', 'demo')

2. 初始化插屏广告

import { initInterstitial } from '@/uni_modules/moko-takuad'

initInterstitial('你的插屏广告位ID', 'demo')

2. 加载广告

import { loadInterstitial } from '@/uni_modules/moko-takuad'

loadInterstitial()

3. 展示广告

import { showInterstitial, isInterstitialReady } from '@/uni_modules/moko-takuad'

if (isInterstitialReady()) {
  showInterstitial()
}

4. 销毁广告

import { destroyInterstitial } from '@/uni_modules/moko-takuad'

destroyInterstitial()

横幅广告

1. 设置横幅广告回调（推荐）

为了更好地处理横幅广告各个生命周期事件的业务逻辑，建议在初始化前先设置回调：

import { setBannerCallbacks, initBanner } from '@/uni_modules/moko-takuad'

// 1. 设置横幅广告回调（按参数顺序）
setBannerCallbacks(
  () => { 
    // onLoaded - 加载成功回调
    console.log('横幅广告加载成功')
    // 可以在这里更新UI状态
  },
  () => { 
    // onShow - 开始展示回调
    console.log('横幅广告开始展示')
    // 广告成功展示时的处理
  },
  () => { 
    // onClicked - 广告点击回调
    console.log('横幅广告被点击')
    // 可以在这里统计点击数据
  },
  () => { 
    // onClosed - 广告关闭回调
    console.log('横幅广告关闭')
    // 广告被关闭时的处理
  },
  () => { 
    // onAutoRefreshed - 自动刷新回调
    console.log('横幅广告自动刷新')
    // 广告自动刷新时的处理
  },
  (error) => { 
    // onAutoRefreshFail - 自动刷新失败回调
    console.log('横幅广告自动刷新失败:', error)
    // 处理刷新失败的情况
  }
)

// 2. 初始化横幅广告
const bannerView = initBanner('your_placement_id', 'demo', 320, 50)

2. 初始化横幅广告

import { initBanner } from '@/uni_modules/moko-takuad'

const bannerView = initBanner('你的横幅广告位ID', 'demo', 320, 50)

2. 加载广告

import { loadBanner } from '@/uni_modules/moko-takuad'

loadBanner()

3. 获取广告View

import { getBannerView, isBannerReady } from '@/uni_modules/moko-takuad'

if (isBannerReady()) {
  const bannerView = getBannerView()
  // 将bannerView添加到你的布局中
}

4. 移除和销毁

import { removeBannerFromParent, destroyBanner } from '@/uni_modules/moko-takuad'

removeBannerFromParent() // 从父布局移除
destroyBanner() // 销毁广告

开屏广告

1. 初始化并加载

import { initAndLoadSplash } from '@/uni_modules/moko-takuad'

initAndLoadSplash('你的开屏广告位ID', 'demo', 5000)

2. 展示广告

import { showSplash, isSplashReady } from '@/uni_modules/moko-takuad'

if (isSplashReady()) {
  showSplash(null, true) // container为null时使用根布局
}

3. 销毁广告

import { destroySplash } from '@/uni_modules/moko-takuad'

destroySplash()

4. 强制关闭（v1.0.1新增）

import { closeSplash } from '@/uni_modules/moko-takuad'

// 当开屏广告无法正常关闭时使用
closeSplash()

5. 调试功能（v1.0.1新增）

import { debugSplashContainer } from '@/uni_modules/moko-takuad'

// 输出容器详细信息到控制台，用于调试
debugSplashContainer()

💡 最佳实践

1. 初始化时机

建议在应用启动时（App.vue 的 onLaunch）初始化SDK：

// App.vue
export default {
  onLaunch() {
    // 初始化塔库SDK
    const { initSDKWithConfig, setDebugMode } = uni.requireNativePlugin('moko-takuad')

    setDebugMode(true) // 开发时开启调试
    initSDKWithConfig('a62b013be01931', 'c3d0d2a9a9d451b07e62b509659f7c97')
  }
}

2. 广告加载时机

• 激励视频: 在可能展示的页面加载时提前加载
• 插屏广告: 在页面切换前加载
• 横幅广告: 在页面显示时加载
• 开屏广告: 应用启动时立即加载

3. 错误处理

始终检查广告状态再展示：

// 展示激励视频的安全方式
async function showReward() {
  try {
    if (!isRewardVideoReady()) {
      console.log('广告未准备好，开始加载...')
      loadRewardVideo()
      return
    }

    const success = showRewardVideo()
    if (success) {
      console.log('广告展示成功')
    } else {
      console.log('广告展示失败')
    }
  } catch (error) {
    console.error('展示广告时出错:', error)
  }
}

4. 场景统计使用

使用场景ID可以帮助优化广告变现：

// 不同场景使用不同的scenarioId
initRewardVideo('placement_id', 'level_complete') // 关卡完成
initRewardVideo('placement_id', 'daily_bonus')   // 每日奖励
initRewardVideo('placement_id', 'shop_discount') // 商店折扣

🐛 调试技巧

1. 开启调试模式

setDebugMode(true)

2. 查看日志

插件所有操作都会输出详细日志，以不同颜色标识：

• 成功操作
• 🔴 错误信息
• 警告信息

3. 常见问题排查

1. 广告不展示: 检查网络连接、广告位ID是否正确
2. 加载失败: 确认AppID和AppKey配置正确
3. 展示失败: 确保在主线程调用且广告已加载完成
4. 开屏广告卡住: 使用closeSplash()强制关闭
5. 页面变灰: 使用调试按钮查看容器状态，必要时刷新页面

4. 开屏广告特别说明

开屏广告具有特殊性，可能出现以下情况：

• 页面残留: 广告View未正确移除，使用closeSplash()
• 容器问题: 使用debugSplashContainer()查看详细信息
• 自动恢复: 插件会自动识别并移除广告相关View

📋 示例代码

完整的激励视频实现

<template>
  <view class="container">
    <button @click="initAd">初始化广告</button>
    <button @click="loadAd">加载广告</button>
    <button @click="showAd" :disabled="!isReady">展示广告</button>
    <text>广告状态: {{ isReady ? '已准备' : '未准备' }}</text>
  </view>
</template>

<script>
export default {
  data() {
    return {
      isReady: false,
      placementId: 'b62ecb800e1f84',
      scenarioId: 'demo'
    }
  },

  onLoad() {
    this.initAd()
  },

  onUnload() {
    // 页面销毁时清理资源
    const { destroyRewardVideo } = uni.requireNativePlugin('moko-takuad')
    destroyRewardVideo()
  },

  methods: {
    initAd() {
      const { initRewardVideo } = uni.requireNativePlugin('moko-takuad')
      initRewardVideo(this.placementId, this.scenarioId)

      // 初始化后开始加载
      setTimeout(() => {
        this.loadAd()
      }, 1000)
    },

    loadAd() {
      const { loadRewardVideo } = uni.requireNativePlugin('moko-takuad')
      loadRewardVideo('user123', 'extra_data')

      // 检查加载状态
      this.checkAdStatus()
    },

    showAd() {
      const { showRewardVideo } = uni.requireNativePlugin('moko-takuad')

      if (this.isReady) {
        const success = showRewardVideo()
        if (success) {
          console.log('激励视频展示成功')
          this.isReady = false

          // 展示后预加载下一个
          setTimeout(() => {
            this.loadAd()
          }, 2000)
        }
      }
    },

    checkAdStatus() {
      const { isRewardVideoReady } = uni.requireNativePlugin('moko-takuad')

      const timer = setInterval(() => {
        this.isReady = isRewardVideoReady()
        if (this.isReady) {
          clearInterval(timer)
          console.log('激励视频已准备好')
        }
      }, 1000)

      // 10秒后停止检查
      setTimeout(() => {
        clearInterval(timer)
      }, 10000)
    }
  }
}
</script>

📞 技术支持

• 塔库官网: https://www.takuad.com
• 开发者文档: https://docs.takuad.com
• 问题反馈: 通过塔库开发者平台提交工单

📄 许可证

本插件遵循 MIT 许可证开源协议。

版本: v1.0.0
更新时间: 2024年6月
兼容平台: Android (iOS 待开发)
UniApp版本要求: 3.0+