Personalized Placements integration for iOS developers

Overview

This guide covers implementation for Personalized Placements in your iOS game.

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

Guide contents

Implementation

Importing the Unity Monetization framework

To get started, download the latest version of the Monetization framework for iOS. Personalized Placements require the Monetization SDK 3.0 or later. For information on downloading and importing the SDK, read that section of the basic ads integration guide for iOS.

Implementing Unity Ads

To implement rewarded or non-rewarded ads in your Unity Project, you must initialize the Unity Monetization SDK, then implement scripts at your surfacing points that access and display content through Placement IDs. For a comprehensive guide, read the ads integration guide for iOS.

Note: The Unity Ads integration for Personalized Placements differs slightly from the basic ads integration, as it requires the UnityMonetization API instead of the UnityAds API.

Unity also recommends reviewing the rewarded ads best practices guide as part of your implementation strategy.

Using mediation

If you use ads mediation, the integration process for Unity Ads differs as dictated by your mediation partner. You can find integration guides and SDK adapters for the following widely-used mediation partners below:

For more details, see documentation on Unity Ads mediation. If you have questions regarding compatibility with other mediators, please contact your Unity representative.

Implementing in-app purchasing

The Monetization SDK allows you to take advantage of Personalized Placements using a custom purchasing integration, by implementing a purchasing adapter. This adapter is required for Unity to hook into the necessary machine learning data. For a complete guide on implementing a purchasing adapter, see documentation on purchasing integration for iOS.

Implementing Standard Events

Standard Events track user experience and player behavior across your game. Implement a subset of game economy events so that Unity’s machine learning engine can optimize your Placement content. Game economy events help the Personalized Placements data model form a complete picture of each player’s preferences and actions in your game, then determine what actions to take accordingly.

The Monetization SDK allows you to use Unity Analytics APIs in iOS games that are not made with Unity. To implement these events in your game and fire the event at the user level to Unity’s endpoint, invoke the UnityAnalytics interface: 

@interface UnityAnalytics: NSObject

Logging acquire and spend events

The following events help train Personalized Placements to know when it’s best to show a Promo.

Call the onItemAcquired event when players acquire a resource in-game. 

+ (void) onItemAcquired: (NSString *) transactionId itemId: (NSString *) itemId transactionContext: (NSString *) transactionContext level: (NSString *) level itemType: (NSString *) itemType amount: (float) amount balance: (float) balance acquisitionType: (UnityAnalyticsAcquisitionType) acquisitionType;

Call the onItemSpent event when players consume a resource in-game. 

+ (void) onItemSpent: (NSString *) transactionId itemId: (NSString *) itemId transactionContext: (NSString *) transactionContext level: (NSString *) level itemType: (NSString *) itemType amount: (float) amount balance: (float) balance acquisitionType: (UnityAnalyticsAcquisitionType) acquisitionType;
Parameter Data type Description Examples
transactionId NSString (Optional) A unique identifier for the specific transaction that occurred. You can use this to group multiple events into a single transaction.

Note: If the acquisitionType is premium (meaning the player purchased the commodity with real money), Unity recommends matching the transaction ID logged at the point of purchase with the one sent for onItemAcquired or onItemSpent, so the data model can easily associate the two as part of a single transaction. For more information, see documentation on purchasing integration for iOS.
  • @"00001"
  • @"12345”
itemId NSString (Required) A name or unique identifier for the spent or acquired item.
  • itemId: @"Mana Potion"
  • itemId: @"Hay Bales"
  • itemId: @"Tokens"
transactionContext NSString (Required) The channel through which the item was spent or acquired.
  • transactionContext: @"IAP Store"
  • transactionContext: @"Shop"
  • transactionContext: @"Crafting"
level NSString (Optional) The name or identifier of the player’s progression level when the item was spent or acquired. This value will be expressed differently depending on the game (for example, as a numerical level, as a title, or as progress on a map). A game with traditional player levels:

  • level: @"13"
  • level: @"72"

A game that gauges progression with titles:

  • level: @"Novice"
  • level: @"Grand Champion"

A game without player levels, that gauges progression through advancing to levels or maps:

  • level: @"Pirate Bay"
  • level: @"Elysian Fields"
itemType NSString (Optional) The category of the spent or acquired item. Unity recommends using one of the following categories for proper data modeling:

  • "Currency"
  • "Resource"
  • "Item"
  • "Other"
  • itemType: @"Currency"
  • itemType: @"Resource"
  • itemType: @"Item"
amount NSFloat (Required) The unit quantity of the spent or acquired item.
  • amount: 1.0F
  • amount: 200.0F
  • amount: 5000.0F
balance NSFloat (Optional) The player’s new (post-transaction) quantity of the spent or acquired item.
  • amount: 10.F
  • amount: 50.0F
  • amount: 120.0F
acquisitionType UnityAnalyticsAcquisitionType (Required) The UnityAnalyticsAcquisitionType can be either:

  • kUnityAnalyticsAcquisitionTypePremium indicates the item was purchased with real currency.
  • kUnityAnalyticsAcquisitionTypeSoft indicates the item was acquired with virtual currency or resources.
  • acquisitionType: kUnityAnalyticsAcquisitionTypePremium
  • acquisitionType: kUnityAnalyticsAcquisitionTypeSoft

Consider the following examples:

Use case Event(s) Example
The player acquires resources through the course of gameplay. Acquire A player loots a potion off a defeated enemy:

[UnityAnalytics onItemAcquired: @"00001" itemId: @"Health Potion" transactionContext: @"PvE Loot" level: @"Pirate Bay" itemType: @"Item" amount: 1.0F balance: 5.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];
The player acquires multiple items bundled through the course of gameplay. Acquire for each item, sharing the same transaction ID. A player receives a potion and silver pieces upon completing a quest:

[UnityAnalytics onItemAcquired: @"00002" itemId: @"Health Potion" transactionContext: @"PC Quest" level: @"Pirate Bay" itemType: @"Item" amount: 1.0F balance: 6.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];

[UnityAnalytics onItemSpent: @"00002" itemId: @"Silver" transactionContext: @"PC Quest" level: @"Pirate Bay" itemType: @"Currency" amount: 50.0F balance: 200.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];
The player acquires resources through an in-app purchase. Acquire (in the purchase handler). A player purchases a premium currency pack:

[UnityAnalytics onItemAcquired: @"00003" itemId: @"Gold Coin" transactionContext: @"Gold Vendor" level: @"Pirate Bay" itemType: @"Currency" amount: 300.0F balance: 300.0F acquisitionType: kUnityAnalyticsAcquisitionTypePremium];
The player acquires multiple items bundled through an in-app purchase. Acquire for each item (in the purchase handler), sharing the same transaction ID. A player spends real money to purchase an armor bundle:

[UnityAnalytics onItemAcquired: @"00004" itemId: @"Warlord Breastplate" transactionContext: @"Castle Armory" level: @"75" itemType: @"Item" amount: 1.0F balance: 1.0F acquisitionType: kUnityAnalyticsAcquisitionTypePremium];

A[UnityAnalytics onItemAcquired: @"00004" itemId: @"Warlord Helmet" transactionContext: @"Castle Armory" level: @"75" itemType: @"Item" amount: 1.0F balance: 1.0F acquisitionType: kUnityAnalyticsAcquisitionTypePremium];

[UnityAnalytics onItemAcquired: @"00004" itemId: @"Warlord Boots" transactionContext: @"Castle Armory" level: @"75" itemType: @"Item" amount: 1.0F balance: 1.0F acquisitionType: kUnityAnalyticsAcquisitionTypePremium];
The player consumes resources through the course of gameplay. Spend A player uses a potion in battle:

[UnityAnalytics onItemSpent: @"00005" itemId: @"Health Potion" transactionContext: @"Arena Combat" level: @"42" itemType: @"Item" amount: 1.0F balance: 5.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];
The player consumes a resource to acquire another resource. Spend and acquire, sharing the same transaction ID. A player spends silver pieces to acquire crafting resources:

[UnityAnalytics onItemSpent: @"00006" itemId: @"Silver" transactionContext: @"Bazaar Trading Post" level: @"25" itemType: @"Currency" amount: 50.0F balance: 150.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];

[UnityAnalytics onItemAcquired: @"00006" itemId: @"Arrowhead" transactionContext: @"Bazaar Trading Post" level: @"25" itemType: @"Resource" amount: 25.0F balance: 25.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];
The player spends premium currency to acquire a virtual good. Spend and acquire, sharing the same transaction ID. A player purchases a weapon with premium currency:

[UnityAnalytics onItemSpent: @"00007" itemId: @"Gold Coin" transactionContext: @"Arena Store" level: @"Grand Champion" itemType: @"Currency" amount: 300.0F balance: 0.0F acquisitionType: kUnityAnalyticsAcquisitionTypePremium];

[UnityAnalytics onItemAcquired: @"00007" itemId: @"Vorpal Blade" transactionContext: @"Arena Store" level: @"Grand Champion" itemType: @"Item" amount: 50.0F balance: 200.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];
The player consumes multiple resources to acquire a virtual good. Spend for each resource spent, and acquired. A player gives the blacksmith currency and materials to make them a weapon:

[UnityAnalytics onItemSpent: @"00008" itemId: @"Silver" transactionContext: @"Royal Blacksmith" level: @"Royal Castle" itemType: @"Currency" amount: 100.0F balance: 50.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];

[UnityAnalytics onItemSpent: @"00008" itemId: @"Iron Ore" transactionContext: @"Royal Blacksmith" level: @"Royal Castle" itemType: @"Resource" amount: 1.0F balance: 0.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];

[UnityAnalytics onItemSpent: @"00008" itemId: @"Stinging Blade Mold" transactionContext: @"Royal Blacksmith" level: @"Royal Castle" itemType: @"Resource" amount: 1.0F balance: 0.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];

[UnityAnalytics onItemAcquired: @"00008" itemId: @"Stinging Blade" transactionContext: @"Royal Blacksmith" level: @"Royal Castle" itemType: @"Item" amount: 1.0F balance: 1.0F acquisitionType: kUnityAnalyticsAcquisitionTypeSoft];

Note: Make sure you implement these events anywhere inventory transactions occur, including in your callback handler for rewarded ads.

Logging level failure

Call the onLevelFail event when players fail a level or die in-game. The data model can use this to show a Promo for a Product that will help them pass the level on the next attempt. 

+ (void) onLevelFail: (int) levelIndex;

Logging levels-up

Call the onLevelUp event when players progress or increase in power. 

+ (void) onLevelUp: (int) newLevelIndex;

See the following code sample for an example implementation: 

#import  

@interface ViewController : UIViewController 

@end 

@implementation ViewController 

// Call when a player acquires an item: 
- (void)acquireItem:(NSString *)transactionId itemId:(NSString *)itemId transactionContext:(NSString *)transactionContext level:(NSString *)level itemType:(NSString *)itemType amount:(float)amount balance:(float)balance acquisitionType:(UnityAnalyticsAcquisitionType)acquisitionType { 

    [UnityAnalytics onItemAcquired:transactionId itemId:itemId transactionContext:transactionContext level:level itemType:itemType amount:amount balance:balance acquisitionType:acquisitionType]; 

    // Add commodity to the player’s inventory. 
} 

// Call when a player consumes or sells an item: 
- (void)spentItem:(NSString *)transactionId itemId:(NSString *)itemId transactionContext:(NSString *)transactionContext level:(NSString *)level itemType:(NSString *)itemType amount:(float)amount balance:(float)balance acquisitionType:(UnityAnalyticsAcquisitionType)acquisitionType { 

    [UnityAnalytics onItemSpent:transactionId itemId:itemId transactionContext:transactionContext level:level itemType:itemType amount:amount balance:balance acquisitionType:acquisitionType]; 

    // Deduct commodity from the player’s inventory. 
} 

// Call when a player dies or fails a challenge: 
- (void)levelFail:(int)levelIndex { 

    [UnityAnalytics onLevelFail:levelIndex]; 

    // Deduct a life.  
    // Respawn the player or display the Game Over menu. 
} 

// Call when a player gains a level or similarly upgrades: 
- (void)levelUp:(int)theNewLevelIndex { 

    [UnityAnalytics onLevelFail:theNewLevelIndex]; 
    // Increase the player’s stats. 
    // Unlock new skills. 
} 
@end

Configuring Personalized Placements

Create Placements for your monetization surfacing points (as described in the pre-integration guide), or convert existing ones in your game. To create or convert a Personalized Placement, simply enable both Ads and IAP Promo content in the Content Settings menu.

Unity recommends multiple Personalized Placements in your game, to give the player a consistent experience throughout.

Converting an existing video Placement

If you already have a live Placement that you wish to convert, simply add IAP Promo offers to your rewarded or non-rewarded video Placement. To do so, navigate to the desired Placement’s settings menu, then select Content Types and check IAP Promo. Make sure you associate your Promo campaigns with your active Placements.

Activating Placements

Provide your Unity representative with the Game ID and Personalized Placement ID(s) you wish to activate in your Project.

Important: Be sure to revisit your mediation integration and update the Placement ID(s) you’re using.

Configuring IAP Promos

The final step is to configure Promos. Begin by importing the Product Catalog you created when implementing IAP to the Operate dashboard. Each Product requires an associated creative in order to be included with Promos.

Next, follow the Promo configuration wizard for each Promo you wish to include in your Personalized Placements. The setup consists of the following steps:

  1. Name the Promo.
  2. Select Products to include in the Promo.
  3. Select the Personalized Placements through which to promote the Promo.

Testing Promos

To verify that your Placements are configured to receive Promo content as well as ads, follow the testing steps detailed in the basic ads integration guide. If the Placement is configured properly, you will see a custom test ad indicating that Promos are enabled.

What's next?

View the Personalized Placements post-integration steps, to monitor performance and scale for maximum revenue.