Unity Ads iOS SDK API reference
Access the Unity Ads SDK public API reference to view available classes, methods, and properties you can use in Objective-C or Swift to integrate and control ad behavior in your iOS app.
Read time 8 minutesLast updated a day ago
Use the
UnityAds.hThis article contains the following API documentation: Classes Enums#import "UnityAds.h"
UnityAdsBannerPositionUnityAdsInitializationErrorUnityAdsLoadErrorUnityAdsShowErrorUnityAdsError
UnityAdsInitializationDelegateUnityAdsLoadDelegateUnityAdsShowDelegateUADSBannerDelegateUADSBannerAdRefreshViewDelegate
Classes
UnityAds
Use this namespace to implement basic ad content, such as rewarded or non-rewarded video, interstitial, or banner ads.#import <UnityAds/UnityAds.h>
initialize
Initializes the ads service, with a specified Game ID, test mode status, and initialization delegate.+ (void) initialize: (NSString *)gameId testMode: (BOOL)testMode initializationDelegate: (nullable id<UnityAdsInitializationDelegate>)initializationDelegate;}
Parameter | Description |
|---|---|
| The platform-specific Unity game identifier for your project, found on the Unity Monetization Dashboard. |
| Use Test mode to test your integration without serving live ads. Use |
| Optionally enables the SDK with |
load
Loads ad content for a specified ad unit. You must call+ (void)load: (NSString *)placementId options: (UADSLoadOptions *)options loadDelegate: (nullable id<UnityAdsLoadDelegate>)loadDelegate { [UADSLoadModule.sharedInstance loadForPlacementID: placementId options: options loadDelegate: loadDelegate];}
loadshowParameter | Description |
|---|---|
| The identifier for the ad unit you want to load with ad content. |
| A collection of options for modifying ad load behavior. |
| Optionally loads ad content with |
isReady
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
Returns+ (BOOL)isReady: (NSString *)adUnitId { return [UnityServices isSupported] && [UnityServices isInitialized] && [UADSPlacement isReady: adUnitId];}
YESenablePerPlacementLoadloadshowParameter | Description |
|---|---|
| The identifier for the ad dnit you want to query. |
Note
If you call without specifying an ad unit ID, the method returns results for the Unity Standard Placement.
isReadyshow
Displays loaded ad content in a specified ad unit.+ (void)show: (UIViewController *)viewController placementId: (NSString *)placementId showDelegate: (nullable id<UnityAdsShowDelegate>)showDelegate { [self show: viewController adUnitId: placementId options: [UADSShowOptions new] showDelegate: showDelegate];}
Parameter | Description |
|---|---|
| The identifier for the ad unit you want to show. |
| A collection of options for modifying ad show behavior. |
| Optionally shows content with |
Note
If you call without specifying an ad unit ID, the method shows loaded content in the Unity Standard Placement. In SDK versions 4.0 and later, you must call this method with an ad unit ID.
showaddDelegate
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
Adds a listener delegate that will recieve Unity Ads callbacks. In versions 3.1.0 and later, you can register multiple listeners. This is especially helpful for mediation customers.+ (void)addDelegate: (__nullable id<UnityAdsDelegate>)delegate { [UADSProperties addDelegate: delegate];}
Parameter | Description |
|---|---|
| A listener for Unity Ads callbacks. |
removeDelegate
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
Removes an active+ (void)removeDelegate: (id<UnityAdsDelegate>)delegate { [UADSProperties removeDelegate: delegate];}
UnityAdsDelegateParameter | Description |
|---|---|
| A listener for Unity Ads callbacks. |
setDebugMode
Controls the amount of logging output from the SDK. Set to+ (BOOL)getDebugMode { return [UnityServices getDebugMode];}
YESgetDebugMode
Returns+ (void)getDebugMode: (BOOL)enableDebugMode { [UnityServices setDebugMode: enableDebugMode];}
YESNOgetVersion
Returns the current version of the Unity Ads SDK.+ (NSString *)getVersion { return [UnityServices getVersion];}
isInitialized
Returns+ (BOOL)isInitialized { return [USRVSdkProperties isInitialized];}
YESNOUADSLoadOptions
This class contains optional metadata to include with the#import <UnityAds/UADSBaseOptions.h>@interface UADSLoadOptions : UADSBaseOptions@property (nonatomic, readwrite) NSString *adMarkup;@end
loadsetAdMarkup
This method takes the ad markup returned from the bidder service. When a bidder from Unity's ad network wins a header bidding auction, the Unity Ads SDK receives ad markup from the mediated exchange. The ad markup string contains information needed for Unity to load and show the ad.- (void)setAdMarkup: (NSString *)adMarkup
UADSBannerView
Use this class to implement banner ads. Unity Ads versions 3.3 and later support multiple banner instances through a single ad unit.@interface UADSBannerView : UIView
initWithPlacementId
Implements a banner view using an ad unit ID and banner size. Call-(instancetype)initWithPlacementId:(NSString *)placementId size:(CGSize)size;
initWithPlacementIdloadUADSBannerViewDelegateParameter | Description |
|---|---|
| The banner's ad unit ID. |
| The |
Note
Using to call a banner ad attempts to load content once, with no refreshing. If the banner returns no fill, you can destroy it and create a new one to try again. Unity recommends this method for mediated customers.
UADSBannerViewload
The basic method for requesting an ad for the banner.- (void)load;
Enums
UnityAdsPlacementState
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
The enumerated states of an ad unit.typedef NS_ENUM(NSInteger, UnityAdsPlacementState)
Value | Description |
|---|---|
| The ad unit is ready to show ads. |
| The ad unit is not available. |
| The ad unit was disabled. |
| The ad unit is waiting to be ready. |
| The ad unit has no ad to show. |
UnityAdsFinishState
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
The enumerated states of the user's interaction with the ad. The SDK passes this value to thetypedef NS_ENUM(NSInteger, UnityAdsFinishState)
unityAdsDidFinishValue | Description |
|---|---|
| Indicates that the ad failed to complete due to a Unity error. |
| Indicates that the user skipped the ad. |
| Indicates that the ad finished playing. |
UnityAdsInitializationError
The enumerated reasons for SDK initialization to fail.typedef NS_ENUM (NSInteger, UnityAdsInitializationError)
Value | Description |
|---|---|
| An error occurred due to the environment or internal services. |
| An error occurred due to invalid arguments in the Initialize method. |
| An error occurred due to a URL being blocked. |
UnityAdsLoadError
The enumerated reasons for an ad unit failing to load.typedef NS_ENUM (NSInteger, UnityAdsLoadError)
Value | Description |
|---|---|
| The ad failed to load due to the SDK not being initialized. |
| The ad failed to load due to an internal Unity Ads service error. |
| The ad failed to load due to invalid arguments in the |
| The ad failed to load because no content was available from the network. |
| The ad failed to load within the specified timeframe. |
UnityAdsShowCompletionState
The enumerated causes for the ad to have finished.typedef NS_ENUM (NSInteger, UnityAdsShowCompletionState)
Value | Description |
|---|---|
| Indicates that the user skipped the ad. |
| Indicates that the ad played in its entirety. This typically indicates that the user can be rewarded for watching the full ad. |
UnityAdsShowError
The enumerated reasons for an ad unit failing to show.typedef NS_ENUM (NSInteger, UnityAdsShowError)
Value | Description |
|---|---|
| The ad failed to show due to the SDK not being initialized. |
| The ad failed to show because the ad unit was not ready. |
| The ad failed to show because of a media player error. |
| The ad failed to show due to invalid arguments in the |
| The ad failed to show because of an internet connection error. |
| The ad failed to show because an ad was already showing. |
| The ad failed to show due to an internal Unity Ads service error. |
UnityAdsError
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
The enumerated causes of a Unity Ads error emitted through thetypedef NS_ENUM (NSInteger, UnityAdsError)
unityAdsDidErrorValue | Description |
|---|---|
| The Unity Ads service is currently uninitialized. |
| An error occurred in the initialization process. |
| Unity Ads initialization failed due to invalid parameters. |
| An error occurred due to the video player failing. |
| Initialization of the Unity Ads service failed due to an invalid environment. |
| An error occurred due to an ad blocker. |
| An error occurred due to inability to read or write a file. |
| An error occurred due to a bad device identifier. |
| An error occurred when attempting to show an ad. |
| An internal Unity Ads service error occurred. |
UnityAdsBannerPosition
The enumerated positions you can set as an anchor for banner ads.Value | Description |
|---|---|
| Anchor the banner to the top-left of the screen. |
| Anchor the banner to the top-center of the screen. |
| Anchor the banner to the top-right of the screen. |
| Anchor the banner to the bottom-left of the screen. |
| Anchor the banner to the bottom-center of the screen. |
| Anchor the banner to the bottom-right of the screen. |
| Anchor the banner to the center of the screen. |
| Do not anchor the banner. |
Delegates
UnityAdsInitializationDelegate
Implement this delegate to handle@protocol UnityAdsInitializationDelegate <NSObject>- (void)initializationComplete;- (void)initializationFailed: (UnityAdsInitializationError)error withMessage: (NSString *)message;@end
initializeinitializationComplete
This callback method handles logic for the SDK successfully initializing.initializationFailed
This callback method handles logic for the SDK failing to initialize.Parameter | Description |
|---|---|
| The |
| A message associated with the error. |
UnityAdsLoadDelegate
Implement this delegate to handle@protocol UnityAdsLoadDelegate <NSObject>- (void)unityAdsAdLoaded: (NSString *)placementId;- (void)unityAdsAdFailedToLoad: (NSString *)placementId withError: (UnityAdsLoadError)error withMessage: (NSString *)message;@end
loadunityAdsAdLoaded
This callback method handles logic for the ad unit successfully loading.Parameter | Description |
|---|---|
| The identifier for the ad unit that loaded content. |
unityAdsAdFailedToLoad
This callback method handles logic for the ad unit failing to load.Parameter | Description |
|---|---|
| The identifier for the ad unit that failed to load content. |
| The UnityAdsLoadError that caused the load to fail. |
| A message associated with the error. |
UnityAdsShowDelegate
Implement this delegate to handle@protocol UnityAdsShowDelegate <NSObject>- (void)unityAdsShowComplete: (NSString *)adUnitId withFinishState: (UnityAdsShowCompletionState)state;- (void)unityAdsShowFailed: (NSString *)adUnitId withError: (UnityAdsShowError)error withMessage: (NSString *)message;- (void)unityAdsShowStart: (NSString *)adUnitId;- (void)unityAdsShowClick: (NSString *)adUnitId;@end
showunityAdsShowComplete
This callback method handles logic for the ad finishing.Parameter | Description |
|---|---|
| The identifier for the ad unit showing the content. |
| Indicates whether the ad was skipped or completed. |
unityAdsShowStart
This callback method handles logic for the ad starting to play.Parameter | Description |
|---|---|
| The identifier for the ad unit showing content. |
unityAdsShowClick
This callback method handles logic for the user clicking on the ad.Parameter | Description |
|---|---|
| The identifier for the ad unit showing content. |
unityAdsShowFailed
This callback method handles logic for the ad unit failing to show content.Parameter | Description |
|---|---|
| The identifier for the ad unit that failed to show content. |
| The |
| message | A message associated with the error. |
UnityAdsDelegate
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
Implement this delegate to handle various states of an ad. Implement it in your script to define logic for rewarded ads.@protocol UnityAdsDelegate <NSObject>- (void)unityAdsReady: (NSString *)placementId;- (void)unityAdsDidError: (UnityAdsError)error withMessage: (NSString *)message;- (void)unityAdsDidStart: (NSString *)placementId;- (void)unityAdsDidFinish: (NSString *)placementId withFinishState: (UnityAdsFinishState)state;@end
unityAdsReady
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
Parameter | Description |
|---|---|
| The identifier for the ad unit that is ready. |
unityAdsDidError
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
Parameter | Description |
|---|---|
| The |
| A message associated with the error. |
unityAdsDidStart
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
Parameter | Description |
|---|---|
| The identifier for the ad unit that is showing the ad. |
unityAdsDidFinish
Important
Removed in SDK version 4.0. For more information, refer to the deprecated API classes.
Parameter | Description |
|---|---|
| The identifier for the ad unit that finished showing. |
| The resulting user event of the ad showing. |
UADSBannerDelegate
This delegate provides callbacks from Unity Ads banner events.@protocol UADSBannerViewDelegate <NSObject> @optional- (void)bannerViewDidLoad: (UADSBannerView *)bannerView;- (void)bannerViewDidClick: (UADSBannerView *)bannerView;- (void)bannerViewDidLeaveApplication: (UADSBannerView *)bannerView;- (void)bannerViewDidError: (UADSBannerView *)bannerView error: (UADSBannerError *)error;@end
bannerViewDidLoad
This callback fires when the banner successfully loaded ad content.bannerViewDidClick
This callback fires when the user clicked the banner ad.bannerViewDidLeaveApplication
This callback fires when the banner closed because the user quit the application.bannerViewDidError
This callback fires when UnityAdsBanner encounters an error.Parameter | Description |
|---|---|
| The |
UADSBannerAdRefreshViewDelegate
Note
This delegate is deprecated and will be removed in a future major version release of the Unity Ads SDK.
This delegate provides callbacks from Unity Ads refresh banner events.@protocol UADSBannerAdRefreshViewDelegate <NSObject> @optional- (void)unityAdsRefreshBannerDidLoad: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidNoFill: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidShow: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidHide: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidClick: (UADSBannerAdRefreshView *)bannerAdRefreshView;- (void)unityAdsRefreshBannerDidError: (UADSBannerAdRefreshView *)bannerAdRefreshView message: (NSString *)message;@end
unityAdsRefreshBannerDidLoad
Called when the banner is loaded and ready to be placed in the view hierarchy.unityAdsRefreshBannerDidNoFill
Called when no ad content is available for the banner.unityAdsRefreshBannerDidShow
Called when the banner is visible to the user.unityAdsRefreshBannerDidHide
Called when the banner is hidden to the user.unityAdsRefreshBannerDidClick
Called when the user clicked the banner ad.unityAdsRefreshBannerDidError
Called whenUnityAdsBannerParameter | Description |
|---|---|
| A message associated with the error. |