--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://ads.yandex.com/helpcenter/en/dev/flutter/adaptive-inline-banner.md - https://ads.yandex.com/helpcenter/ru/dev/flutter/adaptive-inline-banner.md - https://ads.yandex.com/helpcenter/zh/dev/flutter/adaptive-inline-banner.md - href: zh/dev/flutter/adaptive-inline-banner.md type: text/markdown title: Markdown version - href: llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt # 自适应内嵌横幅广告 自适应内嵌横幅广告是一种灵活的横幅广告格式，通过针对每台设备优化广告尺寸，确保投放效果达到最优。 借助这种广告类型，开发者可设置广告允许的最大宽度和高度，系统将自动确定最佳广告尺寸。为了选择最佳广告尺寸，自适应内嵌横幅广告采用最大高度而非固定高度，这有助于提升广告表现。 通常，这种格式用于信息流型应用或可让用户注意力主要集中在广告上的场景。 {% cut "外观" %} {% endcut %} 本指南涵盖将自适应内嵌横幅广告集成到 Flutter 应用中的过程。 除了代码示例和说明之外，该指南还包含特定格式的建议以及其他资源的链接。 ## 前提条件 {#pre} 1. 按照 [快速入门](https://ads.yandex.com/helpcenter/zh/dev/flutter/quick-start.md) 中的流程集成 Yandex Mobile Ads Flutter 插件。 2. 确保您运行的是最新的 [Yandex Mobile Ads Flutter 插件](https://ads.yandex.com/helpcenter/zh/dev/platforms.md) 版本。如果您使用聚合，请确保您运行的是最新版本的 [统一构建](https://ads.yandex.com/helpcenter/zh/dev/platforms.md)。 ## 实施 {#implement} 集成自适应内嵌横幅广告的主要步骤： * 创建并配置用于显示横幅广告的小部件。 * 设置广告生命周期事件的回调函数。 * 加载广告。 ## 自适应内嵌横幅广告集成的具体细节 {#features} 1.如果 `onAdFailedToLoad()` 回调返回错误，请勿尝试再次加载新广告。如果没有其他选择，请限制广告加载重试次数。这有助于避免因资源限制而导致的持续请求失败和连接问题。 2.为了使自适应内嵌横幅广告正常运行，请[将您的应用布局设置为自适应](https://docs.flutter.dev/ui/layout/building-adaptive-apps)。否则，您的广告可能无法正确显示。 3.自适应内嵌横幅广告在充分利用可用宽度时效果最佳。在大多数情况下，这指的是设备屏幕的整个宽度。请务必考虑应用中设置的内边距参数以及显示器的安全区。 4.自适应内嵌横幅广告适合在可滚动浏览的内容中展示。广告的高度可与设备屏幕相同，也可受限于最大高度，具体取决于 API。 5.要获取广告尺寸，请使用 `BannerAdSize.inline(width, maxAdHeight)` 方法，该方法接受广告容器的可用宽度和可接受的最大广告高度作为参数。 6.使用 `BannerAdSize.inline(width, maxAdHeight)` 方法计算的 `BannerAdSize` 对象包含用于在后端选择最佳广告尺寸的技术数据。广告的高度每次加载时都可能发生变化。`getCalculatedBannerAdSize()` 方法根据 `width` 和 `maxAdHeight` 返回容器的边界，但它不能保证广告的实际尺寸。要精确匹配尺寸，请使用 `Platform Channel` 并在广告加载后更新容器。 ## 向应用布局添加广告小部件 要显示横幅广告，请将 `AdWidget` 添加到您的应用布局中。 将 `AdWidget` 添加到应用屏幕布局的示例： ```dart @override Widget build(BuildContext context) { return Scaffold( body: Align( alignment: Alignment.bottomCenter, child: AdWidget(bannerAd: banner), ), ); } ``` ## 加载和显示广告 创建 `AdWidget` 并将其添加到应用屏幕后，您需要加载广告。在加载自适应内嵌横幅广告之前，请计算每个设备的广告尺寸。 此操作通过 SDK API 方法自动完成：`BannerAdSize.inline(width, maxAdHeight)`。 将广告容器的宽度和可接受的最大广告高度作为参数传递。我们建议使用设备屏幕的完整宽度或父容器的宽度。请务必考虑应用中设置的内边距参数和显示器的安全区： ```dart BannerAdSize getAdSize() { final screenWidth = MediaQuery.of(context).size.width.round(); return BannerAdSize.inline(width: screenWidth, maxHeight: bannerMaxHeight); } ``` 要加载广告，您需要在 Yandex Advertising Network 接口中获取的广告单元 ID (adUnitId)。 要启用广告加载或加载失败时的通知，并跟踪自适应内嵌横幅广告的生命周期事件，请为 `BannerAd` 类实例设置回调函数。 您可以通过 `AdRequest()` 传递用户兴趣、上下文页面数据、位置或其他附加信息来扩展广告请求参数。添加到广告请求中的额外上下文可以显著提高广告质量。请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/dev/flutter/target.md)版块了解更多信息。 以下示例展示了如何加载自适应内嵌横幅广告。加载完成后，横幅广告将自动显示： ```dart class _MyHomePageState extends State { late BannerAd banner; var isBannerAlreadyCreated = false; _loadAd() async { banner = _createBanner(); setState(() { isBannerAlreadyCreated = true; }); // 如果横幅广告已创建，您可以直接调用： // banner.loadAd(adRequest: const AdRequest()); } BannerAdSize getAdSize() { final screenWidth = MediaQuery.of(context).size.width.round(); return BannerAdSize.inline(width: screenWidth, maxHeight: bannerMaxHeight); } _createBanner() { return BannerAd( adUnitId: 'R-M-XXXXXX-Y', // 或者 'demo-banner-yandex' adSize: _getAdSize(), adRequest: const AdRequest(), onAdLoaded: () { // 广告已成功加载。现在将显示。 }, onAdFailedToLoad: (error) { // 广告加载失败，出现 AdRequestError 错误。 // 强烈建议不要尝试从 onAdFailedToLoad() 方法加载新广告。 }, onAdClicked: () { // 当记录到广告点击时调用。 }, onLeftApplication: () { // 当用户点击广告后即将离开应用程序（例如，跳转到浏览器）时调用。 }, onReturnedToApplication: () { // 当用户点击广告后返回应用程序时调用。 }, onImpression: (impressionData) { // 当记录到一次广告展示时调用。 } ); } @override initState() { super.initState(); YandexAds.initialize(); _loadAd(); } @override Widget build(BuildContext context) { return Scaffold( body: Align( alignment: Alignment.bottomCenter, child: isBannerAlreadyCreated ? AdWidget(bannerAd: banner) : null, ), ); } } ``` ## 释放资源 如果在小部件销毁后发生回调，则调用已使用广告对象的 `destroy()` 函数来释放资源： ```dart _createBanner() { return BannerAd( adUnitId: 'R-M-XXXXXX-Y', // 或 'demo-banner-yandex' adSize: getAdSize(), adRequest: const AdRequest(), onAdLoaded: () { // 广告已成功加载。现在将显示。 if (!mounted) { banner.destroy(); return; } }, ); } ``` ## 测试自适应内嵌横幅广告集成 {#test} {% list tabs %} - Android ### 使用演示广告单元进行广告测试 {#demo-blocks} 使用测试广告来检查您的自适应内嵌横幅广告集成和应用本身。为了确保每次广告请求都能返回测试广告，您可以使用一个特殊的演示广告版位 ID。 演示广告单元 ID：`demo-banner-yandex`. {% note warning %} 在应用商店发布应用前，请务必将演示广告版位 ID 替换为您在 Yandex Advertising Network 接口中获取的真实 ID。 {% endnote %} 有关所有可用演示广告版位 ID 的列表，请参阅[用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/android/demo-blocks.md)。 ### 测试广告集成 {#test-int} 您可以使用 SDK 的内置分析工具检查自适应内嵌横幅广告是否已正确集成。日志中将显示包含测试结果的详细报告。 要查看报告，请在 Android 应用调试工具 [Logcat](https://developer.android.com/studio/command-line/logcat) 中搜索关键词“YandexAds”。 ```bash adb logcat -v brief '*:S YandexAds' ``` 如果集成成功，将返回以下消息： ```bash adb logcat -v brief '*:S YandexAds' mobileads$ adb logcat -v brief '*:S YandexAds' I/YandexAds(13719): [Integration] Ad type banner was integrated successfully ``` 如果存在任何横幅广告集成问题，您将收到详细的问题报告和故障排除建议。 - iOS ### 使用演示广告单元进行广告测试 我们建议使用测试广告来测试您的广告集成和应用本身。 为了保证为每个广告请求返回测试广告，我们创建了一个特殊的演示广告版位 ID。用它来检查您的广告集成。 演示广告单元 ID：`demo-banner-yandex`. {% note warning %} 在商店中发布您的应用程序之前，确保将演示版位 ID 替换为您在 Yandex Advertising Network 界面中获得的真实 ID。 {% endnote %} 您可以在 [用于测试的演示广告单元](https://ads.yandex.com/helpcenter/zh/dev/ios/demo-blocks.md) 部分找到可用的演示广告版位 ID 列表。 ### 测试广告集成 您可以使用本机控制台工具测试广告集成。 要查看详细日志，请调用 `YMAMobileAds` 类的 `enableLogging` 方法。 ```swift YMAMobileAds.enableLogging() ``` 要查看 SDK 日志，请前往控制台工具并设置 `Subsystem = com.mobile.ads.ads.sdk`。您还可以按类别和错误级别过滤日志。 如果您在集成广告时遇到问题，您将获得有关问题的详细报告以及如何解决这些问题的建议。 {% endlist %} ## 其他资源 {#resources} * [Pub.dev](https://pub.dev/packages/yandex_mobileads/example) 链接。