ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

在 Flet 移动应用中集成 BannerAd 横幅广告:flet-ads 完整实战指南

在 Flet 移动应用中集成 BannerAd 横幅广告:flet-ads 完整实战指南 前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载导读BannerAd是 Flet 官方扩展包flet-ads提供的横幅广告控件让 Python 开发者无需编写任何 Flutter/原生代码即可在 Android 与 iOS 应用中接入 Google AdMob 横幅广告。本文以 website/docs/controls/ads/bannerad.md 为骨架结合 flet-ads 包源码、官方示例 与 Ads 总览文档完整讲解从安装配置、测试广告位、属性与事件回调到底层实现原理的整条链路。读完你将能在一个可运行的 Flet 移动应用中渲染横幅广告并正确响应其加载、点击、展示、计费等生命周期事件。平台支持与前置条件BannerAd由 Flutter 生态的 google_mobile_ads 包驱动因此其平台支持范围与原生 SDK 一致平台WindowsmacOSLinuxiOSAndroidWeb支持❌❌❌✅✅❌这一限制在源码层被显式强制BaseAd.before_update()中会检查page.web与page.platform.is_mobile()一旦在 Web 或非移动平台使用将抛出FletUnsupportedPlatformException见 sdk/python/packages/flet-ads/src/flet_ads/base_ad.py 中的before_update实现def before_update(self): super().before_update() if self.page.web or not self.page.platform.is_mobile(): raise ft.FletUnsupportedPlatformException( f{self.__class__.__name__} is only supported on fMobile (Android and iOS) )因此在 Web 端运行包含BannerAd的页面会直接抛异常合理做法是在 UI 层提前用page.web or not page.platform.is_mobile()禁用相关按钮官方示例正是如此详见下文。安装 flet-ads在项目依赖中加入flet-ads包README使用uvuv add flet-ads使用pippip install flet-ads注意pip安装后还需要手动将该包添加到requirements.txt或pyproject.toml中以保证打包发布时依赖完整。平台级配置AdMob 应用 ID在 Android 与 iOS 上必须为应用指定有效的 AdMob 应用 ID否则应用可能启动崩溃或行为异常。两种平台分别通过构建命令或pyproject.toml配置。Android使用flet build apk命令行flet build apk \ --android-meta-data com.google.android.gms.ads.APPLICATION_IDca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy或在pyproject.toml中声明[tool.flet.android.meta_data] com.google.android.gms.ads.APPLICATION_ID ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyyiOS使用flet build ipa命令行flet build ipa \ --info-plist GADApplicationIdentifierca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy或在pyproject.toml中声明[tool.flet.ios.info] GADApplicationIdentifier ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy相关权限设置可进一步参考 Android 发布文档 与 iOS 发布文档 中的 Permissions 小节。官方示例在页面中渲染 BannerAd仓库提供了完整的可运行示例 sdk/python/examples/extensions/ads/banner_ad_and_interstitial_ad/main.py其中演示了BannerAd与InterstitialAd的配合使用。核心的横幅广告部分如下import flet as ft import flet_ads as fta # Test ad unit IDs ids { ft.PagePlatform.ANDROID: { banner: ca-app-pub-3940256099942544/6300978111, interstitial: ca-app-pub-3940256099942544/1033173712, }, ft.PagePlatform.IOS: { banner: ca-app-pub-3940256099942544/2934735716, interstitial: ca-app-pub-3940256099942544/4411468910, }, } def get_new_banner_ad() - fta.BannerAd: return fta.BannerAd( unit_idids[page.platform][banner], width320, height50, on_clicklambda e: print(BannerAd clicked), on_loadlambda e: print(BannerAd loaded), on_errorlambda e: print(BannerAd error, e.data), on_openlambda e: print(BannerAd opened), on_closelambda e: print(BannerAd closed), on_impressionlambda e: print(BannerAd impression), on_will_dismisslambda e: print(BannerAd will dismiss), ) def main(page: ft.Page): page.appbar ft.AppBar( adaptiveTrue, titleMobile Ads Playground, bgcolorft.Colors.LIGHT_BLUE_300, ) page.horizontal_alignment ft.CrossAxisAlignment.CENTER page.scroll ft.ScrollMode.AUTO page.add( ft.SafeArea( contentft.Column( controls[ ft.OutlinedButton( contentShow BannerAd, on_clicklambda e: page.add(get_new_banner_ad()), disabledpage.web or not page.platform.is_mobile(), # mobile only ), ] ) ), ) if __name__ __main__: ft.run(main)要点解读按平台取广告位 ID通过ids[page.platform]区分 Android 与 iOS 的unit_id两个平台使用各自的测试广告位。动态添加广告点击按钮后通过page.add(get_new_banner_ad())将横幅广告作为普通控件加入页面——BannerAd是ft.LayoutControl的子类参与 Flet 常规布局。移动端守卫按钮的disabled绑定page.web or not page.platform.is_mobile()在 Web/桌面端禁用入口避免触发平台异常。BannerAd 类与属性详解类定义与继承关系BannerAd定义在 sdk/python/packages/flet-ads/src/flet_ads/banner_ad.pyft.control(BannerAd) class BannerAd(ft.LayoutControl, BaseAd):它同时继承ft.LayoutControl因此拥有width、height等布局属性与BaseAd广告公共能力。BaseAd位于 sdk/python/packages/flet-ads/src/flet_ads/base_ad.py是InterstitialAd等其他广告控件共享的基类。继承自 BaseAd 的公共属性属性类型说明unit_idstr必填该广告的广告单元 IDAd unit IDrequestAdRequest用于获取广告的定向信息默认AdRequest()on_load事件处理器广告加载成功时触发on_error事件处理器广告请求失败时触发e.data携带错误信息on_open事件处理器广告被点击、全屏视图/浮层展示时触发建议在此暂停动画与时间敏感交互on_close事件处理器全屏视图关闭时触发应恢复在on_open中暂停的一切操作on_impression事件处理器广告产生展示impression时触发on_click事件处理器广告被点击时触发BannerAd 专属属性属性说明on_will_dismiss全屏视图即将关闭前触发。仅 iOS 可用on_paid当该广告预估产生收益时触发事件数据为PaidAdEvent。仅对 AdMob 白名单账户开放布局属性由于继承自LayoutControl示例中使用width320、height50指定横幅广告的标准尺寸对应 AdMob 的AdSize.banner320×50。AdRequest广告请求定向参数AdRequest用于向 AdMob 传递定向信息定义在 sdk/python/packages/flet-ads/src/flet_ads/types.py其字段镜像原生 AdMobAdRequest.BuilderAPI字段类型说明keywordslist[str] \| None描述当前用户活动的关键词或短语content_urlstr \| None与 App 主要内容匹配的网页 URL用于定向与品牌安全neighboring_content_urlslist[str] \| None广告附近网页内容的 URLnon_personalized_adsbool \| None是否请求非个性化广告不基于用户过往行为http_timeoutint \| None广告请求中 HTTPS 调用的自定义超时毫秒。仅 Android 支持iOS 忽略extrasdict[str, str] \| None传递给 AdMob adapter 的附加参数用法示例from flet_ads import AdRequest, BannerAd banner BannerAd( unit_idca-app-pub-xxxxxxxxxxxxxxxx/yyyyyyyyyy, width320, height50, requestAdRequest( keywords[gaming, puzzle], non_personalized_adsFalse, content_urlhttps://example.com, ), )从源码实现看AdRequest的字段会原样映射到 Flutter 原生AdRequestDart 端parseAdRequest见 sdk/python/packages/flet-ads/src/flutter/flet_ads/lib/utils/ads.dart将 Python 侧的content_url、non_personalized_ads、http_timeout等字段一一映射为contentUrl、nonPersonalizedAds、httpTimeoutMillis等原生参数。on_paid 事件与 PaidAdEventon_paid回调携带PaidAdEvent数据同样定义于 types.pydataclass class PaidAdEvent(ft.Event[ft.EventControlType]): value: float # 广告的货币价值 precision: PrecisionType # 价值的精度 currency_code: str # 货币代码PrecisionType枚举取值包括UNKNOWN未知精度的广告价值ESTIMATED根据聚合数据估算的价值PUBLISHER_PROVIDED发布商提供的价值如中介组中的手动 CPMPRECISE该广告的精确支付价值Dart 端在onPaidEvent中会将value微单位、precision、currency_code打包为paid事件回传见 banner.dart。测试广告位 IDTest ValuesAdMob 官方提供用于测试的 App ID 与广告单元 ID。测试 ID 严禁用于生产环境AdMob 测试 App IDca-app-pub-3940256099942544~3347511713BannerAd.unit_idAndroidca-app-pub-3940256099942544/9214589741BannerAd.unit_idiOSca-app-pub-3940256099942544/2435281174InterstitialAd.unit_idAndroidca-app-pub-3940256099942544/1033173712InterstitialAd.unit_idiOSca-app-pub-3940256099942544/4411468910注意上述 BannerAd 测试 ID 是文档bannerad.md中标注的官方标准测试值而 官方示例 main.py 中使用的 Banner 测试 ID 是ca-app-pub-3940256099942544/6300978111Android与ca-app-pub-3940256099942544/2934735716iOS——两者均为 AdMob 测试位开发时可直接复制示例中的取值。底层实现Flutter 端的 BannerAd 渲染理解 Python 控件背后发生了什么有助于排查问题。Dart 端实现位于 sdk/python/packages/flet-ads/src/flutter/flet_ads/lib/src/banner.dart核心逻辑从控件属性读取unit_id缺省时回退到测试 ID与request解析为原生AdRequest使用AdSize.banner创建原生BannerAd注册BannerAdListener各原生回调经widget.control.triggerEvent(...)映射回 Python 事件onAdLoaded → load、onAdFailedToLoad → error携带错误字符串、onAdOpened → open、onAdClosed → close、onAdClicked → click、onAdWillDismissScreen → will_dismiss、onPaidEvent → paid、onAdImpression → impression广告加载失败时立即ad.dispose()释放资源并保持_isLoaded false成功后通过AdWidget包裹渲染为 Flet 的LayoutControl参与常规布局。这也解释了 Python 侧事件名的来源on_will_dismiss对应原生onAdWillDismissScreen而on_paid的value来自原生回调中的valueMicros微单位计价值。与 ConsentManager 的协作补充横幅广告通常与 Google 用户信息平台UMP的同意流程配合使用详见 Ads 总览文档 的 Consent 章节与 ConsentManager 控件文档。核心要点同意消息在 AdMob 控制台创建发布而非在代码中应用仅负责请求更新并在需要时展示表单ConsentStatus表示是否已收集到决定而非用户选择了什么——用户无论同意或拒绝状态都会变为OBTAINED是否允许请求广告应使用ConsentManager.can_request_ads()判断开发阶段可通过DebugGeographyConsentDebugSettings强制模拟 EEA 等地区的同意流程模拟器/仿真器自动注册为测试设备真机需先从原生日志读取设备哈希 ID 加入test_identifiers。常见注意事项平台限制BannerAd仅支持 Android 与 iOS在 Web/桌面端使用会抛FletUnsupportedPlatformException应在 UI 上提前禁用入口。必填unit_id该属性无默认值必须显式提供Dart 端虽有测试 ID 兜底但生产环境务必替换为自己的正式广告位。测试 ID 勿上生产测试广告位不会产生真实收益且可能违反 AdMob 政策。on_will_dismiss仅 iOSAndroid 端不会触发该事件。on_paid有门槛该回调仅对 AdMob 白名单账户可用。失败自动释放广告加载失败后原生实例会被 dispose控件保持未加载状态等待下一次重建/重试。http_timeout仅 AndroidiOS 端该参数被忽略。同意合规面向 EEA/受监管地区用户发布时应先完成 UMP 同意流程再请求广告避免违规。延伸阅读Ads 控件总览与平台配置InterstitialAd 插屏广告BaseAd 基类 APIConsentManager 同意管理flet-ads 包 README 与安装说明完整示例banner_ad_and_interstitial_ad/main.py赞分享前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载相关推荐Flet 广告集成实战指南使用 flet-ads 在移动应用中接入 Google AdMobFlet 广告集成实战指南使用 flet ads 在移动应用中接入 Google AdMob 本文是基于 flet ads 包的完整技术指南。flet ads前端跨平台桌面应用移动开发flet-ads 从 0.1.0 到 0.86.0在 Flet 移动应用中集成 Google Ads 与 UMP 用户同意管理flet ads 从 0.1.0 到 0.86.0在 Flet 移动应用中集成 Google Ads 与 UMP 用户同意管理 flet ads 是 Flet前端跨平台桌面应用移动开发Google Mobile Ads Next-Gen 安卓横幅广告集成指南Android Banner AdsGoogle Mobile Ads Next Gen 安卓横幅广告集成指南Android Banner Ads 导读 本文基于 skills/ads/gooAI 技能人工智能大模型创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表