Unity 开发者集成

概述

本指南将介绍在使用 Unity 开发的游戏中实现 Unity Ads 的集成方法。

• 如果您是使用 Objective-C 的 iOS 开发者，单击此处。
• 如果您是使用 Java 的 Android 开发者，单击此处。

Unity 的变现平台为您提供了强大的收入工具。如果游戏使用应用内购和广告，Unity 的机器学习数据模型可以无缝地混合内容类型，从而实现优化的变现策略。要详细了解 Unity 如何帮助您优化收入，请参阅有关个性化广告位的文档。

本指南的内容：

• 基本广告实现
• 奖励广告实现
• 横幅广告实现
• 测试您的实现
• 高级变现建议
• API 参考

基本实现

配置项目

设置构建目标

使用 Build Settings 窗口配置您的项目以便发布到受支持的平台。将平台设置为 iOS 或 Android，然后单击 Switch Platform。

安装 Unity Ads

为确保使用最新版本的 Unity Ads，请从 Asset Store 进行下载。变现 API 需要 SDK 3.0 或更高版本。如需了解下载和安装资源包的信息，请参阅资源包文档。

创建广告位

广告位 (Placements) 是游戏中触发的展示变现内容的事件。在开发者控制面板 (Developer Dashboard) 的 Operate 选项卡中选择项目，然后从左侧导航栏中选择 Monetization > Placements，即可对广告位进行管理。

单击 ADD PLACEMENT 按钮将显示广告位创建提示。为广告位命名并选择其类型：

• 选择 Non-rewarded 可显示基本的插页式广告或推荐内容。非奖励广告位 (Non-rewarded Placements) 允许玩家在指定的时间段之后跳过广告。
• 选择 Rewarded 允许玩家选择观看广告来换取奖励。奖励广告位 (Rewarded Placements) 不允许玩家跳过广告。
• 选择 Banner 可创建专门的横幅广告位。

默认情况下，每个启用 Unity Ads 的项目都有一个（非奖励）“video”和（奖励）“rewardedVideo”广告位。如果符合您的需要，请随意使用其中一个进行首次实现，或者自己创建。

初始化 SDK

要初始化该 SDK，必须为适当平台引用项目的 Game ID。在开发者控制面板 (Developer Dashboard) 的 Operate 选项卡中选择项目，然后从左侧导航栏中选择 Monetization > Platforms，即可找到该 ID。

在游戏脚本头文件中，请包含 UnityEngine.Monetization 命名空间。在游戏的运行时生命周期的早期（最好在启动时）使用 Initialize 函数来初始化 SDK。例如：

using UnityEngine.Monetization;

public class UnityAdsScript : MonoBehaviour {

    string gameId = "1234567";
    bool testMode = true;

    void Start () {
        Monetization.Initialize (gameId, testMode);
    }
}

实现基本（非奖励）广告

PlacementContent 对象表示广告位可以显示的变现内容（如需了解更多信息，请参阅有关内容类型和个性化广告位的文档）。使用 GetPlacementContent 函数可以获取已准备好显示的内容，而使用 Show 函数可以显示这些内容。例如：

using UnityEngine.Monetization;

public class UnityAdsPlacement : MonoBehaviour {

    public string placementId = "video";

    public void ShowAd () {
        StartCoroutine (ShowAdWhenReady ());
    }

    private IEnumerator ShowAdWhenReady () {
        while (!Monetization.IsReady (placementId)) {
            yield return new WaitForSeconds(0.25f);
        }

        ShowAdPlacementContent ad = null;
        ad = Monetization.GetPlacementContent (placementId) as ShowAdPlacementContent;

        if(ad != null) {
            ad.Show ();
        }
    }
}

在此示例中，协程使用 IsReady 函数检查传递的 Placement ID 是否有可用的 PlacementContent。如果有可用内容，则会将其存储为变量并使用 Show 函数执行。

实现奖励广告

对观看广告的玩家进行奖励可以增加用户参与度，从而带来更高收入。例如，游戏可以用游戏币、消耗品、额外生命数量或经验倍增法宝来奖励玩家。如需了解如何有效设计奖励广告的更多信息，请参阅有关广告最佳实践的文档。

要奖励玩家观看广告，请按照基本实现部分中详细介绍的相同步骤进行操作，但应使用奖励回调方法向玩家展示广告，该方法中对于看完广告的玩家有自定义的处理逻辑。

选择广告位

必须通过奖励广告位 (Rewarded Placements) 显示奖励广告。默认情况下，每个启用 Unity Ads 的项目也有一个“rewardedVideo”广告位。您可以在自己的实现中任意使用此广告位，或者自己创建（但务必将广告位配置为奖励类型）。

在脚本中添加一个回调方法

Show 函数接受一个回调，此回调由 SDK 用于返回一个 ShowResult 枚举。此结果指示玩家已看完还是跳过广告。使用此信息可以编写自定义函数来处理每种情况。例如：

using UnityEngine.Monetization;

public class RewardedAdsPlacement : MonoBehaviour {

    public string placementId = "rewardedVideo";

    public void ShowAd () {
        StartCoroutine (WaitForAd ());
    }

    IEnumerator WaitForAd () {
        while (!Monetization.IsReady (placementId)) {
            yield return null;
        }

        ShowAdPlacementContent ad = null;
        ad = Monetization.GetPlacementContent (placementId) as ShowAdPlacementContent;

        if (ad != null) {
            ad.Show (AdFinished);
        }
    }

    void AdFinished (ShowResult result) {
        if (result == ShowResult.Finished) {
            // Reward the player
        }
    }
}

奖励广告按钮代码示例

奖励广告通常使用一个按钮提示玩家选择观看广告。以下内容将介绍如何创建奖励广告按钮；只要有可用内容，便会在按下该按钮时显示广告。

1.在 Unity Editor 中，选择 Game Object > UI > Button，将一个按钮添加到场景。 2.选择按钮后，在 Inspector 中，单击 Add Component > New Script，向其添加脚本组件。将脚本命名为 UnityAdsButton 以便与类名匹配。 3.打开脚本，并添加以下示例代码：

using UnityEngine;
using UnityEngine.UI;
using UnityEngine.Monetization;

[RequireComponent (typeof (Button))]
public class UnityAdsButton : MonoBehaviour {

    public string placementId = "rewardedVideo";
    private Button adButton;

# if UNITY_IOS
   private string gameId = "1234567";
# elif UNITY_ANDROID
    private string gameId = "7654321";
# endif

    void Start () {
        adButton = GetComponent<Button> ();
        if (adButton) {
            adButton.onClick.AddListener (ShowAd);
        }

        if (Monetization.isSupported) {
            Monetization.Initialize (gameId, true);
        }
    }

    void Update () {
        if (adButton) {
            adButton.interactable = Monetization.IsReady (placementId);
        }
    }

    void ShowAd () {
        ShowAdCallbacks options = new ShowAdCallbacks ();
        options.finishCallback = HandleShowResult;
        ShowAdPlacementContent ad = Monetization.GetPlacementContent (placementId) as ShowAdPlacementContent;
        ad.Show (options);
    }

    void HandleShowResult (ShowResult result) {
        if (result == ShowResult.Finished) {
            // Reward the player
        } else if (result == ShowResult.Skipped) {
            Debug.LogWarning ("The player skipped the video - DO NOT REWARD!");
        } else if (result == ShowResult.Failed) {
            Debug.LogError ("Video failed to show");
        }
    }
}

注意：此示例将检查游戏中的特定点是否准备好显示 PlacementContent。另一种替代方法是可以实现一个监听器以便在内容可用时向您发出通知。

实现横幅广告

广告位配置

横幅广告需要特定类型的专用横幅广告位。横幅当前显示锚定在屏幕底部中心位置。

脚本实现

在广告位脚本头文件中，声明 UnityEngine.Advertisement 命名空间，其中包含 Banner 类。接下来，初始化 SDK 并使用 Advertisement.Banner.Show () 来显示横幅广告。例如：

using System.Collections;
using UnityEngine;
using UnityEngine.Advertisements;

public class BannerAds : MonoBehaviour {

    public string bannerPlacement = "banner";
    public bool testMode = false;

# if UNITY_IOS
    public const string gameID = "1234567";
# elif UNITY_ANDROID
    public const string gameID = "1234568";
# elif UNITY_EDITOR
    public const string gameID = "1111111";
# endif

    void Start () {
        Advertisement.Initialize (gameID, testMode);
        StartCoroutine (ShowBannerWhenReady ());
    }

    IEnumerator ShowBannerWhenReady () {
        while (!Advertisement.IsReady ("banner")) {
            yield return new WaitForSeconds (0.5f);
        }
        Advertisement.Banner.Show (bannerPlacement);
    }
}

测试

在发布游戏之前，请按照以下步骤启用测试模式：

1.从开发者控制面板 (Developer Dashboard) 的 Operate 选项卡中选择项目。 2.从左侧导航栏中选择 Monetization > Platforms。 3.选择所需的平台，然后选择 SETTINGS 选项卡。 4.向下滚动到 TEST MODE 部分，并切换覆盖客户端测试模式，然后选中 Force test mode ON 单选按钮。

在 Unity Editor 中，单击 Play 按钮即可运行项目并测试广告实现。

注意：必须在测试广告集成之前启用测试模式，以免因欺诈而被标记。

优化收入

恭喜已实现 Unity Ads！我们的目标是让您轻松实现收入最大化。考虑到这一点，请执行以下后续步骤：

• 游戏是否使用应用内购买 (IAP)？
• 如果是，请实现应用内购推荐 (IAP Promo) 来推荐应用内的优惠。
• 如果否，请使用 Unity IAP 创建应用内商店。
• 设置广告 (Ads) 和应用内购推荐 (IAP Promo) 后，请使用个性化广告位 (Personalized Placements) 来增强您的广告和 IAP 策略，并提升整个游戏的收入。
• 查看我们的最佳实践指南，了解如何设计有效的广告机制。

回到顶部

Unity API 参考

Monetization

Initialize

为项目初始化 SDK。

public static void Initialize (string gameID, bool testMode)

gameId 参数是可在开发者控制面板 (Developer Dashboard) 上找到的项目 Game ID。testMode 参数指示游戏是否处于测试模式。当 testMode 为 true 时，只会看到测试广告。当 testMode 为 false 时，您将看到真实广告。为避免被标记为欺诈，在启动游戏之前使用测试模式非常重要。

IsReady

检查给定的广告位是否有就绪的 PlacementContent。

public static boolean IsReady (string placementId);

placementId 参数是开发者控制面板 (Developer Dashboard) 中配置的 Placement ID。如果 PlacementContent 已就绪，此函数返回 true，否则返回 false。

GetPlacementContent

返回已为给定的广告位准备就绪的 PlacementContent 对象。

public static PlacementContent GetPlacementContent (string placementId);

placementId 参数是开发者控制面板 (Developer Dashboard) 中配置的 Placement ID。该函数将返回 PlacementContent 对象（如果可用），或返回 null（如果不可用）。

注意：设置 PlacementContent 作为变量时，必须将其转换为正确类型（ShowAdPlacementContent 或 PromoAdPlacementContent）。如需了解更多信息，请参阅有关内容类型的文档。

IMonetizationListener

这是您实现并传递给 SDK 的接口。

public interface IMonetizationListener {
    void OnPlacementContentReady (string placementId, PlacementContent placementContent);
    void OnPlacementContentStateChange (string placementId, PlacementContent placementContent, Monetization.PlacementContentState previousState, Monetization.PlacementContentState newState);
}

OnPlacementContentReady

接受 Placement ID 和 PlacementContent 对象，并指示 SDK 如何处理已准备好显示的内容。

OnPlacementContentStateChange

指示 SDK 如何处理传递的 PlacementContent 中的状态更改。

SetListener

设置 PlacementContent 事件的监听器。监听器参数是事件回调的监听器。

public static void SetListener (IMonetizationListener listener);

GetListener

返回当前的变现监听器。监听器对象是事件回调的监听器。

public static IMonetizationListener GetListener ();

PlacementContent

一个表示广告位可以显示的变现内容的对象。

RewardablePlacementContent

扩展 PlacementContent 类的范围以支持可奖励的内容。

ShowAdPlacementContent

扩展 RewardablePlacementContent 类的功能以支持视频广告内容。

Show

PlacementContent 转换为 ShowAdPlacementContent 时，使用 Show 函数来显示该内容。您可以传递一个回调方法，指示广告已完成、跳过还是显示失败，以便处理游戏内奖励。

public void Show (ShowAdCallbacks showAdCallbacks)

public void Show (ShowAdFinishCallback finishCallback)

对于奖励类型的 PlacementContent，使用监听器检查内容是否完成并处理所需的行为。

ShowAdCallbacks

运行广告后将一个 ShowResult 枚举传递给 [[ShowOptions.resultCallback]]。

值	描述
Finished	表示玩家已完整观看广告。
Skipped	表示玩家未完整观看广告。
Failed	表示广告显示失败。

public delegate void ShowAdFinishCallback (ShowResult finishState);

public delegate void ShowAdStartCallback ();

public struct ShowAdCallbacks {
    public ShowAdFinishCallback finishCallback;
    public ShowAdStartCallback startCallback;
}

PromoAdPlacementContent

扩展 ShowAdPlacementContent 类的功能以支持应用内购推荐 (IAP Promo) 内容。如需了解更多信息，请参阅有关原生推荐 (Native Promo) 的文档。

Banner

Load

用于加载横幅广告内容的基本方法。可根据需要使用多个参数调整此函数。

方法	描述
public static void Load ()	使用默认的 Placement ID 加载横幅广告，不进行回调。
public static void Load (BannerLoadOptions options)	使用默认的 Placement ID 加载横幅广告，但在成功加载时触发 loadCallback 回调，并在加载失败时触发 errorCallback 回调。
public static void Load (string placementID)	使用特定的 Placement ID 加载横幅广告，不进行回调。
public static void Load (string placementID, BannerLoadOptions options)	使用特定的 Placement ID 加载横幅广告，但在成功加载时触发 loadCallback 回调，并在加载失败时触发 errorCallback 回调。
public static bool isLoaded ()	检查内容是否已成功加载并准备好显示。

BannerLoadOptions

将这些选项传递回 SDK，以便在加载横幅时通知它。

回调	描述
public LoadCallback loadCallback { get; set; }	横幅广告已加载并可供展示时触发。
public ErrorCallback errorCallback { get; set; }	在横幅广告加载过程中发生错误时会触发此回调。如果调用此回调，则认为横幅未加载。可在以后再次尝试调用 Load。

Show

用于显示横幅广告内容的基本方法。可根据需要使用多个参数调整此函数。

方法	描述
public static void Show ()	使用默认的 Placement ID 显示横幅广告，不进行回调。
public static void Show (BannerOptions options)	使用默认的 Placement ID 显示横幅广告，但在内容可见时触发 showCallback 回调，并在内容隐藏时触发 [hideCallback]((#banneroptions) 回调。
public static void Show (string placementID)	使用特定的 Placement ID 显示横幅广告，不进行回调。
public static void Show (string placementID, BannerLoadOptions options)	使用特定的 Placement ID 显示横幅广告，但在内容可见时触发 showCallback 回调，并在内容隐藏时触发 [hideCallback]((#banneroptions) 回调。

BannerOptions

将这些选项传递回 SDK，以便向其通知横幅内的事件。

回调	描述
public BannerCallback showCallback { get; set; }	横幅广告对玩家可见时触发此回调。
public BannerCallback hideCallback { get; set; }	横幅广告对玩家不可见时触发此回调。

Hide

此函数允许隐藏横幅广告，而不是完全将其销毁。

public static void Hide (bool destroy = false);

回到顶部

---

• 2018–11–13 页面已发布