Migrate from Unity Ads to LevelPlay

Migrate from direct integration of the Unity Ads SDK using the Advertisement Legacy package to LevelPlay integration with the Ads Mediation package.

阅读时间6 分钟

最后更新于 1 天前

注意

As of January 31, 2026, the Unity Ads network supports in-app bidding only. Unity Ads no longer supports direct integration of the SDK using the Advertisement Legacy package. To monetize with Unity Ads and receive access to all Unity Ads performance feature updates, the recommended best practice is to install the Ads Mediation package for LevelPlay, Unity's ad mediation platform.

This guide explains how to transition your project from direct Unity Ads SDK integration to LevelPlay SDK integration, including API mapping for common use cases. For more details, refer to the LevelPlay integration guide. Refer to the following table for the main steps for migrating to LevelPlay:

Topic	Description
Migrate to Ads Mediation	Transition your project from legacy Unity Ads to LevelPlay.
Map APIs and update code	Replace legacy initialization, banner, interstitial, and rewarded ad calls with their LevelPlay equivalents.
Testing and verification	Optionally, validate your new integration using the LevelPlay Test Suite and the built-in integration validation tools.
API and feature mapping reference	Review how the legacy Unity Ads functions and parameters map to the corresponding LevelPlay alternatives.
Remove the legacy package	Uninstall the Advertisement Legacy package and resolve any remaining dependencies in your project.

重要

If you install LevelPlay into a project that still uses the Advertisement Legacy package, the project might not function correctly. You must remove the legacy package after mapping your APIs to LevelPlay.

注意

The migration process is only relevant for Unity projects with the Advertisement Legacy package installed through the Unity Package Manager (UPM).

Prerequisites

Make sure you have access to the LevelPlay dashboard.

Migrate to Ads Mediation

To replace the legacy Unity Ads integration with LevelPlay, follow these steps:

Install the LevelPlay package

To install the LevelPlay package using the Unity Package Manager, follow these steps:

In the Unity Editor, go to Window > Package Manager.
Select Packages: Unity Registry.
Search for Ads Mediation.
Select Install for the latest version.

Configure dependencies

LevelPlay requires a dependency resolver like the Mobile Dependency Resolver or External Dependency Manager for Unity (EDM4U) to manage Android and iOS libraries. Verify that a dependency resolver is installed in your project. If your project already contains a dependency resolver, keep it. If a prompt appears asking to install Mobile Dependency Resolver after the LevelPlay installation, select Yes.

Configure the LevelPlay dashboard

Configure the LevelPlay dashboard to register your app and create the ad units required for mediation.

Log in to the LevelPlay dashboard.
Select Add App and follow the prompts to register your application.
Navigate to Ad Units and select the app to manage.
Create the desired ad units (Banner, Interstitial, or Rewarded). For more information about ad units, refer to the Manage ad units documentation.

注意

After you create your ad units, the dashboard displays the status, name, ad unit ID, and ad format for each. The ad unit information also displays the number of networks and mediation groups linked to the ad unit. You can select the number of networks or groups to access the Instances setup and Mediation management pages.

In the LevelPlay dashboard Apps page, locate and save your App Key and Ad Unit IDs; you need these to Map APIs.

Map APIs and update code

Replace your existing

Advertisement

class calls with the corresponding

LevelPlay

methods. Unlike the legacy Unity Ads SDK, LevelPlay requires you to create instances for ad units, which are reusable instances with an optional configuration parameter. Refer to the following sample to initialize the SDK and implement Banner, Interstitial, and Rewarded ads.

Initialize the LevelPlay SDK

The LevelPlay SDK uses an App Key instead of a Game ID. To register event listeners and initialize the SDK, refer to the following sample:

注意

Receive the

OnInitSuccess

callback before creating ad objects:


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

To implement Banner ads, refer to the following sample:


public class BannerAdSample {  private 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

To implement interstitial ads, refer to the following sample:


public class InterstitialAdSample {    private 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

To implement rewarded ads, refer to the following sample:


public class LevelPlaySample : MonoBehaviour{    private LevelPlayRewardedAd rewardedAd;        void CreateRewardedAd()    {        rewardedAd = new LevelPlayRewardedAd("YOUR_REWARDED_AD_UNIT_ID");        rewardedAd.OnAdLoaded += OnAdLoaded;        rewardedAd.OnAdLoadFailed += OnAdLoadFailed;        rewardedAd.OnAdDisplayed += OnAdDisplayed;        rewardedAd.OnAdDisplayFailed += OnAdDisplayFailed;        rewardedAd.OnAdRewarded += OnAdRewarded;        rewardedAd.OnAdClicked += OnAdClicked;        rewardedAd.OnAdClosed += OnAdClosed;        rewardedAd.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(string 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

To validate your integration, build the app and run verification tests.

Build and test

Build your app for Android or iOS to test the integration. Your app remains in Test Mode until you disable it in the LevelPlay dashboard.

Launch the Test Suite (Optional)

Use the LevelPlay Integration Test Suite to verify that each ad network is correctly configured. To enable the Test Suite in your app, call the

setMetaData

API before setting the initialization:


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

On success callback, launch the Test Suite:


LevelPlayEvents.onSdkInitializationCompletedEvent += SdkInitializationCompletedEvent;private void SdkInitializationCompletedEvent(){    ...     //Launch test suite    LevelPlay.LaunchTestSuite();}

Validate the integration

Call the following API to perform an internal check of your package and dependencies:


LevelPlay.ValidateIntegration();

Remove the legacy package

After you verify that all ads function correctly and there are no legacy Advertisement APIs in your project, follow these steps to remove the Advertisement Legacy package:

In the Unity Editor, go to Window > Package Manager.
Select Packages: In Project.
Locate and select Advertisement Legacy.
Select Remove.

API and feature mapping reference

Use the following table to map legacy Unity Ads SDK API parameters to the LevelPlay API parameters.

Use case	Unity Ads API parameter	LevelPlay parameter	Notes
Initialization ID	`gameId`	`appKey`	Applicable to both Android and iOS
Initialize SDK	`Advertisement.Initialize(_gameId, _testMode, this);`	`LevelPlay.Init(appKey);`	Test mode isn't supported by LevelPlay
Initialization success event	`IUnityAdsInitializationListener.OnInitializationComplete()`	`LevelPlay.OnInitSuccess`
Init failed event	`IUnityAdsInitializationListener.OnInitializationFailed(error, message)`	`LevelPlay.OnInitFailed`
Is initialized	`Advertisement.isInitialized`	Not supported	Not supported in LevelPlay
Set MetaData	`Advertisement.SetMetaData(metaData)`	`LevelPlay.SetMetaData(key, value)`
Load banner	`Advertisement.Banner.Load(adUnitId, BannerLoadOptions)`	`bannerAd.LoadAd();`	The instance must be created
Display banner	`Advertisement.Banner.Show(adUnitId, BannerOptions)`	`bannerAd.ShowAd()`	The instance must be created
Set banner position	`Advertisement.Banner.SetPosition(BannerPosition.BOTTOM_CENTER)`	`LevelPlayBannerAd bannerAd = new LevelPlayBannerAd(adUnitId, LevelPlayAdSize.BANNER, LevelPlayBannerPosition.TopLeft);`	Use case passed in constructor or builder
Banner load options	`BannerLoadOptions { loadCallback, errorCallback }`	`bannerAd.OnAdLoaded` And `bannerAd.OnAdLoadFailed`
Banner options	`BannerOptions { clickCallback, hideCallback, showCallback }`	`bannerAd.OnAdDisplayed` And `bannerAd.OnAdDisplayFailed` And `bannerAd.OnAdClicked` And `bannerAd.OnAdCollapsed` And `bannerAd.OnAdLeftApplication` And `bannerAd.OnAdExpanded`
Show options	`ShowOptions { resultCallback }` for `Advertisement.Show(...)`	`bannerAd.OnAdDisplayed` And `bannerAd.OnAdDisplayFailed` And `bannerAd.OnAdClicked` And `bannerAd.OnAdCollapsed` And `bannerAd.OnAdLeftApplication` And `bannerAd.OnAdExpanded`
Hide banner	`Advertisement.Banner.Hide()`	`bannerAd.HideAd()`	The instance must be created
Banner clicked	`BannerOptions.clickCallback`	`bannerAd.OnAdClicked`	Event Callback on the instance
Banner shown	`BannerOptions.showCallback`	`bannerAd.OnAdDisplayed`	Event Callback on the instance
Banner hidden	`BannerOptions.hideCallback`	Not supported
Load rewarded ad	`Advertisement.Load(adUnitId, IUnityAdsLoadListener)`	`rewardedAd.LoadAd();`	Instance must be created
Show rewarded ad	`Advertisement.Show(adUnitId, IUnityAdsShowListener)`	`rewardedAd.ShowAd();`	Instance must be created
Load interstitial	`Advertisement.Load(adUnitId, IUnityAdsLoadListener)`	`interstitialAd.LoadAd();`	The instance must be created
Show interstitial	`Advertisement.Show(adUnitId, IUnityAdsShowListener)`	`interstitialAd.ShowAd();`	The instance must be created
Ad loaded	`IUnityAdsLoadListener.OnUnityAdsAdLoaded(adUnitId)`	`interstitialAd.OnAdLoaded` Or `rewardedAd.OnAdLoaded`	Event Callback on the instance
Ad failed to load	`IUnityAdsLoadListener.OnUnityAdsFailedToLoad(adUnitId, error, message)`	`interstitialAd.OnAdLoaded` Or `rewardedAd.OnAdLoaded`	Event Callback on the instance
Ad failed to show	`IUnityAdsShowListener.OnUnityAdsShowFailure(adUnitId, error, message)`	`interstitialAd.OnAdDisplayFailed` Or `rewardedAd.OnAdDisplayFailed`	Event Callback on the instance
Ad show start	`IUnityAdsShowListener.OnUnityAdsShowStart(adUnitId)`	`interstitialAd.OnAdDisplayed` Or `rewardedAd.OnAdDisplayFailed`	Event Callback on the instance
Ad show click	`IUnityAdsShowListener.OnUnityAdsShowClick(adUnitId)`	`interstitialAd.OnAdClicked` Or `rewardedAd.OnAdDisplayFailed`	Event Callback on the instance
Ad show complete	`IUnityAdsShowListener.OnUnityAdsShowComplete(adUnitId, completionState)`	`interstitialAd.OnAdClosed` Or `rewardedAd.OnAdDisplayFailed`	Event Callback on the instance
Is supported	`Advertisement.isSupported`	Not supported	Not supported in LevelPlay
Debug mode	`Advertisement.debugMode = true`	Not supported	Not supported in LevelPlay
Package version	`Advertisement.version`	`LevelPlay.PluginVersion`
Is showing	`Advertisement.isShowing`	Not supported	Not supported in LevelPlay

文档

引擎

服务

增长

工业

支持

LevelPlay SDK - Unity

Unity

Android

iOS

Adobe Air

Flutter

React Native