Skip to content
This repository was archived by the owner on Apr 26, 2024. It is now read-only.

integration guide ios

Jump to bottom
Solomon Li edited this page May 9, 2016 · 4 revisions

/* Title: Integration Guide for iOS
Description: A guide to integrating the Unity Ads SDK for iOS
Sort: 11
*/

Unity Ads is a monetization tool that allows you to display video trailers of other games to your users, earn money with each view, and reward users with a virtual item. To monetize your users with Unity Ads, integrate the Unity Ads SDK into your game. This document will guide you through that process.

Note: These instructions are meant for non-unity integrations, if you are using Unity please refer to Unity Specific instructions here

Unity Ads Integration consists of the following parts:

Integrating Unity Ads to your iOS Game

Note: If you have not done so already, download the Unity Ads SDK from GitHub.

The process of integrating Unity Ads to your iOS game is fairly straightforward and does not require heavy integration. The process of using Unity Ads in your applications is described below in outlined steps:

  • Import (drag and drop) UnityAds.framework and UnityAds.bundle into your Xcode project from the root directory of your SDK folder
  • Initialize the SDK with your Unity Ads gameId
  • Verify that there are campaigns available to the user
  • Show Unity Ads to user
  • Wait for the user to complete watching the video, and reward the item to the user

Your project will needs to include the following frameworks to compile Unity Ads

AdSupport.framework, AVFoundation.framework, CFNetwork.framework, CoreFoundation.framework

CoreMedia.framework, CoreTelephony.framework, StoreKit.framework, SystemConfiguration.framework

  1. Select Project Settings > Build Phases
  2. Expand "Link Binary with Libraries" section
  3. For each framework, click "+", and add the framework to the Project

The actual code-level integration is described in the sections below. Should you have any problems integrating the product, log a ticket with us by emailing [email protected].

Initializing Unity Ads in your App Delegate

The first step is to add the UnityAds class to your app delegate. Firstly, you need to include the necessary headers:

#import <UnityAds/UnityAds.h>

Then, to your -application:didFinishLaunchingWithOptions: -method, add the initialization code for Unity Ads by passing your Unity Ads gameId, and your root view controller.

// Initialize Unity Ads
[[UnityAds sharedInstance] startWithGameId:@"1003843" andViewController:myViewController]; //replace game ID with your own

Note: Replace the YOUR_GAME_ID_HERE section above with your Unity Ads gameId. You can find this in the Unity Ads Admin Panel under the section “Publisher > Games”.

If for some reason you cannot pass the view controller to Unity Ads at the time when it is initialized, you can init Unity Ads with just calling startWithGameId, without the view controller.

Example:

[[UnityAds sharedInstance] startWithGameId:@"1003843"];

Before you can use Unity Ads, you need to pass the view controller via the setViewController method:

- (void)setViewController:(UIViewController *)viewController;

Example:

[[UnityAds sharedInstance] startWithGameId:1003843];

// Other initialization code
// ...

// Add the view controller
[[UnityAds sharedInstance] setViewController:myViewController];

Configuring your ViewController as a Delegate

Your ViewController needs to act as a delegate for Unity Ads. First, you must register your ViewController as the delegate.

[[UnityAds sharedInstance] setDelegate:self];

The delegate must implement the following method at minimum:

- (void)unityAdsVideoCompleted:(NSString *)rewardItemKey skipped:(BOOL)skipped

This delegate method is called when the user has completed watching a video with Unity Ads, and they should be granted the virtual item offered as a reward if skipped is false.

Showing Video Ads with Unity Ads

When you have initialized the Unity Ads SDK and added your ViewController as the Unity Ads delegate, you can start showing ads in your application. Prior to showing ads, you should always check if there is an ad available for the current user. To see if the ad unit can be shown and whether there is inventory available, use the canShow method. When you have done these checks, you can show an ad to the user using the show method.

Using Ad Placement (Zones)

This functionality allows different configurations for different ads setup in the Unity Ads Admin Panel. Typical example would be a game that shows both: incentivized (watch video get 100 coins) and non-incentivized ads. Usually ad skipping is disabled for incentivized ads and enabled for non-incentivized ads.

You should call setZone just before calling show.

The zoneId is defined in the Unity Ads Admin Panel when defining an Ad-placement. The rewardItemKey is defined in the Unity Ads Admin Panel when defining a reward item.

// Set the zone before checking readiness or attempting to show.
[[UnityAds sharedInstance] setZone:@"rewardedVideo"];

// Use the canShow method to check for zone readiness,
//  then use the canShowAds method to check for ad readiness.
if ([[UnityAds sharedInstance] canShow])
{
    // If both are ready, show the ad.
    [[UnityAds sharedInstance] show];
}

When the ad view is closed, it will automatically remove itself from the ViewController. If you need to close the ad view from your code, you can call the hide method:

[[UnityAds sharedInstance] hide]

Note: The way this API works is that you either don't call setZone at all and use the default ad placement settings everywhere, or you explicitly call setZone always before calling show.

Passing user ID for server-side redeem callbacks

You can pass an optional parameter for Unity Ads by passing the show method a dictionary that defines the requested properties.

  • kUnityAdsOptionGamerSIDKey:@"playerName" – You can give an offer or user ID to Unity Ads through this parameter.

Example:

[[UnityAds sharedInstance] show:@{
    kUnityAdsOptionGamerSIDKey:@"gamerSid"}]

Rewarding the User

If you are not rewarding your users for videos you can safely ignore this section.

Note: The item key functionality is no longer supported.
It will be deprecated in a future SDK release.

Once the user has completed the video ad, the Unity Ads SDK will call the -unityAdsVideoCompleted:rewardItemKey:skipped: delegate method. At this point, you should reward the user with the virtual item that was promised to them. This delegate method passes you the item key of the reward item as a parameter. See section titled “About Item Keys” below to read more about item keys.

unityAdsVideoCompleted:rewardItemKey:skipped: now has a boolean indicating whether user skipped the video or not. If user skips the video he/she shouldn't get the reward, but that is up to developer.

Also note: that the call to the -unityAdsVideoCompleted:rewardItemKey:skipped: method is not a guarantee of the Unity Ads adView being closed, for that, please use the -unityAdsWillHide: delegate method.

About Item Keys

Item keys are a way to differentiate between different rewards in your game. As the redeeming of the virtual items is done inside your game code, you need a way to change the reward item without updating your game. Therefore, the Unity Ads SDK allows you to configure an item key on the Unity Ads Admin Panel that will be passed to your code. It is recommended that you add as many reward items as possible to your code, and differentiate between them with different item keys. This allows you to change the item without changing your code.

Example of multiple items

- (void)unityAdsVideoCompleted:(NSString *)rewardItemKey skipped:(BOOL)skipped
{
   NSLog(@"unityAdsVideoCompleted:rewardItemKey:skipped: -- key: %@", rewardItemKey);
   if([rewardItemKey isEqualToString:@"item_armor"]) {
      [self awardUserWithArmor]
   } else if([rewardItemKey isEqualToString:@"gold_50k"]) {
      [self awardUserWithGold50]
   } else if([rewardItemKey isEqualToString:@"gold_100k"]) {
      [self awardUserWithGold100]
   }
}

Using Multiple Reward Items

Note: Multiple item support is available in SDK version 1.0.3 or newer.

To create a more flexible incentivization for the users, the Unity Ads SDK allows you to configure multiple reward items in the Unity Ads Admin Panel, so your integration can at run-time decide which reward item should be used. This feature is useful is you’re for example providing a free boost in your game, and there are multiple boosts available that you want the user to be able to pick from.

Each integration needs to define a default reward item in the Admin Panel, which will be used if you do not explicitly choose a reward item in your client-side code.

You can change the reward item to be shown to the user by calling the - (BOOL)setRewardItemKey:(NSString *)rewardItemKey; method of the Unity Ads instance.

Example:

-(void) showToUser
{

   // Get the reward item key the user selected in our game's offer menu
   NSString* reward = [myGameUI getRewardItemElement];
   // Tell Unity Ads to use this reward
   /* Note: The Unity Ads UI is already inited in the background, and this call will cause it to change
      to show the new reward item and if you show the Unity Ads view _immediately_ after calling this,
      there may be some flickering, so make sure to call setRewardItemKey as soon as possible in your code */
   [[UnityAds sharedInstance] setRewardItemKey:reward];
   // Show Unity Ads
   [[UnityAds sharedInstance] show];

   /* Now when the user completes the video, the itemKey passed
      to the unityAdsVideoCompleted:rewardItemKey:skipped: delegate method
      will be the one set in this method using the
      setRewardItemKey method
    */

}

You can query the currently set reward item using the - (NSString *)getCurrentRewardItemKey; method. All available reward items can be queried using the - (NSArray *)getRewardItemKeys; method which returns an NSArray* of the item keys. You can query the item details (name, picture) using the - (NSDictionary *)getRewardItemDetailsWithKey:(NSString *)rewardItemKey; method. This method returns an NSDictionary* object that contains two keys that have the following values:

Key kUnityAdsRewardItemPictureKey // contains the URL to the picture as a value
Key kUnityAdsRewardItemNameKey // contains the human readable name (e.g. “100 Coins!”) as a value

Example:

NSArray* items = [[UnityAds sharedInstance] getRewardItemKeys];
for (id itemKey in items) {
  NSDictionary* itemDetails = [[UnityAds] sharedInstance] getRewardItemDetailsWithKey:itemKey];
  NSLog(@"Item %@: Picture: %@, Name: %@",
         itemKey,
         [itemDetails objectForKey:kUnityAdsRewardItemPictureKey]
         [itemDetails objectForKey:kUnityAdsRewardItemNameKey]);
}

Testing your Integration

To test your integration, you can run Unity Ads in test mode. This can be achieved by calling the setTestMode:(BOOL)testModeEnabled method of the UnityAds class prior to calling startWithGameId. Example:

// TEST MODE: Do not use in production apps
[[UnityAds sharedInstance] setTestMode:YES];
[[UnityAds sharedInstance] setDebugMode:YES];

[[UnityAds sharedInstance] startWithGameId:@"YOUR_GAME_ID_HERE" andWithViewController:myViewController];

Configuring Unity Ads on the Unity Ads Admin Panel

To configure Unity Ads for your iOS game, log into the Unity Ads Admin Panel at https://unityads.unity3d.com/admin/.

Adding Your Game

First, you need to register your game in the Unity Ads Admin Panel. For this, you need the iTunes application ID or the iTunes URL for your application. For example:

https://itunes.apple.com/us/app/fatcat-rush/id457251993?mt=8

or

457251993

To register the game, go to the Games page from menu of the Unity Ads Admin Panel and click Add New Game.

After the game has been successfully added, it will show up in the games listing. Click on the game to access further options. Click 'Monetizing Settings' to open up the game’s integration details. On this page, you will find the Unity Ads gameId that you need to use when calling startWithGameId.

Here you may also change the options of the Ad Placements you want to have in your game. You can create additional placements with different settings for e.g. tracking purposes. Each placement's settings are individually adjustable.

Home

置顶

Unity Ads 开发者, 流量变现指导

常见问题（FAQ）

其他

联系方式

咨询

Clone this wiki locally