更新记录

1.0.1（2025-06-25）

更新日志

v1.0.1 (2024-06-25)

平台兼容性

云端兼容性

uni-app(4.66)

uni-app x(4.62)

塔库广告 SDK UniApp UTS 插件

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

🚀 功能特性

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

📦 安装配置

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. 初始化激励视频

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

initRewardVideo('你的激励视频广告位ID', 'demo')

2. 加载广告

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

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

3. 检查广告状态

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

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

4. 展示广告

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

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

5. 销毁广告

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

destroyRewardVideo()

插屏广告

1. 初始化插屏广告

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