api deprecation - Unity-Technologies/unity-ads GitHub Wiki
/*
Title: API deprecation guidelines
Sort: 100
*/
Important: These guidelines are effective beginning with the release of Unity Ads SDK 4.0.0.
You are encouraged to use the best API set that meets your needs at the time of development. However, Unity encourages all developers to update to the latest SDK version as frequently as possible.
In order to ensure that Unity Ads delivers an optimized and consistent development experience, it must continue to evolve and extend the SDK and its API classes. As we adapt to platform and market changes, API classes become obsolete and need to be replaced by more effective versions.
In the event that Unity Ads intends to remove an API class, or alter it in a manner that breaks the previously supported functionality, Unity will endeavor to:
- Label the API as deprecated, note the deprecation in the release notes, and (if applicable) update documentation and samples to provide a preferred alternative in the next major or minor release;
- Remove the deprecated API in a future major release; and
- Use reasonable efforts to provide no less than three (3) months’ notice of the removal of a deprecated API via a Deprecation Notice (see Notifications).
Exceptions to the aforementioned deprecation guidelines are cases where:
- Unity Ads must remove an API as a result of a change in applicable law or its rights under contract;
- Continuing to provide the functionality could create a security, compliance, data privacy or other regulatory risk, or otherwise expose Unity and/or its third party partners and clients to any risk of liability or harm (as determined by Unity in it sole discretion); or
- Continuing to provide the functionality could create a substantial economic or technical burden to Unity or to its third party partners and clients (including by overburdening, or threatening the integrity, performance or availability of, any underlying Unity services), as determined by Unity in its sole discretion.
If an API becomes obsolete, Unity Ads will use reasonable efforts to provide a Deprecation Notice via one or more of the following:
- Developer communication(s) to the Monetization dashboard. The post will contain the Deprecation Notice, the alternative API (if available), and the target SDK version for removal;
- Official technical documentation updates containing the alternative API (if available); or
- Updates to the SDK changelog in a section that contains links to more detailed information about which classes are being deprecated, applicable replacement classes, and the projected end of life date.
Wherever possible, API classes and their supported functionality are maintained in a manner that is compatible with earlier versions. If it is necessary to change something in a way that is not backwards compatible, Unity Ads will create a new resource, media type, or version, and the old resource or media type will be maintained in accordance with the API deprecation policy.
Unity Ads will provide the following information for all announced deprecations:
| API to be removed | Deprecated in version | Removed in version | Depreciation reason |
oldExampleAPI
|
3.7.4 | Future major release | Replace with newExampleAPI
|
These guidelines are subject to change without notice, and Unity reserves the right to modify its API deprecation process in its sole discretion and at any time.
Deprecated API classes may still be used but are no longer supported moving forward and will be removed in a future release.
Provides advanced notification that an API class will be replaced in an upcoming SDK release. This is a good time for developers to upgrade their code.
The Unity Ads SDK follows semantic versioning standards. API classes will only be removed in major version releases.
Unity tries to provide backward compatibility of all public APIs documented in the API reference. Developers must use the supported APIs listed in the API reference to ensure compatibility.
The following API classes are deprecated or obsolete for the Unity SDK:
| API to be removed | Deprecated in version | What to use instead | Removed in version | Depreciation reason |
IsReady()
|
NA | Use the updated Load method signature to access load callbacks. |
4.0.0 | No longer required with Load and Show functionality. |
IsReady(string placementId)
|
NA | Use the updated Load method signature to access load callbacks. |
4.0.0 | No longer required with Load and Show functionality. |
AddListener(IUnityAdsListener listener)
|
NA | Use the Initialize, Load, and Show methods' listeners. |
4.0.0 | Improved callbacks for Load and Show APIs. |
RemoveListener(IUnityAdsListener listener)
|
NA | Use the Initialize, Load, and Show methods' listeners. |
4.0.0 | Improved callbacks for Load and Show APIs. |
GetPlacementState()
|
NA | No direct replacement. | 4.0.0 | Improved callbacks for Load and Show APIs. |
GetPlacementState(string placementId)
|
NA | No direct replacement. | 4.0.0 | No longer required with Load and Show functionality.
|
IUnityAdsListener
|
NA | Use the IUnityAdsInitializationListener, IUnityAdsLoadListener, and IUnityAdsShowListener interfaces. |
4.0.0 | Improved callbacks for Load and Show APIs. |
Show()
|
NA | Use the Show(string placementId) method signature to specify an Ad Unity ID.
|
4.0.0 | Updated Load and Show functionality.
|
ShowOptions.resultCallback
|
3.1.0 | Use the IUnityAdsShowListener interface callbacks.
|
4.0.0 | Updated Load and Show functionality.
|
The following API classes are deprecated or obsolete for the Android SDK:
| API to be removed | Deprecated in version | What to use instead | Removed in version | Depreciation reason |
initialize(final Activity activity, final String gameId, final IUnityAdsListener listener)
|
3.4.0 | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
initialize(final Activity activity, final String gameId)
|
3.4.0 | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
initialize(final Activity activity, final String gameId, final IUnityAdsInitializationListener initializationListener)
|
3.4.0 | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
initialize(final Activity activity, final String gameId, final IUnityAdsListener listener, final boolean testMode)
|
3.4.0 | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
initialize(final Activity activity, final String gameId, final boolean testMode)
|
3.4.0 | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
initialize(final Activity activity, final String gameId, final boolean testMode, final IUnityAdsInitializationListener initializationListener)
|
3.4.0 | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
initialize(final Activity activity, final String gameId, final IUnityAdsListener listener, final boolean testMode, final boolean enablePerPlacementLoad)
|
3.4.0 | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API. |
initialize(final Activity activity, final String gameId, final boolean testMode, final boolean enablePerPlacementLoad)
|
3.4.0 | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
initialize(final Activity activity, final String gameId, final boolean testMode, final boolean enablePerPlacementLoad, final IUnityAdsInitializationListener initializationListener)
|
3.4.0 | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
initialize(final Context context, final String gameId, final boolean testMode, final boolean enablePerPlacementLoad)
|
NA | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
initialize(final Context context, final String gameId, final boolean testMode, final boolean enablePerPlacementLoad, final IUnityAdsInitializationListener initializationListener)
|
NA | Use the consolidated initialize method signature. |
4.0.0 | Replaced by consolidated initialize API.
|
setListener(IUnityAdsListener listener)
|
3.4.0 | Use the initialize, load, and show methods' listeners. |
4.0.0 | Improved callbacks for Show and Load APIs.
|
getListener()
|
3.4.0 | Use the initialize, load, and show methods' listeners. |
4.0.0 | Improved callbacks for Show and Load APIs.
|
addListener(IUnityAdsListener listener)
|
NA | Use the initialize, load, and show methods' listeners. |
4.0.0 | Improved callbacks for Show and Load APIs.
|
removeListener(IUnityAdsListener listener)
|
NA | Use the initialize, load, and show methods' listeners. |
4.0.0 | Improved callbacks for Show and Load APIs.
|
isReady()
|
3.7.1 | Use the updated load method signature to access load callbacks. |
4.0.0 | Introduced a Load API with callbacks.
|
isReady(String placementId)
|
3.7.1 | Use the updated load method signature to access load callbacks. |
4.0.0 | Introduced a Load API with callbacks.
|
getPlacementState()
|
NA | No direct replacement. | 4.0.0 | No longer required with Load and Show functionality.
|
show(final Activity activity)
|
3.7.0 | Use the updated show method signature to access show callbacks.
|
4.0.0 | Introduced a Show API with callbacks.
|
IUnityAdsListener
|
NA | Use the IUnityAdsInitializationListener, IUnityAdsLoadListener, IUnityAdsShowListener
interfaces. |
4.0.0 | Improved callbacks for Show and Load APIs. |
IUnityAdsExtendedListener
|
NA | Use the IUnityAdsShowListener interface. |
4.0.0 | Improved callbacks for Show and Load APIs.
|
com.unity3d.services.monetization
|
NA | Use the UnityAds.java API. |
4.0.0 | Legacy Monetization API not supported.
|
com.unity3d.services.purchasing
|
NA | No direct replacement. | 4.0.0 | Legacy Monetization API not supported.
|
The following API classes are deprecated or obsolete for the iOS SDK:
<<<<<<< HEAD| API to be removed | Deprecated in version | What to use instead | Removed in version | Depreciation reason | |
UnityAdsDelegate
|
NA | Use the UnityAdsInitializationDelegate, UnityAdsLoadDelegate, and UnityAdsShowDelegate interfaces.
|
4.0.0 | Replaced by consolidated Initialize API.
|
|
UnityAdsDelegateUtil |
NA | Use the UnityAdsInitializationDelegate, UnityAdsLoadDelegate, and UnityAdsShowDelegate interfaces.
|
4.0.0 | Replaced by consolidated Initialize API. |
|
UADSInAppPurchaseMetaData
|
NA | No direct replacement; however you can use the generic MetaData class.
|
4.0.0 | Replaced by consolidated Initialize API. |
|
UnityAdsExtendedDelegate
|
NA | Use the UnityAdsInitializationDelegate, UnityAdsLoadDelegate, and UnityAdsShowDelegate interfaces.
|
4.0.0 | Replaced by consolidated Initialize API. |
|
|
|
3.4.0 |
Use the consolidated |
4.0.0 | Replaced by consolidated Initialize API.
|
|
initialize: (NSString *)gameId
|
3.4.0 |
Use the consolidated |
4.0.0 | Replaced by consolidated Initialize API. | |
initialize: (NSString *)gameId
|
3.4.0 |
Use the consolidated |
4.0.0 | Replaced by consolidated Initialize API. | |
initialize: (NSString *)gameId
|
3.4.0 |
Use the consolidated |
4.0.0 | Replaced by consolidated initialize API.
|
|
initialize: (NSString *)gameId
|
3.4.0 |
Use the consolidated |
4.0.0 | Replaced by consolidated initialize API.
|
|
show: (UIViewController *)viewController
|
3.7.0 |
Use the updated |
4.0.0 | Introduced a show API with callbacks.
|
|
show: (UIViewController *)viewController
=======
|
show: (UIViewController \*)viewController
>>>>>>> 7de6e9a57ea35748a692aba55aede2e7f7f81fa9
|
3.7.0 |
Use the updated |
4.0.0 | Introduced a show API with callbacks.
|
show: (UIViewController *)viewController
|
3.7.0 |
Use the updated |
4.0.0 | Introduced a Show API with callbacks.
|
|
getDelegate
|
3.4.0 | Use the initialize, load, and show methods' delegate interfaces.
|
4.0.0 | No longer required with Load and Show functionality.
|
|
setDelegate: (id<UnityAdsDelegate>)delegate
|
3.4.0 | Use the initialize, load, and show methods' delegate interfaces. |
4.0.0 | No longer required with Load and Show functionality. |
|
addDelegate: (__nullable id<UnityAdsDelegate>)delegate
|
3.7.0 | Use the initialize, load, and show methods' delegate interfaces. |
4.0.0 | No longer required with Load and Show functionality. |
|
removeDelegate: (id<UnityAdsDelegate>)delegate;
|
NA | Use the initialize, load, and show methods' delegate interfaces.
|
4.0.0 | No longer required with Load and Show functionality. | |
isReady
|
3.7.1 |
Use the updated |
4.0.0 | Introduced a load API with callbacks.
|
|
isReady: (NSString *)placementId
|
3.7.1 |
Use the updated |
4.0.0 | Introduced a load API with callbacks. |
|
getPlacementState
|
NA | No direct replacement. | 4.0.0 | No longer required with Load and Show functionality.
|
|
getPlacementState: (NSString *)placementId
|
NA | No direct replacement. | 4.0.0 | No longer required with Load and Show functionality. |
|
All of the monetization classes |
3.4.0 | Use the UnityAdvertisement.h class. |
4.0.0 | Legacy Monetization API not supported. |
|
All of the purchasing classes |
3.4.0 | No direct replacement. | 4.0.0 | Legacy Monetization API not supported. |