Knowledge base

Integration guide for iOS (Objective-C)

Overview

This guide covers basic integration for implementing Unity Ads in your made-with-Unity game.

  • If you are a Unity developer using C#, click here.
  • If you are an Android developer using Java, click here.

Unity’s monetization platform provides you with powerful revenue tools. If your game uses in-app purchases as well as ads, Unity’s machine learning data model can seamlessly blend content types for an optimized monetization strategy. To learn more about how Unity helps you optimize revenue, see documentation on Personalized Placements.

In this guide:

Creating a Project in the Unity Developer Dashboard

If you don't have a Unity Developer (UDN) account yet, create one here. When you have an account, follow these steps to create a Unity Project:

  1. Log in to the Developer Dashboard, and navigate to the Operate tab.
  2. Select Projects from the left navigation bar.
  3. Click the NEW PROJECT button in the top right corner.

Locate your Project’s Game ID by selecting your Project, then selecting Monetization > Platforms from the left navigation bar. Copy the Apple App Store Game ID, because you need it to activate the Unity Ads service in your game.

Creating a Placement

Placements are triggered events within your game that display monetization content. Manage Placements from the Operate tab of the Developer Dashboard by selecting your Project, then selecting Monetization > Placements from the left navigation bar.

Click the ADD PLACEMENT button to bring up the Placement creation prompt. Name your Placement and select its type:

  • Select Non-rewarded to show basic interstitial ads or promotional content. Non-rewarded Placements allow players to skip the ad after a specified period of time.
  • Select Rewarded to allow players to opt-in to viewing ads in exchange for incentives. Rewarded Placements do not allow the player to skip the ad.
  • Select Banner to create a dedicated Banner ad Placement.

Every Unity Ads-enabled project has a (non-rewarded) ‘video’ and (rewarded) ‘rewardedVideo’ Placement by default. Feel free to use one of these for your first implementation if they suit your needs, or create your own.

Implementing Unity Ads in your game

Importing the Unity Ads framework

Download the Unity Ads framework here. The UnityMonetization API requires SDK 3.0 or later.

  1. Drag-and-drop the framework into your Unity Project folder, and copy it.
  2. In your ViewController header (.h), import Unity Ads and set the Unity Ads delegate:
#import <UIKit/UIKit.h>
#import <UnityAds/UnityMonetization.h>

@interface ViewController : UIViewController<UnityMonetizationDelegate, UMONShowAdDelegate>
@end

Initializing the Unity Ads SDK

To initialize the SDK, you must reference your Project’s Game ID for the appropriate platform. You can locate the ID on the Operate tab of the Developer Dashboard by selecting the Project, then selecting Monetization > Platforms from the left navigation bar.

Locating your Game ID in the Developer Dashboard

In your ViewController implementation (.m), use the setDelegate method to set the monetization delegate. Next, call the initialize method to initialize the SDK early in your game’s runtime lifecycle, before you need to show ads. For example:

#import "ViewController.h"

@implementation ViewController

- (void) viewDidLoad {
    [super viewDidLoad];
    [UnityMonetization initialize : @"1234567" delegate : self testMode : true];
}
@end

Implementing basic (non-rewarded) ads

PlacementContent is an object representing monetization content that your Placement can display. For more information, see documentation on Content types and Personalized Placements.

UMONPlacementContent is an object representing monetization content that your Placement can display (for more information, see documentation on content types and Personalized Placements). Use the UnityMonetizationDelegate delegate’s placementContentReady function to retrieve content when it’s ready to display, and the show function to display it. For example:

@interface ViewController : UIViewController <UnityMonetizationDelegate, UMONShowAdDelegate>

@property (strong) NSString* activePlacementId;

@end

@implementation ViewController

-(void) viewDidLoad {
    [super viewDidLoad];
    self.activePlacementId = @"video”;
    [UnityMonetization initialize: @"1234567" delegate: self testMode: YES];
}

-(void) showInterstitial {
    // Check if PlacementContent is ready:
    if ([self.interstitialVideo ready]) {
        // Show PlacementContent:
        [self.interstitialVideo show: self]
    }
}
@end

Implementing rewarded ads

Rewarding players for watching ads increases user engagement, resulting in higher revenue. For example, games may reward players with in-game currency, consumables, additional lives, or experience-multipliers. For more information on how to effectively design your rewarded ads, see documentation on Ads best practices.

To reward players for watching ads, follow the same steps as detailed in the basic implementation section, but show the ad using a reward callback method with custom logic for players completing the ad.

Selecting a Placement

You must display rewarded ads through Rewarded Placements. Every Unity Ads-enabled Project also has a ‘rewardedVideo’ Placement by default. Feel free to use this for your implementation, or create your own (but make sure your Placement is configured as Rewarded).

Adding a callback method to your script

The show function uses a delegate to return the ad’s UnityAdsFinishState. This result indicates whether the player finished or skipped the ad. Use this information to write a custom function for how to handle each scenario. For example:

@interface ViewController : UIViewController <UnityMonetizationDelegate, UMONShowAdDelegate>

@property (strong) NSString* interstitialPlacementId;
@property (strong) NSString* rewardedPlacementId;
@property (strong) UMONPlacementContent* interstitialVideo;
@property (strong) UMONPlacementContent* rewardedVideo;
@end

@implementation ViewController

-(void) viewDidLoad {
    [super viewDidLoad];
    self.interstitialPlacementId = @"video”;
    self.rewardedPlacementId = @"rewardedVideo”;
    [UnityMonetization initialize: @"1234567" delegate: self testMode: YES];
}

-(void) showInterstitialVideo {
    if ([self.interstitialVideo ready]) {
        [self.interstitialVideo show: self withDelegate: self]
    }
}

-(void) showRewardedVideo {
    if ([self.rewardedVideo ready]) {
        [self.rewardedVideo show: self withDelegate: self];
    }
}

// Implement the delegate for retrieving PlacementContent:
#pragma mark: UnityMonetizationDelegate

-(void) placementContentReady: (NSString *) placementId placementContent: (UMONPlacementContent *) placementContent {
    // Check and set the available PlacementContent:
    if ([placementId isEqualToString: self.interstitialPlacementId]) {
        self.interstitialVideo = placementContent;
    } else if ([placementId isEqualToString: self.rewardedPlacementId]) {
        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
    }
}

-(void) unityServicesDidError: (UnityServicesError) error withMessage: (NSString *) message {
    NSLog (@"UnityMonetization ERROR: %ld - %@", (long) error, message);
}

// Implement the delegate for handling the ad’s finishState
#pragma mark: UMONShowAdDelegate

-(void) unityAdsDidStart: (NSString *) placementId {
    // (Optional) Log or perform some action when the ad starts

    NSLog (@"Unity ad started for: %@", placementId);
}

-(void) unityAdsDidFinish: (NSString *) placementId withFinishState: (UnityAdsFinishState) finishState {
    // If the ad played in its entirety, and the Placement is rewarded, perform reward logic:
    if (finishState == kUnityAdsFinishStateCompleted
        && [placementId isEqualToString:self.rewardedPlacementId]) {
        // Reward player for watching the entire video
    }
}
@end

Rewarded ads button code example

Rewarded ads usually use a button that prompts players to opt in to watching the ad. You could modify the above example script to include a button, simply by declaring an extra variable and writing a function that calls showRewardedVideo when pressing the button:

@property (strong) UIButton* rewardedVideoButton;

-(void) onRewardedVideoButtonTap {
    [self.showRewardedVideo];
}

Implementing Banner ads

Placement configuration

Banner ads require a specific type of dedicated banner Placement. Banners currently display anchored on the bottom-center of the screen.

Example banner ad

Script implementation

Add your code to the ViewController implementation (.m). The following script sample is an example implementation for displaying banner ads. For more information on the classes referenced, see the UnityAdsBanner API section.

@interface ViewController: UIViewController <UnityAdsBannerDelegate>

@property (copy, nonatomic) NSString* bannerPlacementId;

@end

@implementation ViewController

-(void) viewDidLoad {
    [super viewDidLoad];
    [UnityAdsBanner setDelegate: self];
    [UnityAds initialize: @"1234567" delegate: nil testMode: YES];
}

// If the Placement is ready, load the banner:
-(void) loadBanner {
    if ([UnityAds isReady: self.bannerPlacementId]) {
        [UnityAdsBanner loadBanner: self.bannerPlacementId];
    }
}

-(void) unloadBanner {
    [UnityAdsBanner destroy];
}

-(void) unityAdsBannerDidClick: (NSString *) placementId {
    // Define behavior for the player clicking the banner.
}

-(void) unityAdsBannerDidError: (NSString *) message {
    // Define behavior for an error occurring within the banner.
    // Consider the banner unloaded.
}

-(void) unityAdsBannerDidHide: (NSString *) placementId {
    // The banner was hidden due to being removed from the view hierarchy or the window changing
}

-(void) unityAdsBannerDidShow: (NSString *) placementId {
    // The banner entered the view hierarchy and is visible to the user
}

// The banner loaded and is available to show:
-(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];
}

// The banner was destroyed, so references can be removed:
-(void) unityAdsBannerDidUnload: (NSString *) placementId {
    self.bannerView = nil;
}
@end

Testing

Prior to publishing your game, enable test mode by following these steps:

  1. From the Operate tab of the Developer Dashboard, select your Project.
  2. Select Monetization > Platforms from the left navigation bar.
  3. Select the desired platform, then select the SETTINGS tab.
  4. Scroll down to the TEST MODE section and toggle override client test mode, then select the Force test mode ON radio button.

Run your project and test your ads implementation.

Note: You must enable test mode before testing ads integration, to avoid getting flagged for fraud.

Optimizing your revenue

Congratulations on implementing Unity Ads! Our goal is to make it easy for you to maximize your revenue. With that in mind, consider these next steps:

  • If your game uses in-app purchasing, implement IAP Promo using purchasing integration for Android to promote your in-app offers.
  • When you have Ads and IAP Promo set up, use Personalized Placements to turbocharge your ads and IAP strategy and provide revenue lift for your entire game.
  • Review our Best practices guide for insight on how to design effective ad mechanics.

Back to top

iOS API reference

UnityServicesDelegate

Use this class for initializing Unity Services.

initialize

Initializes Unity Ads in your game at run time. To avoid errors, initialization should occur early in the game’s run-time lifecycle, preferably at boot. Initialization must occur prior to showing ads.

+ (void) initialize: (NSString *) gameId
    delegate: (nullable id <UnityServicesDelegate>) delegate;

    testMode: (BOOL) testMode;

The gameID parameter is the Game ID for your Project found on the Developer Dashboard. The delegate parameter is the delegate for UnityAdsDelegate callbacks. The testMode parameter indicates whether the game is in test mode. When testMode is 'YES', you will only see test ads. When testMode is 'NO', you will see live ads. It is important to use test mode prior to launching your game, to avoid being flagged for fraud.

getDebugMode and setDebugMode

Methods for checking or setting whether the game is in test mode.

+ (BOOL) getDebugMode;
+ (void) setDebugMode: (BOOL) enableDebugMode;

The getDebugMode function returns ‘YES’ if the game is in test mode. Pass ‘YES’ through the setDebugMode function to enable test mode, or ‘NO’ to disable it.

isSupported

Checks to see if the current device supports Unity Ads.

+ (BOOL) isSupported;

Returns ‘YES’ if the device supports Unity Ads, and ‘NO’ if it doesn’t.

getVersion

Returns the string version of this Unity Ads SDK.

+ (NSString *) getVersion;

isInitialized

Checks whether Unity Ads has been initialized. This may be useful for debugging initialization problems.

+ (BOOL) isInitialized;

Returns ‘YES’ if Unity Ads is initialized, and ‘NO’ if it isn’t.

UnityMonetization

This is a static class that implements a delegate to deal with Placement statuses and content.

@interface UnityMonetization: NSObject
+ (void) setDelegate: (id <UnityMonetizationDelegate>) delegate;

+ (nullable id <UnityMonetizationDelegate>) getDelegate;

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

+ (nullable UMONPlacementContent *) getPlacementContent: (NSString *) placementId;
@end

UnityMonetizationDelegate

Implement this delegate and pass it back to the SDK.

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.

UnityAdsBanner

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

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 (as defined in the Developer Dashboard).
+(void) loadBanner: (NSString *) placementId Loads the banner ad with a specific Placement ID.

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;

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;

UnityAdsBannerDelegate

Implement this delegate class for callbacks, and passes it to [UnityAdsBanner setDelegate].

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;

Back to top

Still need help? Get in touch!
Last updated on 16th Nov 2018