Unity Ads iOS SDK 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
    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

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

+ (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 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).

Note: If you call show 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.

addDelegate

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

+ (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

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

+ (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.

Note: Using UADSBannerView 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.

load

- (void)load;

The basic method for requesting an ad for the banner.

Enums

UnityAdsPlacementState

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

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

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

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

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

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.

message

A message associated with the error.

UnityAdsDelegate

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

@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

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

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

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

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

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

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

Removed in SDK version 4.0. For more information, refer to the deprecated API classes.

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

Note: This delegate is deprecated and will be removed in a future major version release of the Unity Ads SDK.

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

Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.