api ios - Unity-Technologies/unity-ads GitHub Wiki

/*
Title: iOS API reference Description:
Sort: 5 */

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

• UnityAds
• UADSBannerView

Enums

• BannerPosition
• UnityAdsPlacementState
• UnityAdsFinishState
• UnityAdsInitializationError
• UnityAdsLoadError
• UnityAdsShowError
• UnityAdsShowCompletionState
• UnityAdsShowError

Delegates

• UnityAdsInitializationDelegate
• UnityAdsLoadDelegate
• UnityAdsShowDelegate
• UnityAdsDelegate
• UADSBannerDelegate
• UADSBannerAdRefreshView

#import <UnityAds/UnityAds.h>

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

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

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

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

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

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

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

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

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

Removes an active UnityAdsDelegate listener.

+ (BOOL)getDebugMode {
    return [UnityServices getDebugMode];
}

Controls the amount of logging output from the SDK. Set to YES for more robust logging.

+ (void)getDebugMode: (BOOL)enableDebugMode {
    [UnityServices setDebugMode: enableDebugMode];
}

Returns YES if the SDK is is in debug mode, and NO if it isn't.

+ (NSString *)getVersion {
    return [UnityServices getVersion];
}

Returns the current version of the Unity Ads SDK.

+ (BOOL)isInitialized {
    return [USRVSdkProperties isInitialized];
}

Returns YES if the SDK is initialized successfully, and NO if it isn't.

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

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

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.

-(void)load;

The basic method for requesting an ad for the banner.

typedef NS_ENUM(NSInteger, UnityAdsPlacementState)

The enumerated states of an Ad Unit.

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.

typedef NS_ENUM (NSInteger, UnityAdsInitializationError)

The enumerated reasons for SDK initialization to fail.

typedef NS_ENUM (NSInteger, UnityAdsLoadError)

The enumerated reasons for an Ad Unit failing to load.

typedef NS_ENUM (NSInteger, UnityAdsShowCompletionState)

The enumerated causes for the ad to have finished.

typedef NS_ENUM (NSInteger, UnityAdsShowError)

The enumerated reasons for an Ad Unit failing to show.

typedef NS_ENUM (NSInteger, UnityAdsError)

The enumerated causes of a Unity Ads error emitted through the unityAdsDidError callback.

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

@protocol UnityAdsInitializationDelegate <NSObject>
- (void)initializationComplete;
- (void)initializationFailed: (UnityAdsInitializationError)error withMessage: (NSString *)message;
@end

Implement this delegate to handle initialize results.

This callback method handles logic for the SDK successfully initializing.

This callback method handles logic for the SDK failing to initialize.

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

This callback method handles logic for the Ad Unit successfully loading.

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

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

This callback method handles logic for the ad finishing.

This callback method handles logic for the ad starting to play.

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

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

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

Specify logic for ad content being ready to display through a specified Ad Unit.

Specify logic for ad content failing to display due to an error.

Specify logic for the player triggering an ad to show.

Specify logic for the player watching the ad in its entirety.

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

This callback fires when the banner successfully loaded ad content.

This callback fires when the user clicked the banner ad.

This callback fires when the banner closed because the user quit the application.

This callback fires when UnityAdsBanner encounters an error.

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

Called when the banner is loaded and ready to be placed in the view hierarchy.

Called when no ad content is available for the banner.

Called when the banner is visible to the user.

Called when the banner is hidden to the user.

Called when the user clicked the banner ad.

Called when UnityAdsBanner encounters an error.