向 Unity 应用添加 AdMob 开屏广告

1. 简介

在此 Codelab 中，您将在 Unity 应用中植入 AdMob 开屏广告。

要构建的内容

此 Codelab 将指导您使用 Google 移动广告 Unity 插件在 Unity 应用中植入 AdMob 开屏广告。

如果您在学习此 Codelab 时遇到任何问题（代码错误、语法错误、措辞含义不明等），请通过 Codelab 左下角的报告错误链接报告相应问题。

要学习的内容

• 如何配置 Google 移动广告 Unity 插件
• 如何在 Unity 应用中植入开屏广告

所需条件

• Unity 2018.4 或更高版本
• Xcode 12 或更高版本和 CocoaPods（部署到 iOS）

您如何评价自己在 AdMob 方面的经验水平？

新手 中等 熟练

2. 设置开发环境

下载代码

下载源代码 在 GitHub 上查看代码库

下载 ZIP 文件后，解压其内容。您将会看到名为 admob-appopen-unity-main 的文件夹。

或者，您也可以从命令行克隆 GitHub 代码库：

$ git clone https://github.com/googlecodelabs/admob-appopen-unity

该代码库包含两个文件夹：

• starter：您在此 Codelab 中用作基础的起始代码。
• complete：此 Codelab 完成后的代码。

3. 设置 AdMob 应用和广告单元

由于 Unity 是一个多平台 SDK，您需要在 AdMob 中添加同时适用于 Android 和 iOS 的应用和广告单元。

注意：如果您希望按照此 Codelab 操作，而不是自行创建新的应用和广告单元，请前往使用测试 AdMob 应用和广告单元部分。

针对 Android 进行设置

如需针对 Android 进行设置，您需要添加 Android 应用并创建广告单元。

添加 Android 应用

1. 在 AdMob 控制台中，点击应用菜单中的添加应用。
2. 选择 Android 作为平台。当系统询问“此应用是否已在受支持的应用商店中上架？”时，点击否。
3. 在应用名称字段中输入 AdMob app open ad。
4. 您不必启用用户指标就能完成此 Codelab。不过，我们仍建议您启用用户指标，以便更详细地了解用户行为。点击添加以完成此流程。

创建广告单元

1. 从 AdMob 控制台的应用菜单中选择 AdMob 开屏广告应用 (Android)。
2. 点击广告单元菜单。

点击添加广告单元。 选择开屏广告作为广告格式。 在广告单元名称字段中输入 android-appopen。 点击创建广告单元以完成此流程。

重要提示：构建和测试应用时，请确保使用测试广告，而不是实际投放的广告。否则，可能会导致您的帐号被暂停。如需详细了解移动广告 SDK 的测试广告如何运作，请参阅测试广告。

新广告单元通常要过几个小时才能投放广告。

如果您想立即测试广告的行为，请使用“Android 应用 ID/广告单元 ID”和“iOS 应用 ID/广告单元 ID”表格中列出的测试应用 ID 和广告单元 ID。

针对 iOS 进行设置

如需针对 iOS 进行设置，您需要添加 iOS 应用并创建广告单元。

添加 iOS 应用

1. 在 AdMob 控制台中，点击应用菜单中的添加应用。
2. 选择 iOS 作为平台。当系统询问“此应用是否已在受支持的应用商店中上架？”时，点击否。
3. 在应用名称字段中输入 AdMob app open ad。
4. 您不必启用用户指标就能完成此 Codelab。不过，我们仍建议您启用用户指标，以便更详细地了解用户行为。点击添加以完成此流程。

创建广告单元

1. 从 AdMob 控制台的应用菜单中选择 AdMob 内嵌广告应用 (iOS)。
2. 点击广告单元菜单。

点击添加广告单元。 选择开屏广告作为广告格式。 在广告单元名称字段中输入 ios-appopen。 点击创建广告单元以完成此流程。

重要提示：构建和测试应用时，请确保使用测试广告，而不是实际投放的广告。否则，可能会导致您的帐号被暂停。如需详细了解移动广告 SDK 的测试广告如何运作，请参阅测试广告。

新广告单元通常要过几个小时才能投放广告。

如果您想立即测试广告的行为，请使用下表中列出的测试应用 ID 和广告单元 ID。

可选：使用测试 AdMob 应用和广告单元

如果您希望按照此 Codelab 操作，而不是自行创建新的应用和广告单元，可以使用下表列出的测试 AdMob 应用 ID 和广告单元 ID。

Android 应用 ID/广告单元 ID

项目	应用 ID/广告单元 ID
AdMob 应用 ID	ca-app-pub-3940256099942544~3347511713
广告单元 ID	ca-app-pub-3940256099942544/3419835294

iOS 应用 ID/广告单元 ID

项目	应用 ID/广告单元 ID
AdMob 应用 ID	ca-app-pub-3940256099942544~1458002511
广告单元 ID	ca-app-pub-3940256099942544/5662855259

如需详细了解测试广告，请参阅 Android 测试广告和 iOS 测试广告开发者文档。

4. 添加 Google 移动广告 Unity 插件

要展示 AdMob 广告并赚取收入，第一步就是集成 Google 移动广告 Unity 插件。

下载移动广告 Unity 插件

借助 Google 移动广告 Unity 插件，Unity 开发者可轻松地在 Android 和 iOS 应用上投放 Google 移动广告。该插件提供了一个用于请求广告的 C# 接口，供 Unity 项目中的 C# 脚本使用。

请通过以下链接下载该插件的 Unity 软件包。

下载插件

打开 starter 项目

1. 启动 Unity Hub。
2. 在 Projects（项目）标签页中，点击 ADD（添加）按钮。
3. 前往您在设置开发环境步骤中提取下载的代码所在的文件夹。
4. 打开 starter 文件夹。
5. 您会在项目列表中看到 starter 项目。点击项目即可在 Unity 编辑器中打开它。

导入移动广告 Unity 插件

1. 在 Unity 编辑器中，从菜单中依次选择 Assets（资源）> Import Package（导入软件包）> Custom Package（自定义软件包）。
2. 选择您在上一步中下载的 GoogleMobileAds-{VERSION}.unitypackage。
3. 确保选择所有文件，然后点击 Import（导入）。

设置您的 AdMob 应用 ID

1. 在 Unity 编辑器中，从菜单中依次选择 Assets（资源）> Google Mobile Ads（Google 移动广告）> Settings（设置）。
2. 在相应字段中分别输入您的 Android 和 iOS AdMob 应用 ID。如果您希望按照此 Codelab 操作，而不是自行创建新的应用和广告单元，请按如下方式输入测试 AdMob 应用 ID。

重要提示：未能输入 AdMob 应用 ID 将会导致应用崩溃。

5. 创建实用工具类

在 Scripts 文件夹下创建一个名为 AppOpenAdManager 的新类。此类会管理一个实例变量，以便跟踪各个平台加载的广告和广告单元 ID。

AppOpenAdManager.cs

using System;
using GoogleMobileAds.Api;
using UnityEngine;

public class AppOpenAdManager
{
#if UNITY_ANDROID
    // Test ad unit ID: ca-app-pub-3940256099942544/3419835294
    private const string AD_UNIT_ID = "<YOUR_ANDROID_APPOPEN_AD_UNIT_ID>";
#elif UNITY_IOS
    // Test ad unit ID: ca-app-pub-3940256099942544/5662855259
    private const string AD_UNIT_ID = "<YOUR_IOS_APPOPEN_AD_UNIT_ID>";
#else
    private const string AD_UNIT_ID = "unexpected_platform";
#endif

    private static AppOpenAdManager instance;

    private AppOpenAd ad;

    private bool isShowingAd = false;

    public static AppOpenAdManager Instance
    {
        get
        {
            if (instance == null)
            {
                instance = new AppOpenAdManager();
            }

            return instance;
        }
    }

    private bool IsAdAvailable
    {
        get
        {
            return ad != null;
        }
    }

    public void LoadAd()
    {
        // TODO: Load an app open ad.
    }
}

加载广告

广告加载是使用静态 AppOpenAd.LoadAd() 方法完成的。该加载方法需要使用广告单元 ID、ScreenOrientation 模式、AdRequest 对象以及在广告加载成功或失败时调用的完成处理程序。

已加载的 AppOpenAd 对象会以完成处理程序中的参数的形式提供。请按如下方式实现 LoadAd() 方法。

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    public void LoadAd()
    {
        AdRequest request = new AdRequest.Builder().Build();

        // Load an app open ad for portrait orientation
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                // Handle the error.
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            // App open ad is loaded.
            ad = appOpenAd;
        }));
    }
}

展示广告

在展示广告之前，请先注册每个事件处理脚本，以监听每个广告事件。

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    public void ShowAdIfAvailable()
    {
        if (!IsAdAvailable || isShowingAd)
        {
            return;
        }

        ad.OnAdDidDismissFullScreenContent += HandleAdDidDismissFullScreenContent;
        ad.OnAdFailedToPresentFullScreenContent += HandleAdFailedToPresentFullScreenContent;
        ad.OnAdDidPresentFullScreenContent += HandleAdDidPresentFullScreenContent;
        ad.OnAdDidRecordImpression += HandleAdDidRecordImpression;
        ad.OnPaidEvent += HandlePaidEvent;

        ad.Show();
    }

    private void HandleAdDidDismissFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Closed app open ad");
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        isShowingAd = false;
        LoadAd();
    }

    private void HandleAdFailedToPresentFullScreenContent(object sender, AdErrorEventArgs args)
    {
        Debug.LogFormat("Failed to present the ad (reason: {0})", args.AdError.GetMessage());
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        LoadAd();
    }

    private void HandleAdDidPresentFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Displayed app open ad");
        isShowingAd = true;
    }

    private void HandleAdDidRecordImpression(object sender, EventArgs args)
    {
        Debug.Log("Recorded ad impression");
    }

    private void HandlePaidEvent(object sender, AdValueEventArgs args)
    {
        Debug.LogFormat("Received paid event. (currency: {0}, value: {1}",
                args.AdValue.CurrencyCode, args.AdValue.Value);
    }
}

考虑广告有效期

开屏广告中的广告引用会在 4 小时后超时。如果广告在超过请求时间 4 小时后呈现，则相应广告将不再有效且可能无法为您创收。

为确保您不会展示过期的广告，请将 IsAdAvailable 属性更改为 AppOpenAdManager，用于检查广告加载后经过了多长时间。然后，使用该方法检查广告是否仍然有效。

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    // TODO: Add loadTime field
    private DateTime loadTime;

    private bool IsAdAvailable
    {
        get
        {
            // TODO: Consider ad expiration
            return ad != null && (System.DateTime.UtcNow - loadTime).TotalHours < 4;
        }
    }

    public void LoadAd()
    {
        if (IsAdAvailable)
        {
            return;
        }

        AdRequest request = new AdRequest.Builder().Build();
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            ad = appOpenAd;
            Debug.Log("App open ad loaded");

            // TODO: Keep track of time when the ad is loaded.
            loadTime = DateTime.UtcNow;
        }));
    }
}

6. 更新场景以加载/展示广告

更新 MainScene 类中的 Start() 方法，以在场景开始时加载开屏广告。

为了接收有关应用前台事件的通知，我们建议您监听 AppStateEventNotifier 单例。通过实现 AppStateEventNotifier.AppStateChanged 代理，您的应用将收到有关应用启动和前台事件的提醒，并且能够展示广告。

MainScene.cs

using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
using UnityEngine;

public class MainScene : MonoBehaviour
{
    public void Start()
    {
        // TODO: Request an app open ad.
        MobileAds.Initialize((initStatus) =>
        {
            AppOpenAdManager.Instance.LoadAd();
            AppStateEventNotifier.AppStateChanged += OnAppStateChanged;
        });
    }

    public void OnAppStateChanged(AppState state)
    {
        if (state == AppState.Foreground)
        {
            // TODO: Show an app open ad if available.
            AppOpenAdManager.Instance.ShowAdIfAvailable();
        }
    }
}

重要提示：推荐使用 AppStateEventNotifier，因为 OnApplicationPause 在应用展示全屏广告时将发出错误的前台和后台信号。

注意：当用户从其他应用返回该应用（例如，从图库中选择一张照片）时，系统可能会展示开屏广告，因为这也被视为“应用切换”事件。建议停用/启用开屏广告，以免在重要的用户体验流程期间展示这些广告。

大功告成！在设备或模拟器上构建并运行项目。应用启动后，请等待几秒钟，以便广告完全加载。

此后，当您从其他应用/主屏幕切换回该应用后，开屏广告将以如下方式展示。

7. 全部完成！

您已完成此 Codelab。您可以在 complete 文件夹中找到此 Codelab 的完整代码。