Unity Ads SDK iOS developer monetization Unity Ads SDK integration guide for iOS developers iOS developer API references Unity Ads iOS SDK API reference - Objective-C Access the Unity Ads SDK public API reference to view available classes, methods, and properties you can use in Objective-C to integrate and control ad behavior in your iOS app.
Read time 13 minutes
Last updated a day ago Use this reference for the Unity Ads iOS SDK API in Objective-C as you integrate Unity Ads into your iOS applications.
Before using this API, ensure that you've imported the library to enable monetization in your app. Refer to Import the UnityAds library for more information.
Classes
UADSBannerAd
The class manages the loading and showing of banner ads.
load:completion:_
@interface UADSBannerAd : NSObject + (void)load:(UADSBannerLoadConfiguration * _Nonnull)config completion:(void (^ _Nonnull)(UADSBannerAd * _Nullable, id<UnityAdsError> _Nullable))completion; @end
Loads a banner ad with the specified configuration.
Parameters Description configuration The options for loading the banner ad. completion A callback that gets called when the banner is loaded. Returns the loaded BannerAd instance if successful, or an UnityAdsError if loading fails.
view
@interface UADSBannerAd : NSObject @property (nonatomic, readonly, strong) UIView * _Nonnull view; @end
A view property that provides access to the banner ad instance. Use this property to insert the banner ad within your app's existing view hierarchy at the desired location.
UADSBannerView
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0. Use iOS deprecated APIs for migration details. was the previous class for loading and displaying banner ads.
UADSBannerViewDelegate
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0. Use iOS deprecated APIs for migration details. was the previous delegate protocol for handling banner ad events.
UADSBannerLoadConfiguration
The UADSBannerLoadConfiguration
@interface BannerLoadConfiguration : NSObject @property (nonatomic, strong) NSString *placementId; @property (nonatomic, strong, nullable) NSString *adMarkup; @property (nonatomic, assign) CGSize bannerSize; @property (nonatomic, weak, nullable) id<UADSBannerAdDelegate> delegate; @property (nonatomic, strong, nullable) NSString *mediationAdUnitId; @property (nonatomic, strong, nullable) MediationInfo *mediationInfo; @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extras; @end
Property Description Required The placement ID defined in the Unity Monetization Dashboard. Yes Ad markup data that's used when loading an ad through bidding. No The size of the banner ad. Yes Delegate to handle banner ad events. Yes The ad unit or placement ID defined in your mediation partner's dashboard. No Specifies details about your mediation integration. No Additional custom key–value pairs. No
UADSBannerLoadConfigurationBuilder
Use UADSBannerLoadConfigurationBuilderUADSBannerLoadConfiguration
initWithPlacementId:adMarkup:bannerSize:delegate
- (nonnull instancetype)initWithPlacementId:(NSString * _Nonnull)placementId bannerSize:(CGSize)bannerSize delegate:(id <UADSBannerAdDelegate> _Nonnull)delegate;
Creates a new instance of BannerLoadConfigurationBuilder
Property Description Required The placement ID defined in the Unity Monetization Dashboard. Yes The size of the banner ad. Yes Delegate to handle banner ad events. Yes
Returns : An instance of UADSBannerLoadConfigurationBuilderwithAdMarkup:_
- (nonnull instancetype)withAdMarkup:(NSString * _Nonnull)adMarkup
Adds an adMarkup to the UADSBannerLoadConfigurationBuilder
Parameter Description adMarkup Ad markup data that's used when loading an ad through bidding.
- (nonnull instancetype)withMediationAdUnitId:(NSString * _Nonnull)mediationAdUnitId
Adds a mediation ad unit ID to the UADSBannerLoadConfigurationBuilder
Parameter Description mediationAdUnitId The ad unit or placement ID defined in your mediation partner's dashboard.
Returns : The updated UADSBannerLoadConfigurationBuilder- (nonnull instancetype)withMediationInfo:(UADSMediationInfo * _Nonnull)info
Adds mediation information to the UADSBannerLoadConfigurationBuilder
Parameter Description mediationInfo Details about the mediation integration (name, version, adapter version).
Returns : The updated UADSBannerLoadConfigurationBuilder instance.- (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
Adds extra key–value parameters to the UADSBannerLoadConfigurationBuilder
Parameter Description extras Custom parameters for banner loading.
Returns : The updated UADSBannerLoadConfigurationBuilderbuild
- (UADSBannerLoadConfiguration * _Nonnull)build
Builds and returns a UADSBannerLoadConfiguration
Returns : An instance of UADSBannerLoadConfigurationUADSBannerLoadOptions
was the previous class for specifying banner load options.
UADSInitializationConfiguration
@interface UADSInitializationConfiguration: NSObject @property (nonatomic, strong) NSString *gameId; @property (nonatomic, assign) BOOL isTestModeEnabled; @property (nonatomic, assign) UADSLogLevel logLevel; @property (nonatomic, strong, nullable) UADSMediationInfo *mediationInfo; @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extras; @end
The UADSInitializationConfiguration
Property Type Description Required Unique identifier for your Unity project. Yes Enables or disables test mode. No Specifies the detail level of log output. No UADSMediationInfo * _NullableSpecifies details about your mediation integration. No NSDictionary<NSString *, NSString *> *Additional key–value pairs for custom configuration. No
UADSInitializationConfigurationBuilder
Use UADSInitConfigurationBuilderUADSInitializationConfiguration
initWithgameID:_
- (nonnull instancetype)initWithGameId:(NSString * _Nonnull)gameId
Creates a new instance of UADSInitConfigurationBuilder
Parameter Description gameId Unique identifier for a game, given by Unity Ads admin tools or Unity editor.
Returns : An instance of UADSInitConfigurationBuilderwithTestMode:_
- (nonnull instancetype)withTestMode:(BOOL)testMode
Sets the test mode.
Parameter Description testMode Set this flag to to indicate test mode and show only test ads.
Returns : The updated UADSInitConfigurationBuilderwithLogLevel:_
- (nonnull instancetype)withLogLevel:(enum UADSLogLevel)logLevel
Sets the log level , which defines the amount of detail included in logs, from none to full debug information.
Parameter Description level Specifies the detail level of log output.
Returns : The updated UADSInitConfigurationBuilder- (nonnull instancetype)withMediationInfo:(UADSMediationInfo * _Nonnull)info
Sets the mediation information, which provides details about your app's mediation integration, including mediation name, version, and adapter version.
Parameter Description info Specifies details about your mediation integration.
Returns : The updated UADSInitConfigurationBuilder- (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
Sets additional parameters.
Parameter Description extras Additional key–value pairs for custom configuration.
Returns : The updated UADSInitConfigurationBuilderbuild
- (UADSInitializationConfiguration * _Nonnull)build
Builds and returns a UADSInitializationConfiguration instance.
Returns : An instance of UADSInitializationConfigurationUADSInterstitialAd
The class manages the loading and showing of interstitial ads.
load:completion:_
@interface UADSInterstitialAd : NSObject + (void)load:(UADSLoadConfiguration * _Nonnull)configuration completion:(void (^ _Nonnull)(UADSInterstitialAd * _Nullable, id<UnityAdsError> _Nullable))completion; @end
Loads an interstitial ad with the specified configuration.
Parameters Description configuration An instance of UADSLoadConfiguration containing the ad loading options. completion A callback that gets called when the loading process is finished. Returns either a UADSInterstitialAd instance or an error.
show:delegate:_
@interface UADSInterstitialAd : NSObject - (void)show:(UADSShowConfiguration * _Nullable)configuration delegate:(id <UADSInterstitialShowDelegate> _Nonnull)delegate; @end
Displays the loaded interstitial ad.
Parameter Description configuration Optional configuration for showing the ad. delegate A delegate conforming to UADSInterstitialShowDelegate
onAdExpired
Register a callback that gets triggered when the ad expires.
@interface UnityAd : NSObject @property (nonatomic, copy) void (^ _Nullable onAdExpired)(UnityAd * _Nonnull); @end
UADSLoadConfiguration
The class encapsulates the options needed to load Unity ads. This includes specifying the placement ID, optional ad markup, and any additional parameters.
@interface UADSLoadConfiguration: NSObject @property (nonatomic, strong) NSString *placementId; @property (nonatomic, strong, nullable) NSString *adMarkup; @property (nonatomic, strong, nullable) NSString *mediationAdUnitId; @property (nonatomic, strong, nullable) UADSMediationInfo *mediationInfo; @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extras; @end
Creates a new instance of .
Property Description Required The placement ID defined in the Unity Monetization Dashboard. Yes Ad markup data that's used when loading an ad through bidding. No The placement ID used in your mediation partner's dashboard. No Specifies details about your mediation integration. No Additional custom key–value pairs for configuration. No
Note: The adMarkup property is required for all bidding implementations. For waterfall implementations, you can set adMarkup to nil.
UADSLoadConfigurationBuilder
Use UADSLoadConfigurationBuilder
initWithPlacementId:_
- - (nonnull instancetype)initWithPlacementId:(NSString * _Nonnull)placementId;
Creates a new instance of UADSLoadConfigurationBuilder
Parameter Description The placement ID defined in the Unity Monetization Dashboard.
Returns : An instance of UADSLoadConfigurationBuilderwithAdMarkup:_
- (nonnull instancetype)withAdMarkup:(NSString * _Nonnull)adMarkup
Adds an adMarkup to the UADSLoadConfigurationBuilder
Property Description Ad markup data that's used when loading an ad through bidding.
Returns : The updated UADSLoadConfigurationBuilder- (nonnull instancetype)withMediationAdUnitId:(NSString * _Nonnull)mediationAdUnitId
Adds the mediation ad unit ID to the UADSLoadConfigurationBuilder
Property Description The placement ID used in your mediation partner's dashboard.
Returns : The updated UADSLoadConfigurationBuilder- (nonnull instancetype)withMediationInfo:(UADSMediationInfo * _Nonnull)info
Adds mediation information to the UADSLoadConfigurationBuilder
Parameter Description mediationInfo Specifies details about your mediation integration (name, version, adapter version).
Returns : The updated UADSLoadConfigurationBuilder- (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
Adds extra configuration key–value pairs to the UADSLoadConfigurationBuilder
Parameter Description extras A dictionary of custom parameters for ad loading.
Returns : The updated UADSLoadConfigurationBuilderbuild
- (UADSLoadConfiguration * _Nonnull)build
Builds and returns a instance.
Returns : An instance of .UADSLoadOptions
was the previous class for specifying ad load options.
Specifies details about your mediation integration.
@interface UADSMediationInfo : NSObject - (nonnull instancetype)initWithName:(NSString * _Nonnull)name version:(NSString * _Nonnull)version adapterVersion:(NSString * _Nonnull)adapterVersion @end
Parameters Description name The name of the mediation platform integrated in your app. version The version of the mediation SDK integrated in your app. adapterVersion The version of the Unity Ads adapter for your mediation partner.
Returns : An instance of .Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0. Use iOS deprecated APIs for migration details. was the previous class for passing mediation partner information.
UADSRewardedAd
The UADSRewardedAd class manages the loading and showing of rewarded ads.
load:completion:_
+ (void)load:(UADSLoadConfiguration * _Nonnull)configuration completion:(void (^ _Nonnull)(UADSRewardedAd * _Nullable, id<UnityAdsError> _Nullable))completion;
Loads a rewarded ad with the specified options.
Parameters Description configuration An instance of UADSLoadConfiguration containing the ad loading options. completion A callback that gets called when ad loading finishes. Returns a UADSRewardedAd instance if successful, or an UnityAdsError if loading fails.
show:delegate:_
- (void)show:(UADSShowConfiguration * _Nullable)configuration delegate:(id <UADSRewardedShowDelegate> _Nonnull)delegate;
Displays the loaded rewarded ad.
Parameter Description configuration Optional settings for showing the ad. delegate A delegate that handles rewarded ad events.
onAdExpired
Register a callback that gets triggered when the ad expires.
@interface UnityAd : NSObject @property (nonatomic, copy) void (^ _Nullable onAdExpired)(UnityAd * _Nonnull); @end
UADSShowConfiguration
The class specifies additional parameters that you want to pass in the form of key-value pairs when showing Unity Ads.
@interface UADSShowConfigurationBuilder : NSObject @property (nonatomic, weak, nullable) UIViewController *viewController; @property (nonatomic, strong, nullable) NSString *customRewardString; @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extras; @end
Creates a new instance of with optional additional parameters.
Property Description Required The view controller used to present the ad. No A custom reward identifier for the ad impression. No Additional key–value parameters to include when showing the ad. Defaults to an empty dictionary. No
UADSShowConfigurationBuilder
Use UADSShowConfigurationBuilder
init
- (nonnull instancetype)init;
Creates a new instance of UADSShowConfigurationBuilder
withViewController:_
- (nonnull instancetype)withViewController:(UIViewController * _Nonnull)viewController
Sets the view controller to present the ad from.
Parameter Description The view controller presenting the ad.
Returns : The updated UADSShowConfigurationBuilderwithCustomRewardString:_
- (nonnull instancetype)withCustomRewardString:(NSString * _Nonnull)customRewardString
Sets a custom reward identifier for the ad impression.
Parameter Description A unique reward ID for the ad impression.
Returns : The updated instance.- (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
Adds extra key–value parameters when showing the ad.
Parameter Description Custom parameters for ad display.
Returns : The updated UADSShowConfigurationBuilderbuild
- (UADSShowConfiguration * _Nonnull)build
Builds and returns a instance.
Returns : An instance of .UADSShowOptions
was the previous class for specifying ad show options.
UADSTokenConfiguration
@interface UADSTokenConfiguration : NSObject @property (nonatomic, assign) AdFormat UADSAdFormat; @property (nonatomic, strong, nullable) UADSMediationInfo *mediationInfo; @property (nonatomic, strong, nullable) NSString *mediationAdUnitId; @property (nonatomic, strong, nullable) NSString *placementId; @property (nonatomic, assign) CGSize bannerSize; @property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extras; @end
The interface creates an object consisting of essential information required to get a bidding token.
Property Description Required Specifies the type of ad format (interstitial, rewarded, banner). Yes Specifies details about your mediation integration. No The placement ID used in your mediation partner's dashboard. No The placement ID defined in the Unity Monetization Dashboard. No The size of the banner ad if a token requested a banner ad. No Additional key–value pairs for custom configuration. No
UADSTokenConfigurationBuilder
Use UADSTokenConfigurationBuilder
- (nonnull instancetype)initWithAdFormat:(enum UADSAdFormat)adFormat
Creates a new instance of UADSTokenConfigurationBuilder
Parameter Description adFormat An instance of AdFormat that specifies the type of ad (interstitial, rewarded, banner).
Returns : An instance of UADSTokenConfigurationBuilder- (nonnull instancetype)withMediationInfo:(UADSMediationInfo * _Nonnull)mediationInfo
Specifies details about your mediation integration.
Parameter Description mediationInfo Specifies details about your mediation integration.
Returns : The updated TokenConfigurationBuilder- (nonnull instancetype)withMediationAdUnitId:(NSString * _Nonnull)mediationAdUnitId
Adds the mediation ad unit ID to the .
Property Description The placement ID used in your mediation partner's dashboard.
Returns : The updated UADSTokenConfigurationBuilderwithPlacementId:_
- (nonnull instancetype)withPlacementId:(NSString * _Nonnull)placementId
Specifies the placement ID defined in the Unity Monetization Dashboard.
Parameter Description placementId The placement ID defined in the Unity Monetization Dashboard.
Returns : The updated UADSTokenConfigurationBuilderwithBannerSize:_
- (nonnull instancetype)withBannerSize:(CGSize)bannerSize
Specifies the size of the banner ad if a token requested a banner ad.
Parameter Description bannerSize The size of the banner ad if a token requested a banner ad.
Returns : The updated UADSTokenConfigurationBuilder- (nonnull instancetype)withExtras:(NSDictionary<NSString *, NSString *> * _Nonnull)extras
Specifies additional key–value pairs for custom configuration.
Parameter Description extras Additional key–value pairs for custom configuration.
Returns : The updated UADSTokenConfigurationBuilderbuild
- (UADSTokenConfiguration * _Nonnull)build
Builds and returns a instance.
Returns : An instance of .UnityAds
The class is a static class that serves as the primary entry point for the SDK. It handles initialization, token retrieval, privacy consent, and provides access to global SDK properties.
Initialization
initialize(_, completion:)
Initializes the Unity Ads SDK with a specified configuration. The completion block is called when initialization completes with either success or failure.
+ (void) initialize:(UADSInitializationConfiguration *) configuration completion:(void (^)(id<UnityAdsError> )) completion;
Parameter Description configuration The UADSInitializationConfiguration object that contains the required settings to initialize the SDK. completion A callback that gets called when SDK initialization finishes. Returns an UnityAdsError if initialization fails.
GetToken
getToken(_, completion:)
Fetches a bidding token based on the provided and passes it to the completion block.
+ (void) getToken:(UADSTokenConfiguration *) configuration completion:(void (^)(NSString * )) completion;
Parameter Description configuration A object that specifies the ad format, mediation info, and other parameters. completion A completion block that is called with the token if it's successfully fetched, or null if an error occurs.
Static variables
IsInitialized
Determines if the Unity Ads SDK is initialized successfully.
Returns : If , Unity Ads has been successfully initialized.getVersion
Determines the current Unity Ads SDK version in use.
Returns : The current installed version of Unity Ads SDK.userIdentifier
Sets a unique ID for each user of your app.
@objc public static var userIdentifier: String {...}
Privacy
setUserConsent()
Displays the user's opt-in choices for personalized ads.
+ (void)setUserConsent:(BOOL)consentGranted;
setUserOptOut()
Offers users the option to opt out of data collection and personalized ads.
+ (void)setUserOptOut:(BOOL)optOut;
setNonBehavioral()
Enables the display of contextual (non-personalized) ads.
+ (void)setNonBehavioral:(BOOL)nonBehavioral;
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0. Use the typed privacy methods on iOS deprecated APIs for migration details. was the previous class for setting GDPR and other privacy-related flags.
UnityAdsInitializationDelegate
UnityAdsInitializationDelegateUnityAdsLoadDelegate
was the previous delegate protocol for ad loading callbacks.
UnityAdsShowDelegate
was the previous delegate protocol for ad show callbacks.
Enum
Defines the different types of ad formats supported by Unity Ads.
typedef enum { UADSAdFormatUnspecified = 0, UADSAdFormatInterstitial = 1, UADSAdFormatRewarded = 2, UADSAdFormatBanner = 3, } UADSAdFormat;
Parameter Description UADSAdFormatUnspecified No specified ad format. UADSAdFormatInterstitial Full-screen ads shown at natural pauses in the app. UADSAdFormatRewarded Ads that grant users a reward after completion. UADSAdFormatBanner Rectangular ads displayed within the app's layout, typically anchored to the top or bottom of the screen.
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0. Use iOS deprecated APIs for migration details. was the previous enum for ad format types.
UADSLogLevel
Defines the logging levels for Unity Ads.
typedef enum { UADSLogLevelDisabled = 0, UADSLogLevelError = 1, UADSLogLevelInfo = 2, UADSLogLevelDebug = 3, } UADSLogLevel;
Parameter Description UADSLogLevelDisabled No logs output. UADSLogLevelError Logs only critical errors and failures in init/load/show operations. UADSLogLevelInfo Logs key operational events (such as initialization started/completed, load started/completed, show started/finished, and token generation). UADSLogLevelDebug Logs all info plus detailed internal operations like network requests and internal errors.
UADSShowFinishState
Represents the finish state of an ad after it has been shown.
typedef enum { UADSShowFinishStateSkipped = 0, UADSShowFinishStateCompleted = 1, } UADSShowFinishState
Parameter Description UADSShowFinishStateSkipped The user closed or skipped the ad before it finished. UADSShowFinishStateCompleted The ad played until the end.
Protocol
UADSBannerAdDelegate
@protocol UADSBannerAdDelegate <NSObject> - (void)bannerImpression:(UADSBannerAd * _Nonnull)banner; - (void)bannerDidClick:(UADSBannerAd * _Nonnull)banner; - (void)bannerDidFailShow:(UADSBannerAd * _Nonnull)banner error:(id<UnityAdsError> _Nonnull)error; @end
Method Description Called when a banner ad is displayed (impression recorded). Called when the user clicks the banner ad. Called if the banner fails to display, with an explaining the failure.
UADSInterstitialShowDelegate
@protocol UADSInterstitialShowDelegate <NSObject> - (void)showDidStart:(UADSInterstitialAd * _Nonnull)unityAd; - (void)showDidClick:(UADSInterstitialAd * _Nonnull)unityAd; - (void)showDidComplete:(UADSInterstitialAd * _Nonnull)unityAd with:(enum UADSShowFinishState)finishState; - (void)showDidFail:(UADSInterstitialAd * _Nonnull)unityAd error:(id<UnityAdsError> _Nonnull)error; @end
Method Description Called when the interstitial ad starts showing. Called when the interstitial ad is clicked. Called when the ad finishes showing. Provides a ( or ). Called if the ad fails to show, with an explaining the failure.
UADSRewardedShowDelegate
@protocol UADSRewardedShowDelegate <NSObject> - (void)showDidStart:(UADSRewardedAd * _Nonnull)unityAd; - (void)showDidClick:(UADSRewardedAd * _Nonnull)unityAd; - (void)showDidComplete:(UADSRewardedAd * _Nonnull)unityAd with:(enum UADSShowFinishState)finishState; - (void)showDidFail:(UADSRewardedAd * _Nonnull)unityAd error:(id<UnityAdsError> _Nonnull)error; - (void)showDidReceiveReward:(UADSRewardedAd * _Nonnull)unityAd; @end
Method Description Called when the rewarded ad starts showing. Called when the rewarded ad is clicked. Called when the ad finishes showing. Provides a ( or ). Called if the ad fails to show, with an explaining the failure. Called when the user earns the reward from the ad.
UnityAdsError
@protocol UnityAdsError @property (nonatomic, readonly) NSInteger code; @property (nonatomic, readonly, copy) NSString * _Nonnull message; @end
Parameter Description code message
UADSBannerErrorCode
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0. Use the protocol instead. See iOS deprecated APIs for migration details. was the previous enum for banner-specific error codes.
UnityAdsInitializationError
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0. Use the protocol instead. See iOS deprecated APIs for migration details. UnityAdsInitializationErrorUnityAdsLoadError
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0. Use the protocol instead. See iOS deprecated APIs for migration details. was the previous enum for ad load error types.
UnityAdsShowError
Warning
Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0. Use the protocol instead. See iOS deprecated APIs for migration details. was the previous enum for ad show error types.