Knowledge base

iOS API reference


This article documents API for the following namespaces:


Use this namespace to implement basic ad content, such as rewarded or non-rewarded video, interstitial, or banner ads.

#import <UnityAds/UnityAds.h>


Initializes the Unity Ads service, with a specified Game ID and test mode status.

+ (void)initialize:(NSString *)gameId
    delegate:(nullable id<UnityAdsDelegate>)delegate
Parameter Data type Description
gameId NSString The Unity Game ID for your Project, located in the developer dashboard.
delegate UnityAdsDelegate The delegate for UnityAdsDelegate callbacks (documented below).
testMode BOOL Set to YES to enable test mode, and NO to disable it. When in test mode, your game will not receive live ads.


Returns whether an ad is ready to be shown for the specified Placement.

+ (BOOL)isReady:(NSString *)placementId;


Shows content in the specified Placement, if content is available.

+ (void)show:(UIViewController *)viewController placementId:(NSString *)placementId; 


The enumerated states of a Unity Ads Placement.

typedef NS_ENUM(NSInteger, UnityAdsPlacementState)
Value Description
kUnityAdsPlacementStateReady The Placement is ready to show ads.
kUnityAdsPlacementStateNotAvailable The Placement is not available.
kUnityAdsPlacementStateDisabled The Placement was disabled.
kUnityAdsPlacementStateWaiting The Placement is waiting to be ready.
kUnityAdsPlacementStateNoFill The Placement has no advertisements to show.

Retrieve the UnityAdsPlacementState value with the following function:

(UnityAdsPlacementState)getPlacementState:(NSString *)placementId;


An interface for handling various states of an ad. Implement this listener in your script to define logic for rewarded ads. The interface has the following methods:

@protocol UnityAdsDelegate <NSObject>
- (void)unityAdsReady:(NSString *)placementId;
- (void)unityAdsDidStart:(NSString *)placementId;
- (void)unityAdsDidFinish:(NSString *)placementId
- (void)unityAdsDidError:(UnityAdsError)error withMessage:(NSString *)message;


A UnityAdsDelegate method that handles logic for ad content being ready to display through a specified Placement. For example:

- (void)unityAdsReady:(NSString *)placementId;

A UnityAdsDelegate method that handles logic for the player triggering an ad to play. For example:

- (void)unityAdsDidStart:(NSString *)placementId;


A UnityAdsDelegate method that handles logic for an ad finishing. Define conditional behavior for different finish states by accessing the UnityAdsFinishState result (documented below) from the listener. For example:

- (void)unityAdsDidFinish:(NSString *)placementId
withFinishState:(UnityAdsFinishState)state {
    if (state == kUnityAdsFinishStateCompleted) {
        // Reward the user for watching the ad to completion:
    } else if (state == kUnityAdsFinishStateSkipped) {
        // Do not reward the user for skipping the ad.
    } else if (state == kUnityAdsFinishStateError) {
        Debug.LogWarning (“The ad did not finish due to an error.);


A UnityAdsDelegate method that handles logic for ad content failing to display because of an error. For example:

- (void)unityAdsDidError:(UnityAdsError)error withMessage:(NSString *)message;


The enumerated states of the end-user’s interaction with the ad. The SDK passes this value to the onUnityAdsDidFinish callback after the ad completes.

typedef NS_ENUM(NSInteger, UnityAdsFinishState)
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 user successfully finished watching the ad.


Allows you to register a delegate after the SDK is initialized.

+ (void)addDelegate:(id<UnityAdsDelegate>)delegate;


Allows you to remove an active delegate, after the SDK is initialized.

+ (void)removeDelegate:(id<UnityAdsDelegate>)delegate;

Service properties


Returns whether the current platform is supported by the SDK.

+ (BOOL)isSupported;


Debug mode controls the amount of logging output from the SDK. To toggle debug mode, use the following method:

+ (void)setDebugMode:(BOOL)enableDebugMode;


To retrieve the debug mode status, use the following method:

+ (BOOL)getDebugMode;


Returns the active Unity Ads SDK version.

+ (NSString *)getVersion;

Back to top


A static class for handling, showing and hiding ad banners.


Sets the position of the banner ad, using the UnityAdsBannerPosition enum.

+ (void)setBannerPosition:(UnityAdsBannerPosition)bannerPosition;


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

typedef NS_ENUM(NSInteger, UnityAdsBannerPosition) {


The basic method for loading banner ad content. You can adjust this function with several parameters, depending on your needs.

Method Description
+ (void)loadBanner Loads the banner ad with the default Placement ID.
+(void)loadBanner:(NSString *)placementId Loads the banner ad with a specific Placement ID (located on the developer dashboard).

For example:

-(void) loadBanner {
    if ([UnityAds isReady: self.bannerPlacementId]) {
        [UnityAdsBanner loadBanner: self.bannerPlacementId];


Destroys the banner ad, removing it from the view hierarchy and hiding it from the player.

+(void) destroy;


A delegate interface for handling various states of a banner ad. The interface has the following methods:

@protocol UnityAdsBannerDelegate <NSObject>
- (void)unityAdsBannerDidLoad:(NSString *)placementId view:(UIView *)view;
- (void)unityAdsBannerDidUnload:(NSString *)placementId;
- (void)unityAdsBannerDidShow:(NSString *)placementId;
- (void)unityAdsBannerDidHide:(NSString *)placementId;
- (void)unityAdsBannerDidClick:(NSString *)placementId;
- (void)unityAdsBannerDidError:(NSString *)message;

Note: Unity recommends implementing all of these methods in your code, even if you don’t use them all.


This callback fires when the banner ad is loaded and available to show, where view is the View to be placed in the view hierarchy. For example:

-(void) unityAdsBannerDidLoad: (NSString *) placementId view: (UIView *) view {
    // Store the bannerView for later:
    self.bannerView = view;
    // Add the banner into your view hierarchy:
    [self.view addSubview:self.bannerView];


This callback fires on [UnityBanners destroy], notifying that the banner was completely destroyed and references can be removed (for example, removing the view provided in unityAdsBannerDidLoad).

-(void) unityAdsBannerDidUnload: (NSString *) placementId {
    self.bannerView = nil;


This callback fires when the banner ad entered the view hierarchy and is visible to the player.

-(void) unityAdsBannerDidShow: (NSString *) placementId;


This callback fires when the banner ad is hidden from the player, due to removal from the view hierarchy or the window changing.

-(void) unityAdsBannerDidHide: (NSString *) placementId;


This callback fires when the player clicks the banner ad.

-(void) unityAdsBannerDidClick: (NSString *) placementId;


This callback fires when the UnityAdsBanner encounters an error. All errors are logged, but this method provides an additional debugging aid. This callback can also be used to collect statistics from different error scenarios.

-(void) unityAdsBannerDidError: (NSString *) message;

setDelegate and getDelegate

Sets or retrieves the assigned UnityAdsBannerDelegate for Unity Ads to send banner callbacks to.

+(nullable id <UnityAdsBannerDelegate>) getDelegate;
+(void)setDelegate: (id <UnityAdsBannerDelegate>) delegate;

Back to top


Use the UnityMonetization namespace to implement Personalized Placements.

#import <UnityAds/UnityMonetization.h>


An interface for handling various states of UMONPlacementContent objects (documented below). The interface has the following methods:


This function notifies you that a UMONPlacementContent object is available for a given Placement and is ready to show.

- (void) placementContentReady: (NSString *) placementId placementContent: (UMONPlacementContent *) decision;


This function notifies you when the readied UMONPlacementContent object’s status has changed due to a refresh.

-(void) placementContentStateDidChange: (NSString *) placementId placementContent: (UMONPlacementContent *) placementContent previousState: (UnityMonetizationPlacementContentState) previousState newState: (UnityMonetizationPlacementContentState) newState;

Example UnityMonetizationDelegate implementation:

@interface MyMonetizationDelegate <UnityMonetizationDelegate>

@implementation MyMonetizationDelegate
-(void) placementContentReady:(NSString *)placementId placementContent:(UMONPlacementContent *)placementContent {
    if ([placementId isEqualToString:@"video"]) {
        self.interstitial = placementContent;
    } else if ([placementId isEqualToString:@"rewardedVideo"]) {
        self.rewardedVideo = placementContent;

-(void) placementContentStateDidChange:(NSString *) placementId placementContent: (UMONPlacementContent *) decision previousState: (UnityMonetizationPlacementContentState) previousState newState: (UnityMonetizationPlacementContentState) newState {
    if (newState != kPlacementContentStateReady) {
        // Disable showing ads because content isn’t ready anymore


An object representing monetization content that your Placement can display.


This function returns YES if the content is ready to display, and NO if it isn’t.

@property (nonatomic, readonly, getter = isReady) BOOL ready;


This function returns the type of UMONPlacementContent available to display.

@property (nonatomic, readonly) NSString *type;

The following string values are valid:

String value Description
SHOW_AD Refers to video ad content using the UMONShowAdPlacementContent class extension.
PROMO_AD Refers to IAP Promo content using the UMONPromoAdPlacementContent class extension.
NO_FILL Refers to a lack of UMONPlacementContent available for the specified Placement.


Extends the UMONPlacementContent class with functionality to support rewarded content.


This function returns YES if the UMONPlacementContent is rewarded, and NO if it isn’t.

@property (nonatomic) BOOL rewarded;


Extends the UMONRewardablePlacementContent class with functionality to support video ad content.


This function displays the available UMONShowAdPlacementContent. Implement a UMONShowAdDelegate delegate to define how this function responds to each ad UnityAdsFinishState.

-(void) show: (UIViewController *) viewController withDelegate: (id <UMONShowAdDelegate>) delegate;


Implement this delegate to provide the unityAdsDidFinish callback method for a video ad’s UnityAdsFinishState.


Implement this method to provide logic for handling whether the ad was completed, skipped, or errored out.

-(void) unityAdsDidFinish: (NSString*) placementId withFinishState: (UnityAdsFinishState) finishState;


An enum representing the final state of an ad when finished. Use it to handle reward cases.

Value Description
kUnityAdsFinishStateCompleted The player viewed the ad in its entirety.
kUnityAdsFinishStateSkipped The player skipped the ad before it played in its entirety.
kUnityAdsFinishStateError The ad failed to load.

Example unityAdsDidFinish implementation:

- (void) unityAdsDidFinish: (NSString *) placementId withFinishState: (UnityAdsFinishState) finishState {

    NSLog (@"UnityAds FINISH: %@", placementId);

    if (finishState == kUnityAdsFinishStateCompleted && [placementId isEqualToString: @"rewardedVideo"]) {
        // Reward the player
        ((UMONShowAdPlacementContent *) self.rewardedContent).rewarded = YES;
        NSLog (@"Reward the player");


Extends the UMONShowAdPlacementContent class, providing functionality for IAP Promo content. For more information, see documentation on Native Promo.

Back to top

Still need help? Get in touch!
Last updated on 17th Jul 2019