Documentation

Support

Unity Ads Monetization

Android developer monetization guide

iOS developer monetization guide

Privacy consent setup

Unity Ads Monetization

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 2 months ago
Use the 
UnityAds.h
library to implement basic ad content, such as rewarded or non-rewarded video, interstitial, or banner ads. 
#import "UnityAds.h"
This article contains the following API documentation: Classes Enums Delegates

Classes

UnityAds

#import <UnityAds/UnityAds.h>
Use this namespace to implement basic ad content, such as rewarded or non-rewarded video, interstitial, or banner ads.

initialize

+ (void) initialize: (NSString *)gameId
    testMode: (BOOL)testMode
    initializationDelegate: (nullable id<UnityAdsInitializationDelegate>)initializationDelegate;
}
Initializes the ads service, with a specified Game ID, test mode status, and initialization delegate.

Parameter

Description

gameId
The platform-specific Unity game identifier for your project, found on the Unity Ads Monetization dashboard.
testMode
Use Test mode to test your integration without serving live ads. Use 
true
to initialize in test mode.
initializationDelegate
Optionally enables the SDK with 
UnityAdsInitializationDelegate
 callbacks (versions 3.7.0 and later).

load

+ (void)load: (NSString *)placementId options: (UADSLoadOptions *)options loadDelegate: (nullable id<UnityAdsLoadDelegate>)loadDelegate {
  [UADSLoadModule.sharedInstance loadForPlacementID: placementId
	      						    options: options
    						         loadDelegate: loadDelegate];
}
Loads ad content for a specified ad unit. You must call 
load
before calling 
show
.

Parameter

Description

placementId
The identifier for the ad unit you want to load with ad content.
options
A collection of options for modifying ad load behavior.
loadDelegate
Optionally loads ad content with 
UnityAdsLoadDelegate
 callbacks (versions 3.7.0 and later).

isReady

+ (BOOL)isReady: (NSString *)adUnitId {
  return [UnityServices isSupported] && [UnityServices isInitialized] && [UADSPlacement isReady: adUnitId];
}
Returns 
YES
if an ad is ready to show in the specified ad unit. If you initialized the SDK with 
enablePerPlacementLoad
enabled, you must call 
load
before calling 
show
.

Parameter

Description

adUnitId
The identifier for the ad dnit you want to query.

show

+ (void)show: (UIViewController *)viewController placementId: (NSString *)placementId showDelegate: (nullable id<UnityAdsShowDelegate>)showDelegate {
 	[self show: viewController
       adUnitId: placementId
        options: [UADSShowOptions new]
   showDelegate: showDelegate];
}
Displays loaded ad content in a specified ad unit.

Parameter

Description

placementId
The identifier for the ad unit you want to show.
options
A collection of options for modifying ad show behavior.
showDelegate
Optionally shows content with 
UnityAdsShowDelegate
 callbacks (versions 3.7.0 and later).

addDelegate

+ (void)addDelegate: (__nullable id<UnityAdsDelegate>)delegate {
  [UADSProperties addDelegate: delegate];
}
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.

Parameter

Description

delegate
A listener for Unity Ads callbacks.

removeDelegate

+ (void)removeDelegate: (id<UnityAdsDelegate>)delegate {
    [UADSProperties removeDelegate: delegate];
}
Removes an active 
UnityAdsDelegate
 listener.

Parameter

Description

delegate
A listener for Unity Ads callbacks.

setDebugMode

+ (BOOL)getDebugMode {
  return [UnityServices getDebugMode];
}
Controls the amount of logging output from the SDK. Set to 
YES
for more robust logging.

getDebugMode

+ (void)getDebugMode: (BOOL)enableDebugMode {
  [UnityServices setDebugMode: enableDebugMode];
}
Returns 
YES
if the SDK is is in debug mode, and 
NO
if it isn't.

getVersion

+ (NSString *)getVersion {
  return [UnityServices getVersion];
}
Returns the current version of the Unity Ads SDK.

isInitialized

+ (BOOL)isInitialized {
  return [USRVSdkProperties isInitialized];
}
Returns 
YES
if the SDK is initialized successfully, and 
NO
if it isn't.

UADSLoadOptions

#import <UnityAds/UADSBaseOptions.h>

@interface UADSLoadOptions : UADSBaseOptions

@property (nonatomic, readwrite) NSString *adMarkup;

@end
This class contains optional metadata to include with the 
load
 method. Customers using header bidding in third-party mediation should use this in cases where a bidder from the Unity network wins the ad auction.

setAdMarkup

- (void)setAdMarkup: (NSString *)adMarkup
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.

UADSBannerView

@interface UADSBannerView : UIView
Use this class to implement banner ads. Unity Ads versions 3.3 and later support multiple banner instances through a single ad unit.

initWithPlacementId

-(instancetype)initWithPlacementId:(NSString *)placementId size:(CGSize)size;
Implements a banner view using an ad unit ID and banner size. Call 
initWithPlacementId
to initialize the object, then 
load
 to load ad content. Note that the banner object accesses lifecycle events through its 
UADSBannerViewDelegate
 listener.

Parameter

Description

placementId
The banner's ad unit ID.
size
The 
size
 of the banner object. The minimum supported size is 320 pixels by 50 pixels.

load

- (void)load;
The basic method for requesting an ad for the banner.

Enums

UnityAdsPlacementState

typedef NS_ENUM(NSInteger, UnityAdsPlacementState)
The enumerated states of an ad unit.

Value

Description

kUnityAdsPlacementStateReady
The ad unit is ready to show ads.
kUnityAdsPlacementStateNotAvailable
The ad unit is not available.
kUnityAdsPlacementStateDisabled
The ad unit was disabled.
kUnityAdsPlacementStateWaiting
The ad unit is waiting to be ready.
kUnityAdsPlacementStateNoFill
The ad unit has no ad to show.

UnityAdsFinishState

typedef NS_ENUM(NSInteger, UnityAdsFinishState)
The enumerated states of the user's interaction with the ad. The SDK passes this value to the 
unityAdsDidFinish
 callback method when the ad completes.

Value

Description

kUnityAdsFinishStateError
Indicates that the ad failed to complete due to a Unity error.
kUnityAdsFinishStateSkipped
Indicates that the user skipped the ad.
kUnityAdsFinishStateCompleted
Indicates that the ad finished playing.

UnityAdsInitializationError

typedef NS_ENUM (NSInteger, UnityAdsInitializationError)
The enumerated reasons for SDK initialization to fail.

Value

Description

kUnityInitializationErrorInternalError
An error occurred due to the environment or internal services.
kUnityInitializationErrorInvalidArgument
An error occurred due to invalid arguments in the Initialize method.
kUnityInitializationErrorAdBlockerDetected
An error occurred due to a URL being blocked.

UnityAdsLoadError

typedef NS_ENUM (NSInteger, UnityAdsLoadError)
The enumerated reasons for an ad unit failing to load.

Value

Description

kUnityAdsLoadErrorInitializeFailed
The ad failed to load due to the SDK not being initialized.
kUnityAdsLoadErrorInternal
The ad failed to load due to an internal Unity Ads service error.
kUnityAdsLoadErrorInvalidArgument
The ad failed to load due to invalid arguments in the 
load
 method.
kUnityAdsLoadErrorNoFill
The ad failed to load because no content was available from the network.
kUnityAdsLoadErrorTimeout
The ad failed to load within the specified timeframe.

UnityAdsShowCompletionState

typedef NS_ENUM (NSInteger, UnityAdsShowCompletionState)
The enumerated causes for the ad to have finished.

Value

Description

kUnityShowCompletionStateSkipped
Indicates that the user skipped the ad.
kUnityShowCompletionStateCompleted
Indicates that the ad played in its entirety. This typically indicates that the user can be rewarded for watching the full ad.

UnityAdsShowError

typedef NS_ENUM (NSInteger, UnityAdsShowError)
The enumerated reasons for an ad unit failing to show.

Value

Description

kUnityShowErrorNotInitialized
The ad failed to show due to the SDK not being initialized.
kUnityShowErrorNotReady
The ad failed to show because the ad unit was not ready.
kUnityShowErrorVideoPlayerError
The ad failed to show because of a media player error.
kUnityShowErrorInvalidArgument
The ad failed to show due to invalid arguments in the 
show
 method.
kUnityShowErrorNoConnection
The ad failed to show because of an internet connection error.
kUnityShowErrorAlreadyShowing
The ad failed to show because an ad was already showing.
kUnityShowErrorInternalError
The ad failed to show due to an internal Unity Ads service error.

UnityAdsError

typedef NS_ENUM (NSInteger, UnityAdsError)
The enumerated causes of a Unity Ads error emitted through the 
unityAdsDidError
 callback.

Value

Description

kUnityAdsErrorNotInitialized = 0
The Unity Ads service is currently uninitialized.
kUnityAdsErrorInitializedFailed
An error occurred in the initialization process.
kUnityAdsErrorInvalidArgument
Unity Ads initialization failed due to invalid parameters.
kUnityAdsErrorVideoPlayerError
An error occurred due to the video player failing.
kUnityAdsErrorInitSanityCheckFail
Initialization of the Unity Ads service failed due to an invalid environment.
kUnityAdsErrorAdBlockerDetected
An error occurred due to an ad blocker.
kUnityAdsErrorFileIoError
An error occurred due to inability to read or write a file.
kUnityAdsErrorDeviceIdError
An error occurred due to a bad device identifier.
kUnityAdsErrorShowError
An error occurred when attempting to show an ad.
kUnityAdsErrorInternalError
An internal Unity Ads service error occurred.

UnityAdsBannerPosition

The enumerated positions you can set as an anchor for banner ads.

Value

Description

kUnityAdsBannerPositionTopLeft
Anchor the banner to the top-left of the screen.
kUnityAdsBannerPositionTopCenter
Anchor the banner to the top-center of the screen.
kUnityAdsBannerPositionTopRight
Anchor the banner to the top-right of the screen.
kUnityAdsBannerPositionBottomLeft
Anchor the banner to the bottom-left of the screen.
kUnityAdsBannerPositionBottomCenter
Anchor the banner to the bottom-center of the screen.
kUnityAdsBannerPositionBottomRight
Anchor the banner to the bottom-right of the screen.
kUnityAdsBannerPositionCenter
Anchor the banner to the center of the screen.
kUnityAdsBannerPositionNone
Do not anchor the banner.

Delegates

UnityAdsInitializationDelegate

@protocol UnityAdsInitializationDelegate <NSObject>
- (void)initializationComplete;
- (void)initializationFailed: (UnityAdsInitializationError)error withMessage: (NSString *)message;
@end
Implement this delegate to handle 
initialize
 results.

initializationComplete

This callback method handles logic for the SDK successfully initializing.

initializationFailed

This callback method handles logic for the SDK failing to initialize.

Parameter

Description

error
The 
UnityAdsInitializationError
 that caused initialization to fail.
message
A message associated with the error.

UnityAdsLoadDelegate

@protocol UnityAdsLoadDelegate <NSObject>
- (void)unityAdsAdLoaded: (NSString *)placementId;
- (void)unityAdsAdFailedToLoad: (NSString *)placementId
       withError: (UnityAdsLoadError)error
     withMessage: (NSString *)message;
@end
Implement this delegate to handle 
load
 results.

unityAdsAdLoaded

This callback method handles logic for the ad unit successfully loading.

Parameter

Description

placementId
The identifier for the ad unit that loaded content.

unityAdsAdFailedToLoad

This callback method handles logic for the ad unit failing to load.

Parameter

Description

placementId
The identifier for the ad unit that failed to load content.
error
The UnityAdsLoadError that caused the load to fail.
message
A message associated with the error.

UnityAdsShowDelegate

@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
Implement this delegate to handle 
show
 results.

unityAdsShowComplete

This callback method handles logic for the ad finishing.

Parameter

Description

adUnitId
The identifier for the ad unit showing the content.
state
Indicates whether the ad was skipped or completed.

unityAdsShowStart

This callback method handles logic for the ad starting to play.

Parameter

Description

adUnitId
The identifier for the ad unit showing content.

unityAdsShowClick

This callback method handles logic for the user clicking on the ad.

Parameter

Description

adUnitId
The identifier for the ad unit showing content.

unityAdsShowFailed

This callback method handles logic for the ad unit failing to show content.

Parameter

Description

adUnitId
The identifier for the ad unit that failed to show content.
error
The 
UnityAdsShowError
 that caused the show to fail.
messageA message associated with the error.

UnityAdsDelegate

@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
Implement this delegate to handle various states of an ad. Implement it in your script to define logic for rewarded ads.

unityAdsReady

Specify logic for ad content being ready to display through a specified ad unit.

Parameter

Description

placementId
The identifier for the ad unit that is ready.

unityAdsDidError

Specify logic for ad content failing to display due to an error.

Parameter

Description

error
The 
UnityAdsError
 that caused the error.
message
A message associated with the error.

unityAdsDidStart

Specify logic for the player triggering an ad to show.

Parameter

Description

placementId
The identifier for the ad unit that is showing the ad.

unityAdsDidFinish

Specify logic for the player watching the ad in its entirety.

Parameter

Description

placementId
The identifier for the ad unit that finished showing.
state
The resulting user event of the ad showing.

UADSBannerDelegate

@protocol UADSBannerViewDelegate <NSObject>
 
@optional
- (void)bannerViewDidLoad: (UADSBannerView *)bannerView;
- (void)bannerViewDidClick: (UADSBannerView *)bannerView;
- (void)bannerViewDidLeaveApplication: (UADSBannerView *)bannerView;
- (void)bannerViewDidError: (UADSBannerView *)bannerView error: (UADSBannerError *)error;
@end
This delegate provides callbacks from Unity Ads banner events.

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

error
The 
UADSBannerError
that caused the error.

UADSBannerAdRefreshViewDelegate

@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
This delegate provides callbacks from Unity Ads refresh banner events.

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 when 
UnityAdsBanner
encounters an error.

Parameter

Description

message
A message associated with the error.