更新记录

1.0.0（2026-09-17）

首个版本：

• 支持激励视频、插屏广告、插屏式激励视频、开屏广告（仅 iOS）与 Banner 横幅组件
• Android 端为纯 UTS 实现（三方依赖走 config.json 的 Maven dependencies），iOS 端为 UTS + Swift 混编，随包 GoogleMobileAds 12.11.0

平台兼容性

uni-app(3.99)

admob-uts（Google AdMob 广告插件 UTS 版）

Google AdMob 广告插件，支持 激励视频、插屏广告、插屏式激励视频、开屏广告（仅 iOS） 与 Banner 横幅组件，Android / iOS 双端。

本插件为完全明文源码，不做任何加密（package.json 中 uni_modules.encrypt 为空数组，插件目录内也不存在 encrypt 文件），可自由二次开发。

一、能力一览

三、接入前配置

调试原生插件必须使用自定义基座。

1. 配置 App ID

iOS：项目根目录新建 Info.plist（注意大小写）

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>GADApplicationIdentifier</key>
    <string>这里填写你应用 iOS 的 APPID</string>
  </dict>
</plist>

Android：项目根目录新建 AndroidManifest.xml（注意大小写）

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools"
  package="io.dcloud.nativeresouce">
    <application>
        <meta-data android:name="com.google.android.gms.ads.APPLICATION_ID" android:value="这里填写你应用安卓的APPID"/>
    </application>
</manifest>

2. 引用插件

import {
    loadAppOpenAD,
    showAppOpenAD,
    loadRewardedAd,
    showRewardedAd,
    loadInterstitialAd,
    showInterstitialAd,
    loadRewardedInterstitialAd,
    showRewardedInterstitialAd
} from '@/uni_modules/admob-uts'

3. 注意

插件测试过程中，请按谷歌要求使用测试广告位 ID 进行测试，以免账号被封停：

四、回调数据格式

所有回调均为 JSON 字符串：

{
    "errorCode": 0,
    "code": 100,
    "msg": "激励视频加载成功",
    "data": {}
}

事件码：

load* 方法只要 errorCode == 0 即代表加载完成，可以调用对应的 show* 播放； show* 方法在广告播放过程中会持续回调（曝光 / 点击 / 关闭 / 激励发放）。

五、API 说明

5.1 激励视频

loadRewardedAd({
    adid: 'ca-app-pub-3940256099942544/5224354917'
}, res => {
    const resJson = JSON.parse(res)
    if (resJson.errorCode == 0) {
        console.log('广告 load 完成，可以播放')
    } else {
        console.log('广告 load 失败：' + resJson.msg)
    }
})

// 加载成功后播放；customData 会在激励发放时原样返回
showRewardedAd({
    adid: 'ca-app-pub-3940256099942544/5224354917',
    customData: '123'
}, res => {
    const resJson = JSON.parse(res)
    if (resJson.code == 105) {
        // 激励发放，此时才可给用户发放奖励
        console.log('奖励发放', resJson.data)
    }
})

5.2 插屏广告

loadInterstitialAd({
    adid: 'ca-app-pub-3940256099942544/1033173712'
}, res => {
    console.log('插屏加载进度更新 = ' + res)
})

showInterstitialAd({
    adid: 'ca-app-pub-3940256099942544/1033173712'
}, res => {
    console.log('插屏播放进度更新 = ' + res)
})

5.3 插屏式激励视频

loadRewardedInterstitialAd({
    adid: 'ca-app-pub-3940256099942544/5354046379'
}, res => {
    console.log('插屏式激励视频加载进度更新 = ' + res)
})

showRewardedInterstitialAd({
    adid: 'ca-app-pub-3940256099942544/5354046379',
    customData: '123'
}, res => {
    console.log('插屏式激励视频播放进度更新 = ' + res)
})

5.4 开屏广告（仅 iOS）

loadAppOpenAD({
    adid: 'ca-app-pub-3940256099942544/5575463023'
}, res => {
    console.log('开屏广告加载进度更新 = ' + res)
})

showAppOpenAD({
    adid: 'ca-app-pub-3940256099942544/5575463023'
}, res => {
    console.log('开屏广告播放进度更新 = ' + res)
})

5.5 辅助方法

import { isAdReady, resetAd } from '@/uni_modules/admob-uts'

isAdReady('rewarded')   // 是否有已加载待播放的激励视频
resetAd('rewarded')     // 清空已缓存的激励视频（切换广告位 ID 时使用）

format 取值：rewarded / interstitial / rewardedInterstitial / appOpen。

5.6 Banner 横幅广告

Banner 为原生组件，仅支持 nvue / uvue 页面。

<admob-banner ref="admobBanner" @eventCallBack="eventCallBack"
    style="width:375px;height:100px;background-color:aqua;"></admob-banner>

// 加载广告：参数为（广告位 ID, 宽, 高），宽高单位为 px，需与 style 中保持一致
this.$refs['admobBanner'].loadAD('ca-app-pub-3940256099942544/9214589741', 375, 100)

eventCallBack(res) {
    console.log(res.detail) // JSON 字符串，与上述回调格式一致
}

Banner 事件码沿用统一事件码（100 加载成功、101 曝光、102 点击、103 关闭、104 加载失败、105 打开、106 滑动点击）， 其中 105/106 仅 Banner 组件会产生。

六、常见问题

• xxx not found：先确认 @/uni_modules/admob-uts 路径正确，且已使用自定义基座（标准基座不含本插件）。

• 加载失败且 msg 提示 Application ID 缺失：检查项目根目录的 AndroidManifest.xml / Info.plist 是否配置了 App ID。

• 当前无可用 Activity（Android）：请勿在 onLaunch 阶段立即调用，等页面 onReady 之后再调用。

• 激励视频没有回调 code == 105：用户未完整观看（提前关闭）时不会发放奖励，属正常行为；请仅在 105 时发放奖励。

• 报 callback回调函数已释放，不能再次执行（两端都可能）： HBuilderX 4.25 起，UTS 插件导出方法里的回调参数改为「触发一次后立即自动回收」。 本插件的回调天然要触发多次（107 已展示 → 101 曝光 → 102 点击 → 105 激励发放 → 103 关闭）， 所以两端实现里的导出方法都带了 @UTSJS.keepAlive 装饰器 （官方文档）。 改动代码时不要删这个装饰器，也不要把 export function 改回 export const xxx: AdMobLoad = ... —— 装饰器不支持那种导出写法。注意 app-android / app-ios 两端都要配，少一端就会在那一端复现。 该装饰器会让回调常驻内存，因此请勿高频调用 load/show（按需加载即可）。

• Android 报「激励视频加载异常」：所有 SDK 调用都已切到主线程 （UTSAndroid.getDispatcher("main").async(...)，Google Mobile Ads SDK 要求在主线程初始化）。 若仍失败，用 adb logcat | grep admob-uts 看完整异常堆栈 —— 详情只写日志、不放回调文案， 因为 UTS 里 catch (e) 的 e 是 any，不能取属性、也不能参与字符串拼接。

• iOS 报 激励视频加载失败…：Request Error: Invalid request.（先别改代码，八成不是代码问题）： iOS 实现会把诊断信息一起回给 JS（adUnitId / appId / initStatus / netProbe / sdklog），照着看即可：

  • netProbe: googleads.g.doubleclick.net=失败(TLS错误导致安全连接失败。) ⇒ 设备网络连不上 Google 广告服务，SDK 拉不到初始化配置 （initStatus 里 GADMobileAds 会是 Not Ready: Could not retrieve application configuration data.）， 请求在本地就被判为无效。此时 detail 里的 Response ID 必然是 (null)、Adapter Response 为空。 修法在网络层（开代理 / 换网络），与本插件代码、广告位、App ID 都无关。
  • 中国大陆网络环境下 iOS 端 AdMob 无法稳定变现（TLS 会被阻断）， 面向国内用户的 App 建议 iOS 走国内广告联盟，或只对可访问 Google 的地区投放。
  • appId= 显示 (未配置) ⇒ 基座里的 Info.plist 没生效；initStatus 里出现 Not Ready ⇒ 初始化没成功。
  • sdklog 字段是用 OSLogStore 读本进程 os_log（iOS 15+）拿到的 Google SDK 自身日志 —— 这些行默认只在 Xcode/设备日志里，这样就能直接在 HBuilderX 控制台看到。
  • 广告位必须按平台取：iOS 与 Android 的测试广告位不通用（见上文对照表）， 两端不要共用一个常量；经典 uni-app 的 vue 服务层里 #ifdef APP-IOS 不生效， 要用 uni.getSystemInfoSync().platform 做运行时判断。