Knowledge base

Integration Guide for XCode (iOS)

This guide will show you how to integrate Unity Ads into a native iOS project in Objective-C or Swift.

Download the Unity Ads Framework here.

Video tutorials available here

Example projects can be found on GitHub.

Contents:


Quickstart Guide

Create a Game Project in the Unity Ads Dashboard

Log into the Unity Ads Dashboard using your UDN account.

  • If you don't have a UDN account yet, sign up here.

From the Dashboard, create a new game project.

NOTE: Leave the "targets children under 13" option OFF unless your game is specifically designed for children in the USA. Games for all ages are not required to enable COPPA compliance.

Locate the (7-digit) Game ID by selecting your game project. You will use this number to activate Unity Ads.

Locate your placement IDs by selecting a game ID (iOS or Android), then clicking the Placements tab. Initially, each game ID has two placements:

  • video (default / skip video after 5 seconds)
  • rewardedVideo (no skip option)

Enable test mode for each game ID under the settings tab.

Apple/Play Store Game ID > Settings > Test mode: Force ON

Integrate Unity Ads in Swift

Scroll down for Objective-C

Import Unity Ads

Download the latest Unity Ads Framework here.

Drag-and-drop the Framework into your project, and copy it.

In your ViewController, import Unity Ads and set the Unity Ads delegate:

import UnityAds

class GameViewController: UIViewController, UnityAdsDelegate {

Add the UnityAds callbacks to the UnityAdsDelegate:

  • unityAdsReady
  • unityAdsDidStart
  • unityAdsDidError
  • unityAdsDidFinish
func unityAdsReady(_ placementId: String) { }

func unityAdsDidStart(_ placementId: String) { }

func unityAdsDidError(_ error: UnityAdsError, withMessage message: String) { }

func unityAdsDidFinish(_ placementId: String, with state: UnityAdsFinishState) { }

At this point, the project should compile.

Initialize Unity Ads & show a video

Initialize the SDK with UnityAds.initialize().

Enter your 7-digit Game ID from the dashboard, and enter self for the UnityAdsDelegate, for example:

override func viewDidLoad() {
  super.viewDidLoad()
  UnityAds.initialize("1003843", delegate: self)
}

Check that a video is ready, then show a video using a valid placement ID:

let placement = "rewardedVideo"
if (UnityAds.isReady(placement)) {
  //a video is ready & placement is valid
  UnityAds.show(self, placementId: placement)
}

At this point, you should be able to watch video ads in your game.

Reward the player for watching an ad

To maximize revenue with Unity Ads, it's important to reward your players in-game for watching an ad. Common rewards include:

  • Free in-game currency
  • A performance boost for a few minutes
  • An opportunity to continue after a game over
  • In-game item or unlocks

Use the unityAdsDidFinish() callback method to check that the video was not skipped, then reward your player:

func unityAdsDidFinish(_ placementId: String, with state: UnityAdsFinishState) {
  if state != .skipped{
    //Add code to reward the player here
  }
}

Integrate Unity Ads in Objective-C

Import Unity Ads

Download the latest Unity Ads Framework here.

Drag-and-drop the Framework into your project, and copy it.

In your ViewController header (.h), import Unity Ads and set the Unity Ads delegate:

#import "UnityAds/UnityAds.h"

@interface ViewController : UIViewController<UnityAdsDelegate>

In your Viewcontroller implementation (.m), add the following @required methods:

- (void)unityAdsReady:(NSString *)placementId{
}

- (void)unityAdsDidError:(UnityAdsError)error withMessage:(NSString *)message{
}

- (void)unityAdsDidStart:(NSString *)placementId{
}

- (void)unityAdsDidFinish:(NSString *)placementId withFinishState:(UnityAdsFinishState)state{
}

:white_check_mark: At this point, the project should compile.

Initialize Unity Ads and show a video

Initialize the SDK with UnityAds.initialize():

NOTE: Enter your 7-digit Game ID as a string.

- (void)viewDidLoad {
  [super viewDidLoad];
  [UnityAds initialize:@"1088169" delegate:self];
}

NOTE: Initialization can take 10 seconds or more, so initialize UnityAds early in your game's lifecycle

Check that a video is ready, then show a video using an existing placement ID from the dashboard:

if ([UnityAds isReady:@"rewardedVideo"]) {
  [UnityAds show:self placementId:@"rewardedVideo"];
}

:white_check_mark: At this point, you should be able to watch video ads in your game.

Reward the player for watching an ad

To maximize revenue with Unity Ads, it's important to reward your players for watching an ad. Common rewards include:

  • Free in-game currency
  • A performance boost for a few minutes
  • An opportunity to continue after a game over
  • In-game item or level unlocks

To reward a player, use the unityAdsDidFinish() callback method, and check that the video was not skipped:

func unityAdsDidFinish(_ placementId: String, with state: UnityAdsFinishState) {
  if state != .skipped{
    //reward the player!
  }
}

At this point, you should be able to show videos and reward the player.


Unity Ads iOS Advanced Guides

For Additional questions, please contact us at unityads-support@unity3d.com

Still need help? Get in touch!
Last updated on 20th Aug 2017