自适应内联横幅

自适应内联横幅是一种灵活的横幅广告格式,通过优化每个设备上的广告尺寸,实现最大效率。

这种广告类型允许开发者设置广告的最大允许宽度和高度,但最佳广告尺寸仍然是自动确定的。为了选择最佳广告尺寸,内置自适应横幅使用最大高度而不是固定高度。这为提高广告效果提供了空间。

通常,这种格式在基于内容来源的应用或允许主要关注广告的上下文环境中使用。

本指南展示了如何将自适应内联横幅集成到 Unity 应用中。 除了代码示例和说明之外,本指南还提供特定于格式的建议和其他资源的链接。

前提条件

  1. 按照 快速入门 中的流程集成 Yandex Mobile Ads Unity 插件。
  2. 确保您运行的是最新的 Yandex Mobile Ads Unity 插件 版本。如果您使用聚合,请同时确保您运行的是最新版本的 统一构建

实施

集成自适应内联横幅的关键步骤:

  • 创建并配置横幅广告对象。
  • 注册回调方法监听器。
  • 加载广告。
  • 如果您使用 Adfox,请传递 其他设置

自适应内联横幅集成的特点

  1. 如果您在 onAdFailedToLoad 事件中收到错误,请不要尝试再次加载新广告。如果没有其他选项,请限制广告加载重试次数。这将有助于避免出现限制时持续出现不成功的请求和连接问题。

  2. 为了确保自适应内联横幅正常运行,您需要 使应用布局自适应。否则,您的广告可能无法正确呈现。

  3. 自适应内联横幅在使用所有可用宽度时效果最佳。通常情况下,这是设备屏幕的全宽度。确保包括适用于您的应用程序的所有内边距和安全显示区域。

  4. 自适应内联横幅设计用于放置在可滚动内容中。广告的高度可以与设备屏幕相同,也可以限制为最大高度,具体取决于 API。

  5. 要获取广告尺寸,请使用 BannerAdSize.InlineSize(screenWidth, maxAdHeight) 方法,该方法接受广告容器的可用宽度和可接受的最大广告高度作为参数。

  6. BannerAdSize 对象是使用 BannerAdSize.InlineSize(screenWidth, maxAdHeight) 方法计算的,其中包含用于在后端选择最有效的广告尺寸的技术数据。广告的高度可能会在每次加载时发生变化。收到广告加载成功消息后即可获取广告的实际宽度和高度。

向项目中添加横幅

要在应用中展示横幅,请在附加到 GameObject 的脚本 (C#) 中创建一个 Banner 对象。

using UnityEngine;
using YandexMobileAds;
using YandexMobileAds.Base;

public class YandexMobileAdsInlineBannerDemoScript : MonoBehaviour
{
    private Banner banner;

    private int GetScreenWidthDp()
    {
        int screenWidth = (int)Screen.safeArea.width;
        return ScreenUtils.ConvertPixelsToDp(screenWidth);
    }

    private void RequestInlineBanner()
    {   
        string adUnitId = "demo-banner-yandex"; // 替换为 "R-M-XXXXXX-Y"
        BannerAdSize bannerMaxSize = BannerAdSize.InlineSize(GetScreenWidthDp(), 100);
        banner = new Banner(adUnitId, bannerMaxSize, AdPosition.BottomCenter);
    }
}

Banner 构造函数包含以下参数:

  • AdUnitId:在合作伙伴界面中发布的唯一标识符,格式为:RM-XXXXXX-Y。

    提示

    出于测试目的,您可以使用演示单元 ID:"demo-banner-yandex"。在发布广告之前,请确保将演示单元 ID 替换为真实的广告单元 ID。

  • BannerAdSize:要展示的横幅的大小。

  • AdPosition:屏幕上的位置。

  • InlineSize(int width, int maxHeight):横幅尺寸。

设置宽度和最大允许高度。广告将适合这些尺寸。所选广告的高度不会超过设备屏幕的高度。

加载和呈现广告

创建并配置 Banner 类的对象后,您需要加载广告。要加载广告,请使用 LoadAd 方法,该方法将 AdRequest 对象作为参数。

在加载自适应内联横幅之前,还必须针对每个设备计算广告尺寸。 该操作通过 SDK API 自动执行:BannerAdSize.InlineSize(screenWidth, maxAdHeight)

您可以通过 AdRequest.Builder() 在请求中传递用户兴趣、上下文应用数据、位置详细信息或其他数据来扩展广告请求参数。在请求中提供额外的上下文数据可以显著提高您的广告质量。

要在广告加载或加载失败时发出通知并跟踪自适应内联横幅的生命周期,请为 BannerAd 类对象设置回调函数。

private void RequestInlineBanner()
{
    // ...

    AdRequest request = new AdRequest.Builder().Build();
    banner.LoadAd(request);
}

横幅广告事件

要跟踪横幅广告中发生的事件,请为适当的 EventHandler 注册委托,如下所示:

using System;
// ...

private void RequestInlineBanner()
{
    // ...
    // 激励广告加载时调用
    banner.OnAdLoaded += HandleAdLoaded;

    // 加载广告出错时调用
    banner.OnAdFailedToLoad += HandleAdFailedToLoad;

    // 当应用因用户点击广告并即将切换到其他应用程序(例如浏览器)而变为非活动状态时调用。
    banner.OnLeftApplication += HandleLeftApplication;

    // 当用户点击后返回应用时调用
    banner.OnReturnedToApplication += HandleReturnedToApplication;

    // 当用户点击广告时调用
    banner.OnAdClicked += HandleAdClicked;

    // 记录广告展示时调用
    banner.OnImpression += HandleImpression;
    // ...
}

private void HandleAdLoaded(object sender, EventArgs args)
{
    Debug.Log("AdLoaded event received");
    banner.Show();
}

private void HandleAdFailedToLoad(object sender, AdFailureEventArgs args)
{
    Debug.Log($"AdFailedToLoad event received with message: {args.Message}");
    // 我们强烈建议不要使用此方法加载新广告
}

private void HandleLeftApplication(object sender, EventArgs args)
{
    Debug.Log("LeftApplication event received");
}

private void HandleReturnedToApplication(object sender, EventArgs args)
{
    Debug.Log("ReturnedToApplication event received");
}

private void HandleAdClicked(object sender, EventArgs args)
{
    Debug.Log("AdClicked event received");
}

private void HandleImpression(object sender, ImpressionData impressionData)
{
    var data = impressionData == null ? "null" : impressionData.rawData;
    Debug.Log($"HandleImpression event received with data: {data}");
}

测试自适应内联横幅集成

使用演示广告单元进行广告测试

我们建议使用测试广告来测试您的自适应内联横幅集成和应用本身。

为了保证为每个广告请求返回测试广告,我们创建了一个特殊的演示广告版位 ID。用它来检查您的广告集成。

演示广告单元 ID:demo-banner-yandex.

重要

在商店中发布您的应用之前,请确保将演示广告版位 ID 替换为从 Partner Interface 获取的真实广告版位 ID。

您可以在 用于测试的演示广告单元 版块找到可用的演示广告版位 ID 列表。

测试广告集成

您可以使用 SDK 的内置分析器测试自适应内联横幅集成。

该工具可确保您的广告正确集成并向日志输出详细报告。 要查看报告,请在用于 Android 应用调试的 Logcat 工具中搜索“YandexAds”关键字。

adb logcat -v brief '*:S YandexAds'

如果集成成功,您将看到以下消息:

adb logcat -v brief '*:S YandexAds'
mobileads$ adb logcat -v brief '*:S YandexAds'
I/YandexAds(13719): [Integration] Ad type banner was integrated successfully

如果您在集成横幅广告时遇到问题,您将获得有关问题的详细报告以及如何解决这些问题的建议。

使用演示广告单元进行广告测试

我们建议使用测试广告来测试您的广告集成和应用本身。

为了保证为每个广告请求返回测试广告,我们创建了一个特殊的演示广告版位 ID。用它来检查您的广告集成。

演示广告单元 ID:demo-banner-yandex.

重要

在将您的应用发布到商店之前,请确保将演示广告单元 ID 替换为从 Partner Interface 获取的真实 ID。

您可以在 用于测试的演示广告单元 部分找到可用的演示广告版位 ID 列表。

测试广告集成

您可以使用本机控制台工具测试广告集成。

要查看详细日志,请调用 YMAMobileAds 类的 enableLogging 方法。

YMAMobileAds.enableLogging()

要查看 SDK 日志,请前往控制台工具并设置 sybsystem = com.yandex.mobile.ads.sdk。您还可以按类别和错误级别过滤日志。

如果您在集成广告时遇到问题,您将获得有关问题的详细报告以及如何解决这些问题的建议。

提示

广告预加载

加载广告可能需要几秒钟的时间,具体取决于移动聚合中对接的广告网络数量和用户的互联网速度。我们建议在展示广告之前预加载广告。

您可以在应用启动时或在展示之前加载广告。确保使用 DontDestroyOnLoad(gameObject) 调用保留场景之间的对象。这可确保加载的广告不会在场景更改时随 gameObject 一起删除。

当您需要呈现横幅时,请调用 banner.Show()

如果您在太多不太可能显示的屏幕上缓存广告,您的广告效果可能会下降。例如,如果用户每次会话完成 2-3 个游戏关卡,则您不应缓存 6-7 个屏幕的广告。否则,您的广告可见性可能会降低,并且广告系统可能会降低您的应用的优先级。

为确保您为应用找到良好的平衡,请在合作伙伴界面中跟踪“展示次数份额”或“已观看展示次数份额”指标。如果该指标低于 20%,您可能需要修改缓存算法。展示次数百分比越高越好。

清除未使用的内存

我们建议在每次广告请求之前调用 banner?.Destroy() 并重新创建 Banner 对象。这可确保清除所有已使用的内存,并且应用可以多次请求和展示广告,而不会使设备过载。这还可以防止与重复广告加载和生命周期中断相关的代码错误。

其他资源