更新记录

1.0.0（2025-08-17）

更新日志

[1.0.0] - 2025-08-17

新增

平台兼容性

uni-app x(4.65)

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

其他

多语言 暗黑模式 宽屏模式
× × √

z-admob 使用说明

z-admob 是基于 Google AdMob SDK 的 UTS 插件，适配 uni-app X，支持横幅、插屏、激励、激励插屏、开屏广告的加载与展示。
插件提供了完整的生命周期回调，便于开发者进行广告事件追踪、奖励发放与错误处理。

📦 安装

在 manifest.json 中配置插件依赖，或通过 HBuilderX 插件市场安装。
使用前需要在 AdMob 控制台创建广告单元，并替换示例中的 adUnitId。

⚙️ 准备工作（重要）

在使用插件前，必须在 AndroidManifest.xml 和 Info.plist 中配置 AdMob App ID。
App ID 可在 Google AdMob 控制台 创建应用后获取。可选添加Z_ADMOB_AUTO_INIT相关配置，添加该配置后会自动调用initAdmob，否则需要在app lunch时手动调用。

Android

在 AndroidManifest.xml 中添加：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="uts.sdk.modules.zAdmob">

    <application>
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-3940256099942544~1458002511" />
        <meta-data
            android:name="Z_ADMOB_AUTO_INIT"
            android:value="true" />
    </application>

</manifest>

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>ca-app-pub-3940256099942544~1458002511</string>
        <key>SKAdNetworkItems</key>
        <array>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>cstr6suwn9.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>4fzdc2evr5.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>2fnua5tdw4.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>ydx93a7ass.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>p78axxw29g.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>v72qych5uu.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>ludvb6z3bs.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>cp8zw746q7.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>3sh42y64q3.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>c6k4g5qg8m.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>s39g8k73mm.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>3qy4746246.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>f38h382jlk.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>hs6bdukanm.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>mlmmfzh3r3.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>v4nxqhlyqp.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>wzmmz9fp6w.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>su67r6k2v3.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>yclnxrl5pm.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>t38b2kh725.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>7ug5zh24hu.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>gta9lk7p23.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>vutu7akeur.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>y5ghdn5j9k.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>v9wttpbfk9.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>n38lu8286q.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>47vhws6wlr.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>kbd757ywx3.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>9t245vhmpl.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>a2p9lx4jpn.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>22mmun2rn5.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>44jx6755aq.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>k674qkevps.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>4468km3ulz.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>2u9pt9hc89.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>8s468mfl3y.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>klf5c3l5u5.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>ppxm28t8ap.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>kbmxgpxpgc.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>uw77j35x4d.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>578prtvx9j.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>4dzt52r2t5.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>tl55sbb4fm.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>c3frkrj4fj.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>e5fvkxwrpn.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>8c4e2ghe7u.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>3rd42ekr43.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>97r2b46745.skadnetwork</string>
            </dict>
            <dict>
                <key>SKAdNetworkIdentifier</key>
                <string>3qcr597p9d.skadnetwork</string>
            </dict>
        </array>
        <key>Z_ADMOB_AUTO_INIT</key>
        <true/>
    </dict>
</plist>

🚀 API 列表

1. 横幅广告

export type ShowBannerAdRequest = {
  webViewElement?: UniElement
  adUnidId: String
}

export type ShowBannerAd = (request: ShowBannerAdRequest) => void

2. 开屏广告

export type LoadOpenAdRequest = {
  adUnitId: String
  success?: (ad: ZAdmobAd) => any
  fail?: (err: ZAdmobError) => any
}

export type LoadOpenAd = (request: LoadOpenAdRequest) => void

3. 插屏广告

export type LoadInterstitialAdRequest = {
  adUnitId: String
  success?: (ad: ZAdmobAd) => any
  fail?: (err: ZAdmobError) => any
}

export type LoadInterstitialAd = (request: LoadInterstitialAdRequest) => void

4. 激励广告

export type LoadRewardedAdRequest = {
  adUnitId: String
  customData?: String
  success?: (ad: ZAdmobAd) => any
  fail?: (err: ZAdmobError) => any
}

export type LoadRewardedAd = (request: LoadRewardedAdRequest) => void

5. 插页式激励广告

export type LoadRewardedInterstitialAdRequest = {
  adUnitId: String
  customData?: String
  success?: (ad: ZAdmobAd) => any
  fail?: (err: ZAdmobError) => any
}

export type LoadRewardedInterstitialAd = (request: LoadRewardedInterstitialAdRequest) => void

🔄 错误对象说明

export type ZAdmobError = {
  code?: Number
  message?: String
  domain?: String
  cause?: any
}

🎁 奖励对象说明

export type RewardWrapper = {
  rewardType: String
  rewardAmount: Number
}

📝 示例代码

<template>
    <view>
        <view class="bannerArea" id= "banner-test" @click="showBanner"></view>
        <button @click="interstitial">插屏广告</button>
        <button @click="reward">激励广告</button>
        <button @click="rewardInterstitial">插页式激励广告</button>
    </view>
</template> 

<script setup lang="uts">
    import {
        showBannerAd,
        ShowBannerAdRequest,
        loadInterstitialAd, 
        LoadInterstitialAdRequest, 
        showFullScreenAd, 
        ShowFullScreenAdRequest,
        loadRewardedAd,
        LoadRewardedAdRequest,
        LoadRewardedInterstitialAdRequest,
        loadRewardedInterstitialAd,
        ZAdmobAd,
        ZAdmobError
    } from "@/uni_modules/z-admob"

    function showBanner() {
        const element = uni.getElementById("banner-test")
        showBannerAd({webViewElement: element, adUnidId: "ca-app-pub-3940256099942544/9214589741"} as ShowBannerAdRequest)
    }

    function interstitial() {
        const request: LoadInterstitialAdRequest = {
            adUnitId: "ca-app-pub-3940256099942544/1033173712",
            success: function(ad) {
                const showRequest: ShowFullScreenAdRequest = {
                    ad: ad,
                    onFailed(err) {
                        console.log(err.code, err.message, err.domain)
                    },
                    onShow() {
                        console.log("------------------Show the ad------------------")
                    },
                    onClicked() {
                        console.log("------------------Click the ad------------------")
                    },
                    onImpression() {
                        console.log("------------------Impression the ad------------------")
                    },
                    onDismissed() {
                        console.log("------------------Dismissed the ad------------------")
                    },
                    onWillDismiss() {
                        console.log("------------------Will dimiss the ad------------------")
                    }
                } as ShowFullScreenAdRequest
                showFullScreenAd(showRequest)
            },
            fail: (err) => {
                console.log('插屏广告加载失败，错误原因：', err.message)
            }
        } as LoadInterstitialAdRequest
        loadInterstitialAd(request)
    }

    function reward() {
        const request: LoadRewardedAdRequest = {
            adUnitId: "ca-app-pub-3940256099942544/5224354917",
            success: ad => {
                console.log("加载激励广告成功！")
                const showRequest: ShowFullScreenAdRequest = {
                    ad: ad,
                    onShow: () => {
                        console.log("调用onShow")
                    },
                    onDismissed: () => {
                        console.log("调用onDismissed")
                    },
                    onFailed: (err) => {
                        console.log("展示激励广告失败，失败原因:", err.message)
                    },
                    onClicked: () => {
                        console.log("调用onClicked")
                    },
                    onImpression: () => {
                        console.log("调用onImpression")
                    },
                    onEarnedReward(rewardItem) {
                        console.log("Get reward, type is", rewardItem.rewardType, ", amount is", rewardItem.rewardAmount)
                    }
                } as ShowFullScreenAdRequest
                showFullScreenAd(showRequest)
            },
            fail: err => {
                console.log("激励视频加载失败，错误原因：", err.message)
            },
            customData: "test custom data"
        } as LoadRewardedAdRequest
        loadRewardedAd(request)
    }

    function rewardInterstitial() {
        const request: LoadRewardedInterstitialAdRequest = {
            adUnitId: "ca-app-pub-3940256099942544/6978759866",
            success: ad => {
                console.log("加载激励广告成功！")
                const showRequest: ShowFullScreenAdRequest = {
                    ad: ad,
                    onShow: () => {
                        console.log("调用onShow")
                    },
                    onDismissed: () => {
                        console.log("调用onDismissed")
                    },
                    onFailed: (err) => {
                        console.log("展示插页式激励广告失败，失败原因:", err.message)
                    },
                    onClicked: () => {
                        console.log("调用onClicked")
                    },
                    onImpression: () => {
                        console.log("调用onImpression")
                    },
                    onEarnedReward: (rewardItem) => {
                        console.log("获取奖励，type:", rewardItem.rewardType, ", amount:", rewardItem.rewardAmount)
                    }
                } as ShowFullScreenAdRequest
                showFullScreenAd(showRequest)
            },
            fail: err => {
                console.log("插页式激励视频加载失败，错误原因：", err.message)
            },
            customData: "test custom data aabbccdd"
        } as LoadRewardedInterstitialAdRequest
        loadRewardedInterstitialAd(request)
    }
</script>

<style>
    .logo {
        height: 100px;
        width: 100px;
        margin: 100px auto 25px auto;
    }

    .title {
        font-size: 18px;
        color: #8f8f94;
        text-align: center;
    }

    .bannerArea {
        height: 100px;
        width: 90%;
        background-color: cyan;
        align-self: center;
    }
</style>

隐私、权限声明

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

无

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

无

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

无

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

暂无用户评论。