# Unity Ads 레벨플레이 마이그레이션 > Advertisement 레거시 패키지를 사용하는 Unity Ads SDK의 직접 통합에서 Ads Mediation 패키지와 레벨플레이 통합으로 마이그레이션합니다. > **Note:** > > 2026년 4월 1일부터 Advertisement 레거시 패키지를 통한 직접 연동을 통해 Unity Ads 수익을 창출하는 앱 광고 성과가 저하될 수 있습니다. 성과 저하를 방지하려면 입찰자로 Unity Ads 통합으로 전환하십시오. > > Unity Ads 네트워크는 계속해서 직접 통합을 사용하여 모든 앱 Fill을 지원하고 제공합니다. 그러나 수익과 성과를 극대화하기 위해 Unity의 광고 Mediation 플랫폼인 [LevelPlay용 Ads Mediation 패키지를 설치하는](/grow/levelplay/sdk/unity/package-integration.md.md) 것이 좋습니다. 이 가이드에서는 일반적인 사용 사례에 대한 API 매핑을 비롯하여 프로젝트를 직접 Unity Ads SDK 통합에서 레벨플레이 SDK 통합으로 전환 방법을 설명합니다. 자세한 내용은 [레벨플레이 통합 가이드](/grow/levelplay/sdk/unity/package-integration.md)를 참조하십시오. 레벨플레이 마이그레이션하는 주요 단계는 다음 표를 참고하십시오. | 항목 | 설명 | | ------------------------------------------------------ | ------------------------------------------------------ | | [광고 Mediation으로 마이그레이션](#migrate-to-ads-mediation) | 레거시 Unity Ads에서 레벨플레이로 프로젝트 전환 | | [맵 API 및 업데이트 코드](#map-apis-and-update-code) | 레거시 초기화, 배너, 인터스티셜 광고 및 보상형 광고를 레벨플레이에 해당하는 광고로 교체합니다. | | [테스트 및 검증](#test-and-validate) | 선택 사항으로 레벨플레이 테스트 제품군과 빌트인 통합 확인 툴을 사용하여 새 통합을 검증합니다. | | [API 및 기능 매핑 레퍼런스](#api-and-feature-mapping-reference) | 레거시 Unity Ads 기능과 파라미터가 해당 레벨플레이 대안에 매핑되는 방법을 검토합니다. | | [레거시 패키지 제거](#remove-the-legacy-package) | Advertisement 레거시 패키지를 제거하고 프로젝트의 남은 종속성을 결정합니다. | > **Important:** > > Advertisement 레거시 패키지를 계속 사용하는 프로젝트에 레벨플레이 설치하면 프로젝트가 제대로 함수 않을 수 있습니다. [API를 레벨플레이에 매핑](#map-apis-and-update-code)한 후 레거시 패키지를 제거해야 합니다. > **Note:** > > 마이그레이션 프로세스는 Unity 패키지 관리자(UPM)를 통해 Advertisement 레거시 패키지가 설치된 Unity 프로젝트에만 해당합니다. ## 필수 조건##prerequisites [레벨플레이 대시보드](https://platform.ironsrc.com/partners/identity/login)에 액세스, 접근할 수 있는지 확인합니다. ## Ads Mediation 마이그레이션##migrate-to-ads-mediation 레거시 Unity Ads 연동을 레벨플레이 대체하려면 다음 단계를 따르십시오. ### 레벨플레이 패키지 설치##install-the-levelplay-package Unity 패키지 관리자 사용하여 레벨플레이 패키지를 설치하려면 다음 단계를 따르십시오. 1. Unity 에디터에서 **Window** > **Package Manager**로 이동합니다. 2. 선택 **패키지: Unity Registry**를 선택합니다. 3. 검색 **광고 Mediation**. 4. 최신 버전의 경우 **설치**를 선택합니다. ### 종속성 구성##configure-dependencies 레벨플레이 Android 및 iOS 라이브러리를 관리하려면 Mobile Dependency Resolver 또는 Unity 외부 종속성 관리자(EDM4U)와 같은 종속성 리솔러가 필요합니다. 프로젝트에 종속성 리셀러가 설치되어 있는지 확인합니다. 프로젝트에 이미 종속성 리셀러가 포함되어 있으면 유지하세요. 레벨플레이 설치 후에 Mobile Dependency Resolver를 설치하라는 프롬프트가 나타나면 **Yes**를 선택합니다. ### 레벨플레이 대시보드 설정##configure-the-levelplay-dashboard 레벨플레이 대시보드를 설정 앱을 등록하고 Mediation 필요한 광고 유닛을 생성합니다. 1. [레벨플레이 대시보드](https://platform.ironsrc.com/partners/identity/login)에 로그인합니다. 2. **Add App**을 선택하고 프롬프트에 따라 애플리케이션을 등록합니다. 3. **광고 유닛**으로 이동하여 관리할 앱을 선택합니다. 4. 광고 유닛을 생성합니다(배너, 인터스티셜 광고 또는 보상형 광고). 광고 유닛에 대한 자세한 내용은 [광고 유닛 관리](/grow/levelplay/platform/get-started/ad-units.md) 기술 자료를 참고하십시오. > **Note:** > > 광고 유닛을 생성하면 대시보드에 각각의 상태, 이름, 광고 유닛 ID, 광고 형식이 표시됩니다. 광고 유닛 정보에는 광고 유닛에 연결된 네트워크 및 Mediation 그룹 수도 표시됩니다. 인스턴스 설정 및 Mediation 관리 페이지에 액세스, 접근 수 있는 네트워크 또는 그룹 수를 선택할 수 있습니다. 5. 레벨플레이 대시보드 앱 페이지에서 **앱 키** 및 **광고 유닛 ID**를 찾아 저장합니다. 이 ID는 [맵 API](#map-apis-and-update-code)에 필요합니다. ## 맵 API 및 코드 업데이트##map-apis-and-update-code 기존의 `Advertisement` 클래스 호출을 해당하는 `LevelPlay` 메서드로 교체합니다. 레거시 Unity Ads SDK와 달리, 레벨플레이 광고 유닛의 인스턴스를 생성해야 합니다. 광고 유닛은 선택적 설정 파라미터 있는 재사용 가능한 인스턴스입니다. SDK를 초기화하고 배너 광고, 인터스티셜 광고 광고, 보상형 광고 광고를 구현하려면 다음 샘플을 참고하십시오. ### 레벨플레이 SDK 초기화##initialize-the-levelplay-sdk 레벨플레이 SDK는 게임 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 { 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 인터스티셜 광고 구현하려면 다음 샘플을 참고하십시오. ```csharp 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 보상형 광고 광고를 구현하려면 다음 샘플을 참고하십시오. ```csharp 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(문자열 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 연동을 확인하려면 앱을 빌드 확인 테스트를 실행합니다. ### 빌드 및 테스트##build-and-test Android 또는 iOS용 앱을 빌드 통합을 테스트합니다. 앱은 레벨플레이 대시보드에서 비활성화하다, 무효화하다, 사용 안 함 때까지 테스트 모드 상태로 유지됩니다. ### Test Suite 실행(선택 사항)##launch-the-test-suite-optional 레벨플레이 통합 테스트 제품군을 사용하여 각 광고 네트워크가 올바르게 구성되었는지 확인합니다. 앱에서 Test Suite를 활성화하려면 초기화를 설정하기 전에 `setMetaData` API를 호출합니다. ```csharp LevelPlay.SetMetaData("is_test_suite", "enable"); ``` 성공 콜백 시 Test Suite 실행: ```csharp LevelPlayEvents.onSdkInitializationCompletedEvent += SdkInitializationCompletedEvent; private void SdkInitializationCompletedEvent(){ ... //Launch test suite LevelPlay.LaunchTestSuite(); } ``` ### 연동 확인##validate-the-integration 다음 API 호출 패키지 및 종속성에 대한 내부 검사를 수행합니다. ```csharp LevelPlay.ValidateIntegration(); ``` ## 레거시 패키지 제거##remove-the-legacy-package 모든 광고가 올바르게 함수 프로젝트에 레거시 Advertisement API가 없는지 확인한 후 다음 단계에 따라 Advertisement 레거시 패키지를 제거합니다. 1. Unity 에디터에서 **Window** > **Package Manager**로 이동합니다. 2. 선택 **패키지: In Project**. 3. 찾아서 **광고 레거시**를 선택합니다. 4. **제거**를 선택합니다. ## API 및 기능 매핑 레퍼런스##api-and-feature-mapping-reference 다음 표를 사용하여 레거시 Unity Ads SDK API 파라미터를 레벨플레이 API 파라미터에 맵. | 사용 사례 | Unity Ads API 파라미터 | 레벨플레이 파라미터 | 참고 사항 | | -------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | | 초기화 ID | `gameId` | `appKey` | Android와 iOS 모두에 적용 | | Initialize SDK | `Advertisement.Initialize(_gameId, _testMode, this);` | `LevelPlay.Init(appKey);` | 테스트 모드는 레벨플레이에서 지원되지 않습니다. | | 초기화 성공 이벤트 | `IUnityAdsInitializationListener.OnInitializationComplete()` | `LevelPlay.OnInitSuccess` | | | Init 이벤트 실패 | `IUnityAdsInitializationListener.OnInitializationFailed(error, message)` | `LevelPlay.OnInitFailed` | | | 초기화됨 | `Advertisement.isInitialized` | 지원 안 함 | 레벨플레이 지원되지 않음 | | 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` | | | 배너 옵션 | `BannerOptions { clickCallback, hideCallback, showCallback }` | `bannerAd.OnAdDisplayed`및`bannerAd.OnAdDisplayFailed`및`bannerAd.OnAdClicked`및`bannerAd.OnAdCollapsed`및`bannerAd.OnAdLeftApplication`및`bannerAd.OnAdExpanded` | | | 옵션 표시 | `ShowOptions { resultCallback }`: `Advertisement.Show(...)` | `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` | 지원 안 함 | 레벨플레이 지원되지 않음 | | 디버그 모드 | `Advertisement.debugMode = true` | 지원 안 함 | 레벨플레이 지원되지 않음 | | 패키지 버전 | `Advertisement.version` | `LevelPlay.PluginVersion` | | | 표시 중 | `Advertisement.isShowing` | 지원 안 함 | 레벨플레이 지원되지 않음 |