Knowledge base

iOS API reference

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 initializationDelegate: (id<UnityAdsInitializationDelegate>)initializationDelegate 
{
    [self initialize: gameId
                      testMode: false
        enablePerPlacementLoad: false
        initializationDelegate: initializationDelegate];
} 

Initializes the ads service, with a specified Game ID, test mode status, and Ad Unit load setting.

Parameter Description
gameId The platform-specific Unity game identifier for your project, found on the developer dashboard.
testMode Test mode allows you to test your integration without serving live ads. Use true to initialize in test mode.
enablePerPlacementLoad Optionally enables the SDK with the Load API lifecycle (versions 3.5.0 and higher).
initializationDelegate Optionally enables the SDK with UnityAdsInitializationDelegate callbacks (versions 3.7.0 and higher).

load

+ (void)load: (NSString *)placementId options: (UADSLoadOptions *)options loadDelegate: (nullable id<UnityAdsLoadDelegate>)loadDelegate {
    [UADSLoadModule.sharedInstance loadForPlacementID: adUnitId
                                              options: options
                                         loadDelegate: loadDelegate];
}

Loads ad content for a 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 Unit you want to load with ad content.
options A collection of options for modifying ad load behavior.
loadDelegate Optionally loads ad content with IUnityAdsLoadDelegate callbacks (versions 3.7.0 and higher).

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 Unit you want to query.

Note: If you call isReady() without specifying an Ad Unit ID, the method returns results for the Unity Standard Placement.

show

+ (void)show: (UIViewController *)viewController adUnitId: (NSString *)adUnitId showDelegate: (nullable id<UnityAdsShowDelegate>)showDelegate {
    [self show: viewController
         adUnitId: adUnitId
             options: [UADSShowOptions new]
        showDelegate: showDelegate];
}

Displays loaded ad content in a specified Ad Unit.

Parameter Description
adUnitId 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 higher).

Note: If you call show() without specifying an Ad Unit ID, the method shows loaded content in the Unity Standard Placement.

addDelegate

+ (void)addDelegate: (__nullable id<UnityAdsDelegate>)delegate {
    [UADSProperties addDelegate: delegate];
}

Adds a listener delegate that will recieve Unity Ads callbacks. Versions 3.1.0 and higher allow you to 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.

UADSBannerView

Use this class to implement banner ads. Unity Ads versions 3.3 and higher support multiple banner instances through a single Ad Unit.

@interface UADSBannerView : UIView

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.

Note: Using UADSBannerView to call a banner ad attempts to load content once, with no refreshing. If the banner returns no fill, you may destroy it and create a new one to try again. Unity recommends this method for mediated customers.

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 *)adUnitId;
- (void)unityAdsAdFailedToLoad: (NSString *)adUnitId
                     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
adUnitId The identifier for the Ad Unit that loaded content.

unityAdsAdFailedToLoad

This callback method handles logic for the Ad Unit failing to load.

Parameter Description
adUnitId 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 the content.

unityAdsShowClick

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

Parameter Description
adUnitId The identifier for the Ad Unit showing the content.

unityAdsShowFailed

This callback method handles logic for the Ad Unit failing to show.

Parameter Description
adUnitId The identifier for the Ad Unit that failed to show content.
error The UnityAdsShowError that caused the show to fail.
message A message associated with the error.

UnityAdsDelegate

@protocol UnityAdsDelegate <NSObject>
- (void)unityAdsReady: (NSString *)adUnitId;
- (void)unityAdsDidError: (UnityAdsError)error withMessage: (NSString *)message;
- (void)unityAdsDidStart: (NSString *)adUnitId;
- (void)unityAdsDidFinish: (NSString *)adUnitId
          withFinishState: (UnityAdsFinishState)state;
@end

Implement this delegate to handle various states of an ad. Implement this listener 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
adUnitId 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
adUnitId 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
adUnitId 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.
Still need help? Get in touch!
Last updated on 22nd Oct 2021