Knowledge base

iOS API reference

Overview

This article documents API for the following namespaces:

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 Unity Ads service, with a specified Game ID and test mode status.

+ (void)initialize:(NSString *)gameId
    delegate:(nullable id<UnityAdsDelegate>)delegate
    testMode:(BOOL)testMode;
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.

isReady

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

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

show

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

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

UnityAdsPlacementState

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;

UnityAdsDelegate

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
    withFinishState:(UnityAdsFinishState)state;
- (void)unityAdsDidError:(UnityAdsError)error withMessage:(NSString *)message;
@end

onUnityAdsReady

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

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

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

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

onUnityAdsDidFinish

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.);
    }    
}

onUnityAdsDidError

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;

UnityAdsFinishState

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.

addDelegate

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

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

removeDelegate

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

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

Service properties

isSupported

Returns whether the current platform is supported by the SDK.

+ (BOOL)isSupported;

setDebugMode

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

+ (void)setDebugMode:(BOOL)enableDebugMode;

getDebugMode

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

+ (BOOL)getDebugMode;

getVersion

Returns the active Unity Ads SDK version.

+ (NSString *)getVersion;

Back to top

UnityAdsBanner

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

setBannerPosition

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

+ (void)setBannerPosition:(UnityAdsBannerPosition)bannerPosition;

UnityAdsBannerPosition

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

typedef NS_ENUM(NSInteger, UnityAdsBannerPosition) {
    kUnityAdsBannerPositionTopLeft,
    kUnityAdsBannerPositionTopCenter,
    kUnityAdsBannerPositionTopRight,
    kUnityAdsBannerPositionBottomLeft,
    kUnityAdsBannerPositionBottomCenter,
    kUnityAdsBannerPositionBottomRight,
    kUnityAdsBannerPositionCenter,
    kUnityAdsBannerPositionNone
};

loadBanner

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];
    }
}

destroy

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

+(void) destroy;

UnityAdsBannerDelegate

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;
@end

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

unityAdsBannerDidLoad

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];
}

unityAdsBannerDidUnload

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;
}

unityAdsBannerDidShow

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

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

unityAdsBannerDidHide

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;

unityAdsBannerDidClick

This callback fires when the player clicks the banner ad.

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

unityAdsBannerDidError

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

UnityMonetization

Use the UnityMonetization namespace to implement Personalized Placements.

#import <UnityAds/UnityMonetization.h>

UnityMonetizationDelegate

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

placementContentReady

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;

placementContentStateDidChange

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>
@end

@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
    }
}
@end

UMONPlacementContent

An object representing monetization content that your Placement can display.

ready

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

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

getType

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.

UMONRewardablePlacementContent

Extends the UMONPlacementContent class with functionality to support rewarded content.

isRewarded

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

@property (nonatomic) BOOL rewarded;

UMONShowAdPlacementContent

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

show

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;

UMONShowAdDelegate

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

unityAdsDidFinish

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

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

UnityAdsFinishState

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");
    }
}

UMONPromoAdPlacementContent

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