更新记录

1.0.0（2026-01-20）

  • chore: 插件 id 调整为 hans-admob-banner（上传校验仅保留一个同名组件）
  • feat: AdMob initialize (Android/iOS)
  • feat: banner component (Android/iOS)
  • feat: Anchored Adaptive Banner（支持自适应高度 + resize 回调）
  • feat: setLogEnabled/isLogEnabled for plugin logs（默认开启）

平台兼容性

uni-app x(4.87)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - √ √ - -

hans-admob-banner

UTS 插件：Google AdMob 初始化 + Banner（支持标准 Banner / Anchored Adaptive Banner）。

平台支持

  • 仅支持 uni-app x App 端
  • Android：支持
  • iOS：支持
  • HarmonyOS：不支持（会回调错误）

依赖版本要求

  • HBuilderX：>= 4.31（native-view 标准组件要求）
  • Android：minSdkVersion 21
  • iOS：deploymentTarget 12

功能

  • initialize()：初始化 Google Mobile Ads SDK（Android/iOS）
  • hans-admob-banner：Banner 组件
    • 标准 Banner：固定 50px
    • Anchored Adaptive Banner：高度自适应 + resize 回调
  • setLogEnabled() / isLogEnabled()：插件日志开关（默认开启）

安装与配置

安装

  • 将插件目录 uni_modules/hans-admob-banner 放到你的项目 uni_modules/ 下（从插件市场安装也会自动放到这里）
  • 在 App 启动阶段调用一次 initialize()（推荐）
  • 页面中按需使用 <hans-admob-banner />

Android

  • 依赖：已在 utssdk/app-android/config.json 声明 play-services-ads（当前：com.google.android.gms:play-services-ads:22.6.0）
  • 必须配置 App ID：com.google.android.gms.ads.APPLICATION_ID
    • 方式 A（推荐，项目级覆盖）：在项目根目录创建 nativeResources/android/AndroidManifest.xml，添加同名 <meta-data ... />
    • 方式 B（直接修改插件文件）：修改 utssdk/app-android/AndroidManifest.xml
    • 当前插件内默认值为 AdMob 官方 Test App ID（可直接用于联调；发布前务必替换为你的 App ID）

示例（项目级覆盖）：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <application>
    <meta-data
      android:name="com.google.android.gms.ads.APPLICATION_ID"
      android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy" />
  </application>
</manifest>

iOS

  • 依赖：已在 utssdk/app-ios/config.json 声明 CocoaPods Google-Mobile-Ads-SDK（当前：11.1.0）
    • 需要 macOS + CocoaPods；HBuilderX 首次运行到 iOS 会自动安装 pods
  • 必须配置 App ID：GADApplicationIdentifier
    • 方式 A（推荐，项目级覆盖）：在项目根目录创建 nativeResources/ios/Info.plist 并添加 GADApplicationIdentifier
    • 方式 B（直接修改插件文件）：修改 utssdk/app-ios/Info.plist
    • 当前插件内默认值为 AdMob 官方 Test App ID（可直接用于联调；发布前务必替换为你的 App ID）

示例（项目级覆盖）：

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

iOS（可选）ATT/隐私弹窗

  • 本插件不包含 ATT 请求逻辑；如你需要基于 IDFA 投放/归因，请自行在业务侧申请 ATT，并在 Info.plist 添加文案：
<key>NSUserTrackingUsageDescription</key>
<string>用于向你展示更相关的广告</string>

API

initialize(options)

  • success：初始化成功回调
  • fail：失败回调（AdmobFail：errCode + errMsg）
  • complete：完成回调

setLogEnabled(enabled) / isLogEnabled()

  • 默认 enabled=true

用法

1) 初始化

import { initialize } from '@/uni_modules/hans-admob-banner'

initialize({
  success: () => console.log('init success'),
  fail: (err) => console.log(err.errCode, err.errMsg)
})

说明：

  • 组件内部也会在加载前确保初始化；但建议在 App 启动阶段先调用一次 initialize()，便于尽早暴露配置问题。

0) 插件日志（默认开启）

import { setLogEnabled } from '@/uni_modules/hans-admob-banner'

// 关闭日志：
setLogEnabled(false)

2) Banner 组件（支持自适应高度）

<template>
  <hans-admob-banner
    adUnitId="ca-app-pub-3940256099942544/6300978111"
    :adaptive="true"
    @load="() => console.log('banner loaded')"
    @error="(e) => console.log(e.errCode, e.errMsg)"
    @resize="(s) => console.log('banner size', s.width, s.height)"
  />
</template>

说明：

  • adaptive=true 会启用 Anchored Adaptive Banner（高度可能不是 50px）。
  • 自适应模式下不要给组件写死 height: 50px，否则可能裁切。
  • Android/iOS 的 Ad Unit ID 不同；请按平台分别配置。

示例（按平台选择 ID）：

let bannerAdUnitId = 'android-ad-unit-id'
// #ifdef APP-IOS
bannerAdUnitId = 'ios-ad-unit-id'
// #endif

组件参数与事件

Props

  • adUnitId: string（必填）Banner 广告单元 ID
  • adaptive?: boolean（可选，默认 false）是否启用 Anchored Adaptive Banner

Events

  • load：加载成功
  • error：加载失败（AdmobFail）
  • resize：尺寸变化（AdmobBannerSize：{ width, height }）

错误码

  • 9011001：not initialized
  • 9011002：missing AdMob app id
  • 9011003：invalid ad unit id
  • 9011004：banner load failed
  • 9011099：unknown / not supported（HarmonyOS）

常见问题（FAQ）

  • iOS 初始化失败 9011002：检查 GADApplicationIdentifier 是否已写入最终打包的主工程 Info.plist
  • Android 初始化失败 9011002：检查 com.google.android.gms.ads.APPLICATION_ID 是否已写入最终打包的主工程 AndroidManifest.xml
  • Banner 不展示：确认使用的是对应平台的 Banner Ad Unit ID（Android/iOS 不同），并在真机环境测试
  • CocoaPods 安装失败：确认已安装 CocoaPods，且 HBuilderX 可正常执行 pod install

发布前检查

  • 替换 Android/iOS 的 App ID（不要使用官方 Test App ID）
  • 替换页面/组件里的 Ad Unit ID（不要使用官方 Test Ad Unit ID）
  • 真机验证 Android + iOS：初始化成功、Banner 展示、resize 回调符合预期

隐私与合规提示

  • 本插件仅封装 Google Mobile Ads SDK 的初始化与 Banner；不包含同意管理（UMP）/ATT 请求逻辑
  • 上架与投放请自行遵守 Google 与平台政策；数据采集/权限以 Google Mobile Ads SDK 实际行为为准

AdMob 测试 ID（官方）

  • Android Test App ID：ca-app-pub-3940256099942544~3347511713
  • iOS Test App ID：ca-app-pub-3940256099942544~1458002511
  • Android Banner Test Ad Unit ID：ca-app-pub-3940256099942544/6300978111
  • iOS Banner Test Ad Unit ID：ca-app-pub-3940256099942544/2934735716

隐私、权限声明

1. 本插件需要申请的系统权限列表：

Android：INTERNET、ACCESS_NETWORK_STATE（插件 manifest 已声明）；iOS：如需 ATT 请自行添加 NSUserTrackingUsageDescription。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

可能涉及广告相关数据（例如设备信息、广告标识符、IP 等），具体以 Google Mobile Ads SDK 与 AdMob 后台配置为准。

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

集成 Google AdMob（Google Mobile Ads SDK），用于展示 Banner 广告。

评论列表 撰写评论 向官方投诉

暂无用户评论。