# 从 Unity Ads 迁移到 LevelPlay > 从使用 Advertisement 旧版 软件包直接集成 Unity Ads SDK 迁移到 LevelPlay 与 广告服务 Mediation 软件包集成。 > **Note:** > > 从 2026 年 4 月 1 日开始，通过广告旧版软件包直接集成使用 Unity Ads 进行变现的应用可能会降低广告效果。为避免性能下降，请切换到将 Unity Ads 集成为出价者。 > > Unity Ads 网络将继续支持所有使用直接集成的应用程序并提供填充。但是，为了最大限度提高收入和效果，建议的最佳做法是为 Unity 的广告聚合平台 LevelPlay [安装广告服务](/grow/levelplay/sdk/unity/package-integration.md.md)聚合软件包。 本指南介绍如何将项目从直接 Unity Ads SDK 集成过过渡 LevelPlay SDK 集成，包括常见用例的 API 映射。有关更多详细信息，请参阅 [LevelPlay 集成指南](/grow/levelplay/sdk/unity/package-integration.md)。请参阅下表以了解迁移到 LevelPlay 的主要步骤： | 主题 | 描述 | | ------------------------------------------------- | -------------------------------------------- | | [迁移到广告服务聚合](#migrate-to-ads-mediation) | 将项目从旧版 Unity Ads 过渡到 LevelPlay。 | | [贴图 API 和更新代码](#remove-the-legacy-package) | 将旧版初始化、横幅广告、插页式广告和奖励广告调用替换为其 LevelPlay 等效内容。 | | [测试和验证](#test-and-validate) | （可选）使用 LevelPlay 测试套件和内置集成验证工具验证新集成。 | | [API 和功能映射参考](#api-and-feature-mapping-reference) | 回顾旧版 Unity Ads 功能和参数如何映射到相应的 LevelPlay 替代方案。 | | [删除旧版软件包](#map-apis-and-update-code) | 卸载广告旧版软件包并解决项目中的任何剩余依赖项。 | > **Important:** > > 如果将 LevelPlay 安装到仍然使用 Advertisement 旧版 软件包的项目中，项目可能无法正常函数。必须在[将 API 映射到 LevelPlay](#map-apis-and-update-code) 之后删除旧版软件包。 > **Note:** > > 迁移过程仅与通过 Unity Package Manager (UPM) 安装了 Advertisement 旧版 软件包的 Unity 项目相关。 ## 先决条件##prerequisites 确保您有权访问 [LevelPlay 后台](https://platform.ironsrc.com/partners/identity/login)。 ## 迁移到广告服务聚合##migrate-to-ads-mediation 要将旧版 Unity Ads 集成替换为 LevelPlay，请执行以下步骤： ### 安装 LevelPlay 软件包##install-the-levelplay-package 要使用 Unity Package Manager 安装 LevelPlay 软件包，请执行以下步骤： 1. 在 Unity 编辑器中，转到 **Window（窗口）**> **Package Manager（包管理器）**。 2. 选择 **Packages：Unity Registry（Unity 注册表）**。 3. 搜索**广告服务聚合**。 4. 选择 **Install**（安装）以查看最新版本。 ### 配置依赖项##configure-dependencies LevelPlay 需要一个依赖项解析器（如移动端端依赖项解析器或 Unity 外部依赖项管理器 (EDM4U)）来管理 Android 和 iOS。 验证项目中是否安装了依赖项解析器。如果项目已经包含依赖项解析器，请保留该解析器。如果在 LevelPlay 安装后出现提示词要求安装移动端依赖项解析器，请选择 **Yes**。 ### 配置 LevelPlay 控制面板##configure-the-levelplay-dashboard 配置 LevelPlay 后台以注册 app 并创建聚合所需的广告单位。 1. 登录 [LevelPlay 后台](https://platform.ironsrc.com/partners/identity/login)。 2. 选择 **Add app** 并按照提示注册应用程序。 3. 导航到 **Ad Units**（广告单位），然后选择要管理的 app。 4. 创建广告单位（横幅广告、插页式广告或奖励广告）。有关广告单位的更多信息，请参阅[管理广告单位](/grow/levelplay/platform/get-started/ad-units.md)文档。 > **Note:** > > 创建广告单位后，后台会显示每个广告单位的状态、名称、广告单位 ID 和广告格式。广告单元信息还显示链接到广告单元的网络和聚合组的数量。您可以选择要访问实例设置和聚合管理页面的网络或组的数量。 5. 在 LevelPlay Dashboard Apps 页面中，找到并保存 **App Key** 和 **Ad Unit ID**；您需要这些 ID 来[映射 API](#map-apis-and-update-code)。 ## Map API 和更新代代码##map-apis-and-update-code 将现有 `Advertisement` 类调用替换为相应的 `LevelPlay` 方法。与旧版 Unity Ads SDK 不同，LevelPlay 要求您为广告单位创建实例，这些实例是具有可选配置参数的可重用实例。请参阅以下示例来初始化 SDK 并实现横幅广告、插页式广告和奖励广告服务。 ### 初始化 LevelPlay SDK##initialize-the-levelplay-sdk LevelPlay SDK 使用 app 密钥而不是游戏 ID。要注册事件监听器并初始化 SDK，请参阅以下示例： > **Note:** > > 在创建广告对象之前接收 `OnInitSuccess` 回调： ```csharp 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}"); } ``` ### 实现横幅广告服务##implement-banner-ads 要实现横幅广告服务，请参阅以下示例： ```csharp 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) {} } ``` ### 实现插页式广告服务##implement-interstitial-ads 要实现插页式广告服务，请参阅以下示例： ```csharp 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) { } } ``` ### 奖励广告服务##rewarded-ads 要实现奖励广告服务，请参阅以下示例： ```csharp 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}"); } } ``` ## 测试和验证##test-and-validate 要验证您的集成，请构建 app 并运行验证测试。 ### 构建和测试##build-and-test 针对 Android 或 iOS 构建 app 以测试集成。在 LevelPlay 后台中禁用之前，App 将保持测试模式。 ### 启动测试套件（可选）##launch-the-test-suite-(optional) 使用 LevelPlay 集成测试套件可以验证每个广告网络是否已正确配置。 要在 app 中启用 Test Suite，请在设置初始化之前调用 `setMetaData` API： ```csharp LevelPlay.SetMetaData("is_test_suite", "enable"); ``` 成功回调时，启动测试套件： ```csharp LevelPlayEvents.onSdkInitializationCompletedEvent += SdkInitializationCompletedEvent; 私有变量 void SdkInitializationCompletedEvent(){ ... //Launch test suite LevelPlay.LaunchTestSuite(); } ``` ### 验证集成##validate-the-integration 调用以下 API 对软件包和依赖项执行内部检查： ```csharp LevelPlay.ValidateIntegration(); ``` ## 删除旧版软件包##remove-the-legacy-package 在验证所有广告服务都能正常函数并且项目中没有旧版广告 API 后，请按照以下步骤删除 Advertisement 旧版 软件包： 1. 在 Unity 编辑器中，转到 **Window（窗口）**> **Package Manager（包管理器）**。 2. 选择 **Packages：项目**中。 3. 找到并选择 **Advertisement 旧版**。 4. 选择 **Remove**（移除步骤）。 ## API 和功能映射参考##api-and-feature-mapping-reference 使用下表可将旧版 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 不支持 |