从 Unity Ads 迁移到 LevelPlay

从使用 Advertisement 旧版软件包直接集成 Unity Ads SDK 迁移到 LevelPlay 与广告服务 Mediation 软件包集成。

阅读时间12 分钟

最后更新于 3 天前

注意

从 2026 年 4 月 1 日开始，通过广告旧版软件包直接集成使用 Unity Ads 进行变现的应用可能会降低广告效果。为避免性能下降，请切换到将 Unity Ads 集成为出价者。

Unity Ads 网络将继续支持所有使用直接集成的应用程序并提供填充。但是，为了最大限度提高收入和效果，建议的最佳做法是为 Unity 的广告聚合平台 LevelPlay 安装广告服务聚合软件包。

本指南介绍如何将项目从直接 Unity Ads SDK 集成过过渡 LevelPlay SDK 集成，包括常见用例的 API 映射。有关更多详细信息，请参阅 LevelPlay 集成指南。请参阅下表以了解迁移到 LevelPlay 的主要步骤：

主题	描述
迁移到广告服务聚合	将项目从旧版 Unity Ads 过渡到 LevelPlay。
贴图 API 和更新代码	将旧版初始化、横幅广告、插页式广告和奖励广告调用替换为其 LevelPlay 等效内容。
测试和验证	（可选）使用 LevelPlay 测试套件和内置集成验证工具验证新集成。
API 和功能映射参考	回顾旧版 Unity Ads 功能和参数如何映射到相应的 LevelPlay 替代方案。
删除旧版软件包	卸载广告旧版软件包并解决项目中的任何剩余依赖项。

重要

如果将 LevelPlay 安装到仍然使用 Advertisement 旧版软件包的项目中，项目可能无法正常函数。必须在将 API 映射到 LevelPlay 之后删除旧版软件包。

注意

迁移过程仅与通过 Unity Package Manager (UPM) 安装了 Advertisement 旧版软件包的 Unity 项目相关。

先决条件

确保您有权访问 LevelPlay 后台。

迁移到广告服务聚合

要将旧版 Unity Ads 集成替换为 LevelPlay，请执行以下步骤：

安装 LevelPlay 软件包

要使用 Unity Package Manager 安装 LevelPlay 软件包，请执行以下步骤：

在 Unity 编辑器中，转到 Window（窗口）> Package Manager（包管理器）。
选择 Packages：Unity Registry（Unity 注册表）。
搜索广告服务聚合。
选择 Install（安装）以查看最新版本。

配置依赖项

LevelPlay 需要一个依赖项解析器（如移动端端依赖项解析器或 Unity 外部依赖项管理器 (EDM4U)）来管理 Android 和 iOS。

验证项目中是否安装了依赖项解析器。如果项目已经包含依赖项解析器，请保留该解析器。如果在 LevelPlay 安装后出现提示词要求安装移动端依赖项解析器，请选择 Yes。

配置 LevelPlay 控制面板

配置 LevelPlay 后台以注册 app 并创建聚合所需的广告单位。

登录 LevelPlay 后台。
选择 Add app 并按照提示注册应用程序。
导航到 Ad Units（广告单位），然后选择要管理的 app。
创建广告单位（横幅广告、插页式广告或奖励广告）。有关广告单位的更多信息，请参阅管理广告单位文档。

注意

创建广告单位后，后台会显示每个广告单位的状态、名称、广告单位 ID 和广告格式。广告单元信息还显示链接到广告单元的网络和聚合组的数量。您可以选择要访问实例设置和聚合管理页面的网络或组的数量。

在 LevelPlay Dashboard Apps 页面中，找到并保存 App Key 和 Ad Unit ID；您需要这些 ID 来映射 API。

Map API 和更新代代码

将现有

Advertisement

类调用替换为相应的

LevelPlay

方法。与旧版 Unity Ads SDK 不同，LevelPlay 要求您为广告单位创建实例，这些实例是具有可选配置参数的可重用实例。请参阅以下示例来初始化 SDK 并实现横幅广告、插页式广告和奖励广告服务。

初始化 LevelPlay SDK

LevelPlay SDK 使用 app 密钥而不是游戏 ID。要注册事件监听器并初始化 SDK，请参阅以下示例：

注意

在创建广告对象之前接收

OnInitSuccess

回调：


LevelPlay.OnInitSuccess += SdkInitializationCompletedEvent;LevelPlay.OnInitFailed += SdkInitializationFailedEvent;LevelPlay.Init("YOUR_APPKEY");void SdkInitializationCompletedEvent(LevelPlayConfiguration config){    Debug.Log($"[LevelPlaySample] Received SdkInitializationCompletedEvent with Config: {config}");}void SdkInitializationFailedEvent(LevelPlayInitError error){    Debug.Log($"[LevelPlaySample] Received SdkInitializationFailedEvent with Error: {error}");	}

要实现横幅广告服务，请参阅以下示例：


public class BannerAdSample {  私有变量 LevelPlayBannerAd bannerAd;    void CreateBannerAd() {    // Create ad configuration - optional    var adConfig = new LevelPlayBannerAd.Config.Builder()      .SetSize(LevelPlayAdSize.BANNER)      .SetPlacementName("placementName")      .SetPosition(LevelPlayBannerPosition.BottomCenter)      .SetDisplayOnLoad(true)      .SetRespectSafeArea(true)      .Build();            // Create banner instance    bannerAd = new LevelPlayBannerAd("YOUR_BANNER_AD_UNIT_ID", adConfig);        // Subscribe BannerAd events    bannerAd.OnAdLoaded += BannerOnAdLoadedEvent;    bannerAd.OnAdLoadFailed += BannerOnAdLoadFailedEvent;    bannerAd.OnAdDisplayed += BannerOnAdDisplayedEvent;    bannerAd.OnAdDisplayFailed += BannerOnAdDisplayFailedEvent;    bannerAd.OnAdClicked += BannerOnAdClickedEvent;    bannerAd.OnAdCollapsed += BannerOnAdCollapsedEvent;    bannerAd.OnAdLeftApplication += BannerOnAdLeftApplicationEvent;    bannerAd.OnAdExpanded += BannerOnAdExpandedEvent;  }    public void LoadBannerAd() {    //Load the banner ad     bannerAd.LoadAd();  }    public void ShowBannerAd() {    //Show the banner ad, call this method only if you turned off the auto show when you created this banner instance.    bannerAd.ShowAd();  }    public void HideBannerAd() {    //Hide banner    bannerAd.HideAd();  }    public void DestroyBannerAd() {    //Destroy banner    bannerAd.DestroyAd();  }    //Implement BannerAd Events  public void BannerOnAdLoadedEvent(LevelPlayAdInfo adInfo) {}  public void BannerOnAdLoadFailedEvent(LevelPlayAdError ironSourceError) {}  public void BannerOnAdClickedEvent(LevelPlayAdInfo adInfo) {}  public void BannerOnAdDisplayedEvent(LevelPlayAdInfo adInfo) {}  public void BannerOnAdDisplayFailedEvent(LevelPlayAdInfo adInfo, LevelPlayAdError error){}  public void BannerOnAdCollapsedEvent(LevelPlayAdInfo adInfo) {}  public void BannerOnAdLeftApplicationEvent(LevelPlayAdInfo adInfo) {}  public void BannerOnAdExpandedEvent(LevelPlayAdInfo adInfo) {}}

实现插页式广告服务

要实现插页式广告服务，请参阅以下示例：


public class InterstitialAdSample {    私有变量 LevelPlayInterstitialAd interstitialAd;        void CreateInterstitialAd() {        // Create InterstitialAd instance        interstitialAd = new LevelPlayInterstitialAd("YOUR_INTERSTITIAL_AD_UNIT_ID");        // Subscribe InterstitialAd events        interstitialAd.OnAdLoaded += InterstitialOnAdLoadedEvent;        interstitialAd.OnAdLoadFailed += InterstitialOnAdLoadFailedEvent;        interstitialAd.OnAdDisplayed += InterstitialOnAdDisplayedEvent;        interstitialAd.OnAdDisplayFailed += InterstitialOnAdDisplayFailedEvent;        interstitialAd.OnAdClicked += InterstitialOnAdClickedEvent;        interstitialAd.OnAdClosed += InterstitialOnAdClosedEvent;        interstitialAd.OnAdInfoChanged += InterstitialOnAdInfoChangedEvent;    }        void LoadInterstitialAd() {        // Load or reload InterstitialAd        interstitialAd.LoadAd();    }        void ShowInterstitialAd() {        // Show InterstitialAd, check if the ad is ready before showing        if (interstitialAd.IsAdReady()) {            interstitialAd.ShowAd();        }    }        void DestroyInterstitialAd() {        // Destroy InterstitialAd        interstitialAd.DestroyAd();    }        // Implement InterstitialAd events    void InterstitialOnAdLoadedEvent(LevelPlayAdInfo adInfo) { }    void InterstitialOnAdLoadFailedEvent(LevelPlayAdError error) { }    void InterstitialOnAdClickedEvent(LevelPlayAdInfo adInfo) { }    void InterstitialOnAdDisplayedEvent(LevelPlayAdInfo adInfo) { }    void InterstitialOnAdDisplayFailedEvent(LevelPlayAdInfo adInfo, LevelPlayAdError error) { }    void InterstitialOnAdClosedEvent(LevelPlayAdInfo adInfo) { }    void InterstitialOnAdInfoChangedEvent(LevelPlayAdInfo adInfo) { }}

奖励广告服务

要实现奖励广告服务，请参阅以下示例：


public class LevelPlaySample : MonoBehaviour{    私有变量 LevelPlayRewardedAd rewardAd;        void CreateRewardedAd()    {        rewardedAd = new LevelPlayRewardedAd("YOUR_REWARDED_AD_UNIT_ID");        rewardAd.OnAdLoaded += OnAdLoaded;        rewardAd.OnAdLoadFailed += OnAdLoadFailed;        rewardAd.OnAdDisplayed += OnAdDisplayed;        rewardAd.OnAdDisplayFailed += OnAdDisplayFailed;        rewardAd.OnAdRewarded += OnAdRewarded;        rewardAd.OnAdClicked += OnAdClicked;        rewardAd.OnAdClosed += OnAdClosed;        rewardAd.OnAdInfoChanged += OnAdInfoChanged;    }        void LoadRewardedAd()    {        rewardedAd.LoadAd();    }        void ShowRewardedAd(string placementName = null)    {        if (rewardedAd.IsAdReady() && !LevelPlayRewardedAd.IsPlacementCapped(placementName))        {            rewardedAd.ShowAd(placementName);        }    }        bool CheckIfRewardedAdIsReady()    {        return rewardedAd.IsAdReady();    }        bool CheckIfPlacementIsCapped(字符串 placementName)    {        return LevelPlayRewardedAd.IsPlacementCapped(placementName);    }        void OnAdLoaded(LevelPlayAdInfo adInfo)    {        Debug.Log($"Rewarded ad loaded with ad info {adInfo}");    }        void OnAdLoadFailed(LevelPlayAdError adError)    {        Debug.Log($"Rewarded ad failed to load with ad error {adError}");    }       void OnAdDisplayed(LevelPlayAdInfo adInfo)    {        Debug.Log($"Rewarded ad displayed with ad info {adInfo}");    }           void OnAdDisplayFailed(LevelPlayAdDisplayInfoError adInfoError)    {        Debug.Log($"Rewarded ad failed to display with ad info and error {adInfoError}");    }        void OnAdRewarded(LevelPlayAdInfo adInfo, LevelPlayReward adReward)    {        Debug.Log($"Rewarded ad gained reward with adInfo {adInfo} and reward {adReward}");    }        void OnAdClicked(LevelPlayAdInfo adInfo)    {        Debug.Log($"Rewarded ad clicked with ad info {adInfo}");    }        void OnAdClosed(LevelPlayAdInfo adInfo)    {        Debug.Log($"Rewarded ad closed with ad info {adInfo}");    }        void OnAdInfoChanged(LevelPlayAdInfo adInfo)    {        Debug.Log($"Rewarded ad info changed with ad info {adInfo}");    }    }

测试和验证

要验证您的集成，请构建 app 并运行验证测试。

构建和测试

针对 Android 或 iOS 构建 app 以测试集成。在 LevelPlay 后台中禁用之前，App 将保持测试模式。

启动测试套件（可选）

使用 LevelPlay 集成测试套件可以验证每个广告网络是否已正确配置。

要在 app 中启用 Test Suite，请在设置初始化之前调用

setMetaData

API：


LevelPlay.SetMetaData("is_test_suite", "enable");

成功回调时，启动测试套件：


LevelPlayEvents.onSdkInitializationCompletedEvent += SdkInitializationCompletedEvent;私有变量 void SdkInitializationCompletedEvent(){    ...    //Launch test suite    LevelPlay.LaunchTestSuite();}

验证集成

调用以下 API 对软件包和依赖项执行内部检查：


LevelPlay.ValidateIntegration();

删除旧版软件包

在验证所有广告服务都能正常函数并且项目中没有旧版广告 API 后，请按照以下步骤删除 Advertisement 旧版软件包：

在 Unity 编辑器中，转到 Window（窗口）> Package Manager（包管理器）。
选择 Packages：项目中。
找到并选择 Advertisement 旧版。
选择 Remove（移除步骤）。

API 和功能映射参考

使用下表可将旧版 Unity Ads SDK API 参数映射到 LevelPlay API 参数。

用例	Unity Ads API 参数	LevelPlay 参数	注意
初始化 ID	`gameId`	`appKey`	适用于 Android 和 iOS
初始化 SDK	`Advertisement.Initialize(_gameId, _testMode, this);`	`LevelPlay.Init(appKey);`	LevelPlay 不支持测试模式
初始化成功事件	`IUnityAdsInitializationListener.OnInitializationComplete()`	`LevelPlay.OnInitSuccess`
Init 失败事件	`IUnityAdsInitializationListener.OnInitializationFailed(error, message)`	`LevelPlay.OnInitFailed`
已初始化	`Advertisement.isInitialized`	不支持	LevelPlay 不支持
设置 MetaData	`Advertisement.SetMetaData(metaData)`	`LevelPlay.SetMetaData(key, value)`
加载横幅	`Advertisement.Banner.Load(adUnitId, BannerLoadOptions)`	`bannerAd.LoadAd();`	必须创建实例
显示横幅	`Advertisement.Banner.Show(adUnitId, BannerOptions)`	`bannerAd.ShowAd()`	必须创建实例
设置横幅位置	`Advertisement.Banner.SetPosition(BannerPosition.BOTTOM_CENTER)`	`LevelPlayBannerAd bannerAd = new LevelPlayBannerAd(adUnitId, LevelPlayAdSize.BANNER, LevelPlayBannerPosition.TopLeft);`	在构造函数或构建器中传递的用例
横幅加载选项	`BannerLoadOptions { loadCallback, errorCallback }`	`bannerAd.OnAdLoaded` 和 `bannerAd.OnAdLoadFailed`
Banner 选项	`BannerOptions { clickCallback, hideCallback, showCallback }`	`bannerAd.OnAdDisplayed` 和 `bannerAd.OnAdDisplayFailed` 和 `bannerAd.OnAdClicked` 和 `bannerAd.OnAdCollapsed` 和 `bannerAd.OnAdLeftApplication` 和 `bannerAd.OnAdExpanded`
显示选项	`Advertisement.Show(...)` 的 `ShowOptions { resultCallback }`	`bannerAd.OnAdDisplayed` 和 `bannerAd.OnAdDisplayFailed` 和 `bannerAd.OnAdClicked` 和 `bannerAd.OnAdCollapsed` 和 `bannerAd.OnAdLeftApplication` 和 `bannerAd.OnAdExpanded`
隐藏横幅	`Advertisement.Banner.Hide()`	`bannerAd.HideAd()`	必须创建实例
单击的横幅	`BannerOptions.clickCallback`	`bannerAd.OnAdClicked`	实例上的事件回调
显示的横幅	`BannerOptions.showCallback`	`bannerAd.OnAdDisplayed`	实例上的事件回调
横幅隐藏	`BannerOptions.hideCallback`	不支持
加载奖励广告	`Advertisement.Load(adUnitId, IUnityAdsLoadListener)`	`rewardedAd.LoadAd();`	必须创建实例
显示奖励广告	`Advertisement.Show(adUnitId, IUnityAdsShowListener)`	`rewardedAd.ShowAd();`	必须创建实例
加载插屏广告	`Advertisement.Load(adUnitId, IUnityAdsLoadListener)`	`interstitialAd.LoadAd();`	必须创建实例
显示插屏广告	`Advertisement.Show(adUnitId, IUnityAdsShowListener)`	`interstitialAd.ShowAd();`	必须创建实例
已加载广告	`IUnityAdsLoadListener.OnUnityAdsAdLoaded(adUnitId)`	`interstitialAd.OnAdLoaded` 或 `rewardedAd.OnAdLoaded`	实例上的事件回调
广告加载失败	`IUnityAdsLoadListener.OnUnityAdsFailedToLoad(adUnitId, error, message)`	`interstitialAd.OnAdLoaded` 或 `rewardedAd.OnAdLoaded`	实例上的事件回调
广告无法显示	`IUnityAdsShowListener.OnUnityAdsShowFailure(adUnitId, error, message)`	`interstitialAd.OnAdDisplayFailed` 或 `rewardedAd.OnAdDisplayFailed`	实例上的事件回调
广告展示开始	`IUnityAdsShowListener.OnUnityAdsShowStart(adUnitId)`	`interstitialAd.OnAdDisplayed` 或 `rewardedAd.OnAdDisplayFailed`	实例上的事件回调
广告展示点击	`IUnityAdsShowListener.OnUnityAdsShowClick(adUnitId)`	`interstitialAd.OnAdClicked` 或 `rewardedAd.OnAdDisplayFailed`	实例上的事件回调
广告展示完成	`IUnityAdsShowListener.OnUnityAdsShowComplete(adUnitId, completionState)`	`interstitialAd.OnAdClosed` 或 `rewardedAd.OnAdDisplayFailed`	实例上的事件回调
受支持	`Advertisement.isSupported`	不支持	LevelPlay 不支持
调试模式	`Advertisement.debugMode = true`	不支持	LevelPlay 不支持
软件包本	`Advertisement.version`	`LevelPlay.PluginVersion`
正在显示	`Advertisement.isShowing`	不支持	LevelPlay 不支持