激励广告

所谓激励广告，指的是用户可以选择与之互动来换取应用内奖励的一种广告。本指南介绍了如何将 AdMob 激励广告植入到 Unity 应用中。您可以查看客户成功案例：案例研究 1、案例研究 2。

Google 移动广告 SDK 引入了一组经过改进的新版激励广告 API。新版激励广告 API 在旧版 API 基础上做了改进，现在它允许您：

• 缓存多个广告。之前的情况是您只能一次加载一个广告，在第一个广告完成之前无法加载第二个广告；新版激励广告 API 则可让您同时缓存多个广告。
• 在广告加载时访问奖励值。之前的情况是只有在向用户授予奖励时才可以访问奖励内容。对于使用 AdMob 界面中奖励值的应用，本次改进让您可以在用户观看广告之前向其显示奖励。
• 中介合作伙伴的初始化。如果您使用激励广告中介，新版激励广告 API 支持在第一次加载广告之前初始化中介适配器；旧版激励广告 API 则不会初始化适配器，中介适配器更有可能在会话的第一个请求上超时。

前提条件

• Unity 插件 3.16.0 或更高版本。
• 完成入门指南的学习。您的 Unity 应用应该已经导入了 Google 移动广告 Unity 插件。

创建激励广告对象

激励广告由 RewardedAd 对象请求和展示。要展示激励广告，第一步要做的是实例化 RewardedAd 对象，具体方法是调用相应的构造函数，其中包含用于加载广告的广告单元 ID。以下代码段对此进行了演示：

要使用 Unity 编辑器更轻松地植入广告，请试用全新广告展示位置（Beta 版）。

using UnityEngine.Events;
using UnityEngine;
using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
using UnityEngine.UI;
using System;
using System.Collections.Generic;

public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        ...

        this.rewardedAd = new RewardedAd(adUnitId);
    }
}

务必用测试广告进行测试

在构建和测试应用时，请确保使用的是测试广告，而不是实际投放的广告。否则，可能会导致您的帐号被暂停。

对于 Android 和 iOS 激励广告，加载测试广告最简便的方法就是使用下面的专用测试广告单元 ID：

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

这些测试广告单元 ID 已经过专门配置，可为每个请求返回测试广告，您可以在自己应用的编码、测试和调试过程中随意使用这些测试广告单元 ID。只需确保您会在发布应用前用自己的广告单元 ID 替换这些测试广告单元 ID 即可。

如需详细了解移动广告 SDK 的测试广告如何运作，请参阅测试广告。

加载广告

要加载激励广告，请调用 RewardedAd 对象的 loadAd() 方法。此方法需要 AdRequest 实例作为参数。

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        ...

        this.rewardedAd = new RewardedAd(adUnitId);

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }
}

广告事件

要进一步自定义您广告的行为，您可以在广告生命周期内加入许多事件，如加载、打开、关闭等等。您可以通过为相应的事件处理脚本注册代理来监听这些事件。最重要的事件是 OnUserEarnedReward，该事件会在用户因观看视频而应获得奖励时被调用。您还可以实现其他广告事件，如下所示。

using GoogleMobileAds.Api;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        string adUnitId;
        #if UNITY_ANDROID
            adUnitId = "ca-app-pub-3940256099942544/5224354917";
        #elif UNITY_IPHONE
            adUnitId = "ca-app-pub-3940256099942544/1712485313";
        #else
            adUnitId = "unexpected_platform";
        #endif

        this.rewardedAd = new RewardedAd(adUnitId);

        // Called when an ad request has successfully loaded.
        this.rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        // Called when an ad request failed to load.
        this.rewardedAd.OnAdFailedToLoad += HandleRewardedAdFailedToLoad;
        // Called when an ad is shown.
        this.rewardedAd.OnAdOpening += HandleRewardedAdOpening;
        // Called when an ad request failed to show.
        this.rewardedAd.OnAdFailedToShow += HandleRewardedAdFailedToShow;
        // Called when the user should be rewarded for interacting with the ad.
        this.rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        // Called when the ad is closed.
        this.rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }

    public void HandleRewardedAdLoaded(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdLoaded event received");
    }

    public void HandleRewardedAdFailedToLoad(object sender, AdErrorEventArgs args)
    {
        MonoBehaviour.print(
            "HandleRewardedAdFailedToLoad event received with message: "
                             + args.Message);
    }

    public void HandleRewardedAdOpening(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdOpening event received");
    }

    public void HandleRewardedAdFailedToShow(object sender, AdErrorEventArgs args)
    {
        MonoBehaviour.print(
            "HandleRewardedAdFailedToShow event received with message: "
                             + args.Message);
    }

    public void HandleRewardedAdClosed(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdClosed event received");
    }

    public void HandleUserEarnedReward(object sender, Reward args)
    {
        string type = args.Type;
        double amount = args.Amount;
        MonoBehaviour.print(
            "HandleRewardedAdRewarded event received for "
                        + amount.ToString() + " " + type);
    }
}

OnUserEarnedReward 事件会提供特殊事件参数。该事件会传递一个 Reward 实例，其中包含的 Type 和 Amount 用于描述用户所获奖励：

public void HandleUserEarnedReward(object sender, Reward args)
{
    string type = args.Type;
    double amount = args.Amount;
     MonoBehaviour.print(
          "HandleRewardedAdRewarded event received for "
              + amount.ToString() + " " + type);
}

警告：强烈建议您不要在广告加载失败时尝试使用广告请求完成块加载新广告。如果您必须使用广告请求完成块加载广告，请限制广告加载重试次数，以免在网络连接受限等情况下广告请求连续失败。

可用的广告事件

OnAdLoaded

在广告加载完成时被调用。

OnAdFailedToLoad

在广告加载失败时被调用。提供的 AdErrorEventArgs 的 Message 属性用于描述发生了何种类型的失败。

OnAdOpening

在广告开始展示并铺满设备屏幕时被调用。如需暂停应用音频输出或游戏循环，则非常适合使用此方法。

OnAdFailedToShow

在广告显示失败时被调用。提供的 AdErrorEventArgs 的 Message 属性用于描述发生了何种类型的失败。

OnUserEarnedReward

在用户因观看视频而应获得奖励时被调用。 Reward 参数描述了要呈现给用户的奖励。

OnAdClosed

在用户点按“关闭”图标或使用“返回”按钮关闭激励视频广告时被调用。如果您的应用暂停了音频输出或游戏循环，则非常适合使用此方法恢复这些活动。

展示广告

在向用户展示激励广告之前，必须为用户提供明确的选项，让用户可以自行选择是否通过观看激励广告内容来换取奖励。激励广告必须始终是一项可由用户自行选择的体验。

要展示激励广告，请检查 IsLoaded() 方法来验证广告已加载完成，然后调用 show()。以下示例展示了如何做到这一点：

private void UserChoseToWatchAd()
{
  if (this.rewardedAd.IsLoaded()) {
    this.rewardedAd.Show();
  }
}

使用 OnAdClosed 预加载下一个激励广告

RewardedAd 是一次性对象。这意味着，在展示激励广告后，就不能再用该对象加载另一个广告了。要请求另一个激励广告，您需要创建新的 RewardedAd 对象。

最佳做法是在 OnAdClosed 广告事件中加载另一个激励广告，以便在上一个激励广告关闭后，立即开始加载下一个激励广告：

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void CreateAndLoadRewardedAd()
    {
        #if UNITY_ANDROID
            string adUnitId = "ca-app-pub-3940256099942544/5224354917";
        #elif UNITY_IPHONE
            string adUnitId = "ca-app-pub-3940256099942544/1712485313";
        #else
            string adUnitId = "unexpected_platform";
        #endif

        this.rewardedAd = new RewardedAd(adUnitId);

        this.rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        this.rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        this.rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }

...

    public void HandleRewardedAdClosed(object sender, EventArgs args)
    {
        this.CreateAndLoadRewardedAd();
    }
}

加载多个激励广告

要加载多个激励广告，请针对您要加载的每个广告，按照创建激励广告对象和加载广告部分中所述的步骤操作。下面的代码段展示了如何为两个不同的广告展示位置加载两个激励广告。

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd gameOverRewardedAd;
    private RewardedAd extraCoinsRewardedAd;
    ...
    public void Start()
    {
        ...

        this.gameOverRewardedAd = CreateAndLoadRewardedAd(adUnitId);
        this.extraCoinsRewardedAd = CreateAndLoadRewardedAd(adUnitId);
    }

    public RewardedAd CreateAndLoadRewardedAd(string adUnitId)
    {
        RewardedAd rewardedAd = new RewardedAd(adUnitId);

        rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        rewardedAd.LoadAd(request);
        return rewardedAd;
    }
}

其他资源

示例

• HelloWorld 示例 — 所有广告格式的极简实现方案

后续步骤

• 在 AdMob 界面中创建您自己的横幅广告单元。
• 尝试其他广告格式：
  • 横幅广告
  • 插页式广告