更新记录

1.0.8（2026-04-17）

支持更多广告平台

平台兼容性

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+

更新日志

v1.0.6 (2025-06-29)

• 增强：所有广告回调函数现在支持 AdInfo 参数，提供详细的广告平台信息
• 优化：可获取广告平台ID、名称、价格、广告源ID等详细信息

v1.0.5 (2025-06-28)

• 新增：插屏广告和横幅广告完整回调支持
• 优化：统一所有广告类型的回调机制

v1.0.4 (2025-06-27)

• 修复：UTS兼容性问题，优化回调函数参数处理

v1.0.3 (2025-06-26)

• 修复：UTS兼容性问题，修正回调函数参数类型

v1.0.2 (2025-06-25)

• 新增：激励视频广告完整回调支持
• 优化：回调机制，支持播放开始、结束、失败等事件

v1.0.1 (2025-06-24)

• 修复：开屏广告View销毁问题
• 新增：强制关闭开屏广告功能
• 新增：开屏广告容器调试功能

v1.0.0 (2025-06-23)

• 首次发布
• 支持激励视频、插屏、横幅、开屏广告
• 支持广告初始化、加载、显示等基本功能

广告回调信息

所有广告回调现在都包含 adInfo 参数，提供丰富的广告平台信息：

// 广告信息数据结构
interface AdInfo {
    // 基础信息
    id?: string;                 // 广告展示ID
    placementId?: string;        // 广告位ID

    // 广告平台信息
    networkFirmId?: string;      // 广告平台ID
    networkName?: string;        // 广告平台名称
    networkPlacementId?: string; // 广告平台的广告位ID
    networkType?: string;        // Network类型，如"Network"、"Cross_Promotion"、"Adx"

    // 广告源信息
    adsourceId?: string;         // 广告源ID
    adsourceIndex?: string;      // 当前广告源在WaterFall中的排序
    isHeaderBidding?: boolean;   // 是否为头部竞价的广告源
    bidType?: string;            // 广告源竞价类型，0：常规源；1：S2S；2：C2S
    bidFloor?: number;           // Taku后台配置竞价广告源竞价底价

    // 广告类型信息
    adFormat?: string;           // 广告类型，如"RewardedVideo"、"Banner"等
    adSourceAdType?: string;     // 当前广告源广告类型

    // 价格和收益信息
    price?: number;              // 广告价格
    ecpm?: number;               // Taku预估eCPM
    ecpmLevel?: string;          // 广告源的eCPM层级
    ecpmPrecision?: string;      // eCPM精度
    currency?: string;           // 货币类型
    publisherRevenue?: number;   // Taku广告位展示收益

    // 地区信息
    country?: string;            // 国家代码

    // 场景和分组信息
    scenarioId?: string;         // 广告场景ID
    scenarioRewardName?: string; // 广告场景的激励名称
    scenarioRewardNumber?: string; // 广告场景的激励数量
    segmentId?: string;          // 流量分组ID

    // 渠道信息
    channel?: string;            // 渠道信息
    subChannel?: string;         // 子渠道信息

    // AB测试信息
    abTestId?: string;           // AB测试ID

    // 广告位类型
    placementType?: string;      // 广告位类型，1：真实广告位，2：共享广告位
    sharedPlacementId?: string;  // 共享广告位id

    // 关闭类型
    dismissType?: string;        // 广告关闭类型

    // 自定义参数
    adSourceCustomExt?: string;  // 在Taku后台广告源配置的自定义参数
    showCustomExt?: string;      // 展示时传入的自定义参数
    customRule?: string;         // Placement+App维度的自定义规则

    // 加密信息
    encEcpmInfo?: string;        // 加密后的ecpm信息
    secretId?: string;           // 解密ecpm信息的私钥id

    // Adx、OnlineAPI等特殊信息
    offerId?: string;            // Adx、OnlineAPI Offer的广告ID
    creativeId?: string;         // Adx、OnlineAPI Offer的素材ID
    isDeeplinkOffer?: boolean;   // 是否为Deeplink或JumpURL的单子
    baiduEncryptedPrice?: string; // 百度c2s加密的价格

    // 额外信息标记
    hasExtInfo?: boolean;        // 是否有扩展信息
    hasLocalExtra?: boolean;     // 是否有本地传入参数

    // 用户自定义数据
    userId?: string;             // 用户ID
    userCustomData?: string;     // 用户自定义数据
}

常用字段说明

使用示例

// 设置激励视频回调
takuad.setRewardVideoCallbacks(
  (adInfo) => {
    console.log('激励视频开始播放', adInfo)
    // 获取广告平台信息
    if (adInfo) {
      console.log(`广告平台: ${adInfo.networkName || adInfo.networkFirmId}`)
      console.log(`广告源ID: ${adInfo.adsourceId}`)
      console.log(`是否头部竞价: ${adInfo.isHeaderBidding ? '是' : '否'}`)
    }
  },
  (adInfo) => {
    console.log('激励视频播放结束', adInfo)
  },
  (error, adInfo) => {
    console.log('激励视频播放失败', error, adInfo)
  },
  (adInfo) => {
    console.log('激励视频关闭', adInfo)
  },
  (adInfo) => {
    console.log('激励视频被点击', adInfo)
  },
  (adInfo) => {
    console.log('激励视频奖励发放', adInfo)
    // 获取广告价格和收益信息
    if (adInfo) {
      console.log(`广告价格: ${adInfo.price} ${adInfo.currency}`)
      console.log(`广告收益: ${adInfo.publisherRevenue} ${adInfo.currency}`)
      console.log(`eCPM精度: ${adInfo.ecpmPrecision}`)
    }
  }
)

高级用法：数据分析

// 广告平台统计
let platformStats = {};

function recordAdImpression(adInfo) {
  if (!adInfo || !adInfo.networkFirmId) return;

  const platformId = adInfo.networkFirmId;
  if (!platformStats[platformId]) {
    platformStats[platformId] = {
      name: adInfo.networkName || `平台${platformId}`,
      impressions: 0,
      clicks: 0,
      revenue: 0
    };
  }

  // 记录展示
  platformStats[platformId].impressions++;

  // 记录收益
  if (adInfo.publisherRevenue) {
    platformStats[platformId].revenue += adInfo.publisherRevenue;
  }
}

function recordAdClick(adInfo) {
  if (!adInfo || !adInfo.networkFirmId) return;

  const platformId = adInfo.networkFirmId;
  if (platformStats[platformId]) {
    platformStats[platformId].clicks++;
  }
}

// 在回调中使用
takuad.setRewardVideoCallbacks(
  (adInfo) => { /* 开始播放 */ },
  (adInfo) => { /* 播放结束 */ },
  (error, adInfo) => { /* 播放失败 */ },
  (adInfo) => { /* 广告关闭 */ },
  (adInfo) => {
    // 广告被点击
    recordAdClick(adInfo);
  },
  (adInfo) => {
    // 奖励发放
    recordAdImpression(adInfo);

    // 输出当前统计
    console.log('广告平台统计:', platformStats);
  }
);