Knowledge base

Personalized Placements guide (Unity)

Introduction to Personalized Placements

A Personalized Placement is the decision engine that ties together ads and in-app purchase (IAP) promotions, determining which format to serve based on player experience and impact to lifetime value (LTV). Each player receives the most meaningful engagements to maximize retention and revenue. Simply add IAP Promos to your rewarded or non-rewarded video ad Placements to increase their performance.

In this guide:

How it works

Personalized Placements optimize toward LTV for retention and sustainable revenue. Unity calculates the LTV of your users by projecting their total potential value over an infinite amount of time. The data model analyzes many factors to predict the LTV of monetization content relative to your user, not just the bid price. These data points include, but are not limited to, the likelihood of the player returning to the app, and the likelihood of churn, app usage, historical ad preference, genre preference, and propensity for in-app purchases.

The Personalized Placements machine learning decision engine.

The machine learning engine also benefits from being trained on all available data since the inception of the experiment. When a Personalized Placement requests content, its machine learning engine assigns an LTV score to each format, whether it’s an ad bid or IAP Promo. The format with the highest LTV score wins the impression.

Succeeding with Personalized Placements

To maximize profits with Personalized Placements, you follow a two-phase rollout process:

  1. Observation
    In the observation phase, Unity segments your users so that half receive optimized content, while the other half acts as a control group. This allows you to easily determine the optimization effects and make educated decisions about how to proceed.
  2. Scale
    When you’ve observed significant results (typically after roughly one month of data), you’ll enter the scaling phase. During this phase, Unity maximizes the number of users experiencing optimization, in order to maximize your revenue.

Because Personalized Placements work holistically to optimize your revenue, it’s important to ensure that your game’s overall economy and monetization strategy is healthy and effective to begin with. Unity’s machine learning model can dynamically adjust to your user’s preferences, to provide the best experience for each individual user. But if the underlying setup of your app or game is ineffective at driving monetization, the revenue lift will be smaller. This is especially important because the player’s journey, behavior, and creatives they experience directly impact the Personalized Placement’s valuations and choices.

This guide walks you through the path to success in three phases:

  1. Preparation
    Read the pre-integration section if you’re new to monetization design strategy and looking for guidance on implementing an effective monetization system.
  2. Implementation
    Read the integration section when you’re confident in your monetization design strategy and ready to execute on it by implementing Personalized Placements in your game.
  3. Scale for success
    Read the post-integration section when your game has been published long enough to observe and act on performance results to drive revenue higher.

If you have any more questions, contact your Unity representative or review the FAQ.

Define your monetization strategy

Before implementing Personalized Placements, it is important to clearly define your monetization strategy. If you need help getting started, Unity recommends these steps:

  1. Identify your game’s core loop.
  2. Identify surfacing points that will entice players to enhance their experience.
  3. Identify player archetypes engaging with your game, and create Promos that target them.

Define your game’s core loop

Your core loop is the fundamental sequence of activities a player follows and repeats throughout your game. These vary depending on the game and genre, but usually involve acquiring and spending resources to progress in the game. Your core loop is the mechanic that keeps players engaged with your content and incentivized to play. The steps between each activity in the core loop present the most fertile monetization opportunities.

Here is an abstract example of a core game loop:

Example of a generic core game loop.

Identify surfacing points that will entice players to enhance their experience

Natural breaks in gameplay or friction points occur between the phases of your core loop. These are surfacing points, and excellent locations to implement Placements because they present the player with choices or information without interrupting gameplay.

When identifying these opportunities, remember that similar surfacing points can occur in multiple locations, so you can use a single Placement in multiple surfacing points throughout your game. For example, you can use the same Placement anywhere a player loses a life, levels up, or defeats a boss.

You can further augment these surfacing points by implementing Standard Events that provide more context into in-game milestones of the player, which provides better data for machine learning-driven decisions (for more information, see section on Implementing Standard Events). These will ultimately be where you implement your Placements.

Common examples of surfacing points

Personalized Placements serve both ad and Promo content. Unity strongly recommends using rewarded ads in your implementation, and suggests reviewing the rewarded video best practices guide. Context is important. When considering these examples, think about what incentives make enticing rewards for each surfacing point if an ad wins the impression.

Level complete

Level transitions present a natural pause to display an ad or Promo without disrupting gameplay, and might be a good opportunity to reward or promote items that will help players with the upcoming challenge.

Level failed or player death

Failing a challenge presents both a break in gameplay and a friction point, where the player might be interested in extra lives or power-ups that improve their chances of success on the next attempt.

Example of an augmented core loop using level failure as a surfacing point.


Leveling up often results in access to increased power or resources. This may present an opportunity to entice a non-paying player with a discounted purchase offer, or the option to watch an ad in exchange for a period of double rewards.

Example of an augmented core loop using leveling up as a surfacing point.

In-game store menu

Shops are resource sinks, and therefore good opportunities for rewarded Placements offering currency in exchange for watching an ad, or Promos for currency packs.

Create Products and Promos based on player archetypes

Who plays your game?

Now that you have a strategy for surfacing ads and Promo campaigns, consider the types of players engaged with your game. This helps inform the types of in-app purchases you want to promote. Consider the following example archetypes:

  • The "completionist" player desires resources to collect and craft the best items.
  • The "pitstop" player’s most valued resource is time, and therefore wants to speed things up and eliminate waiting.
  • The "conqueror" player enjoys raiding, battling, and competition. They are typically willing to pay for power.

What do they want?

Understanding your game’s audience helps identify what products they might desire. Remember, you don’t have to worry about matching the right player with the right offer, because the machine learning will do that for you. However, it’s important to account for every play style in your player base when choosing the types of Promos you’ll run.

For example, using the archetypes listed above, you might end up with a Promo strategy that looks like this:

Player archetypes Products Promos
Completionist Focus on collectable or crafting items, and unique non-consumables such as vanity items or skins.

  • Soft currency
  • Crafting resources
  • Unique skins
  • 100 Gems ($0.99)
  • 500 Gems ($4.99)
  • 2000 Gems ($19.99)
  • 2000 Gem Starter Pack ($9.99 for non-payers only)
  • 2000 Gem Sale ($14.99 for a limited time only)
  • Crafting Pack (500 Gems, 10 Wood, 20 Nails, 1 Hammer, $9.99)
  • Crafting Starter Pack (500 Gems, 10 Wood, 20 Nails, 1 Hammer, $4.99 for non-payers only)
  • Thor’s Crafting Hammer ($9.99 for a limited time only)
Pitstop Focus on consumable items that speed up ability to progress in the game.

  • Accelerators
  • Energy refills
  • XP boosts
  • Plant Growth Stimulant ($0.99)
  • Plant Growth Stimulant x6 ($4.99)
  • Plant Growth Stimulant x25 ($19.99)
  • Plant Growth Stimulant x25 Starter Pack ($9.99 for non-payers only)
  • Plant Growth Stimulant x25 Sale ($14.99 for a limited time only)
  • Booster Pack (Double XP Boost, Double Gems Boost, Plant Growth Stimulant x5, Coffee x5, $9.99)
  • Booster Starter Pack (Double XP Boost, Double Gems Boost, Plant Growth Stimulant x5, Coffee x5, $4.99 for non-payers only)
Conqueror Focus on items that increase power, or vanity items that distinguish the player from their peers.

  • Weapons
  • Armor
  • Consumables
  • Flame Blade ($4.99)
  • Flame Tunic ($4.99)
  • Inferno Blade ($9.99)
  • Inferno Mail ($9.99)
  • Phoenix Blade ($19.99)
  • Phoenix Robe ($19.99)
  • Phoenix Set (Phoenix Blade and Phoenix Robe, $34.99)
  • Phoenix Starter Set (Phoenix Blade and Phoenix Robe, $24.99 for non-payers only)
  • Phoenix Set Sale (Phoenix Blade and Phoenix Robe, $29.99 for a limited time only)
  • Inferno War Chest (Inferno Blade, Inferno Mail, Stamina Potion x5, Strength Potion x5, $19.99)
  • Inferno Starter Pack (Inferno Blade, Inferno Mail, Stamina Potion x5, Strength Potion x5, $9.99 for non-payers only)

How you choose to organize your Promos is up to you. In this example, the Promos are organized around several campaign types:

  • Evergreen: Persistent content that is always available at a consistent price point.
  • Non-payer: Single-use discounts only available to players who have not spent money in the game.
  • Limited-time: Discounted items available to the entire player base, but only between specified dates.

Note: You can configure non-payer and limited-time offers in the final step of the IAP Promo creation process (targeting and scheduling). Unity generally discourages including discounted items in Personalized Placement Promos, as it can skew the machine-learning data towards sale items, but non-payer and limited-time offers work well because the model excludes them from consideration when the player is ineligible for those offers.

For more ideas on how to design effective Promo campaigns, see the IAP Promo monetization tips.

Back to top

Implement Personalized Placements

The next section guides you through implementation. You’ll create Placements at the surfacing points you identified, then tie your Promos to them. Don’t worry about targeting specific user segments with specific offers. As long as you’ve covered your bases by providing offers that will appeal to different players in different situations, Unity’s data model will determine which offer best resonates with each individual player.

Unity recommends multiple Personalized Placements in your game, to give the player a consistent experience throughout the game, as opposed to only occasionally receiving optimized content. Benchmarking across the industry suggests that users prefer 1 or 2 impressions per day. When choosing which Promos to associate with each Placement, consider the game event occurring, and what offers might entice players in that situation.

Implementing Personalized Placements

With your monetization strategy set, you’re ready to implement Personalized Placements in your game.

Installing Unity Ads

To ensure the latest version of Unity Ads, download it through the Asset store, or through the Unity Package Manager in the Editor. Personalized Placements require version 3.0 of the SDK or higher.

Important: You must choose either the Asset or the package. Installing both may lead to build errors.

Using the Asset package

Download the latest version of Unity Ads from the Asset store. For information on downloading and installing Asset packages, see Asset packages documentation.

Using Package Manager

Install the latest version of Unity Ads through the Unity Package Manager, by following these steps:

  1. In the Unity Editor, select Window > Package Manager to open the Package Manager.
  2. Select the Advertisements package from the list, then select the most recent verified version.
  3. Click the Install or Update button.

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 Unity Ads integration documentation.

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

Unity IAP provides the most streamlined integration with Personalized Placements. However, you may also take advantage of the feature if you use a custom purchasing integration, by implementing a purchasing adapter.

Using Unity IAP

Always use the most current Unity IAP Asset package. The IAP Promo feature requires version 1.20 or higher. For detailed setup information, see documentation on configuring Unity IAP. If you’re interested in the simplest implementation, Unity recommends taking advantage of the Codeless IAP feature.

Important: If you implement Unity Ads through a third party mediator, you will need an adaptor that allows the Unity Ads SDK to receive purchase and conversion events while in mediation. See documentation on using IAP Promo in mediation for more information.

Note that your game must initialize the Unity IAP SDK before initializing the Unity Monetization SDK for IAP Promo to work.

Using a purchasing adapter

If you use a custom IAP solution, see documentation on Custom purchase integration for guidelines on implementing a purchasing adapter. This adapter is required for Unity to hook into the necessary machine learning data.

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.

Logging acquire and spend events

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

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

public static AnalyticsResult ItemAcquired (AcquisitionType currencyType, string transactionContext, float amount, string itemId, float balance, string itemType = null, string level = null, string transactionId = null, IDictionary<string, object> eventData = null)

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

public static AnalyticsResult ItemSpent (AcquisitionType currencyType, string transactionContext, float amount, string itemId, float balance, string itemType = null, string level = null, string transactionId = null, IDictionary<string, object> eventData = null)

Parameter Data type Description Examples
currencyType AcquisitionType (Required) The AcquisitionType can be either:

  • AcquisitionType.Premium indicates the item was purchased with real currency.
  • AcquisitionType.Soft indicates the item was acquired with virtual currency or resources.
  • AcquisitionType.Premium
  • AcquisitionType.Soft
transactionContext string (Required) The context through which the item was spent or acquired.
  • "IAP Store"
  • "Shop"
  • "Crafting"
amount float (Required) The unit quantity of the spent or acquired item.
  • 1
  • 200
  • 5000
itemId string (Required) A name or unique identifier for the spent or acquired item.
  • "Mana Potion"
  • "Hay Bales"
  • "Tokens"
balance float (Optional) The player’s new (post-transaction) quantity of the spent or acquired item.
  • 10
  • 50
  • 120
itemType string (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"
  • "Currency"
  • "Resource"
  • "Item"
level string (Optional) The name or identifier of the player’s progression level when the item was spent or acquired. This value is 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:

  • "13"
  • "72"

A game that gauges progression with titles:

  • "Novice"
  • "Grand Champion"

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

  • "Pirate Bay"
  • "Elysian Fields"
transactionId string (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 acquisition type 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 ItemAcquired or ItemSpent, so the data model can easily associate the two as part of a single transaction. If you use Unity IAP, the SDK automatically logs the transaction ID, currency code, and amount for each purchase.
  • "00001"
  • "12345"
  • eventData IDictionary (Optional) A dictionary of custom parameters.

    Consider the following use cases:

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

    Analytics.ItemAcquired (AcquisitionType.Soft, "PvE Loot", 1, "Health Potion", 5, "Item", "Pirate Bay", "00001");
    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:

    Analytics.ItemAcquired (AcquisitionType.Soft, "PC Quest", 1, "Health Potion", 6, "Item", "Pirate Bay", "00002");

    Analytics.ItemAcquired (AcquisitionType.Soft, "PC Quest", 50, "Silver", 200, "Currency", "Pirate Bay", "00002");
    The player acquires resources through an in-app purchase. Acquire (in the purchase handler). A player purchases a premium currency pack:

    Analytics.ItemAcquired (AcquisitionType.Premium, "Gold Vendor", 300, "Gold Coin", 300, "Currency", "Pirate Bay", "00003");
    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:

    Analytics.ItemAcquired (AcquisitionType.Premium, "Castle Armory", 1, "Warlord Breastplate", 1, "Item", "75", "00004");

    Analytics.ItemAcquired (AcquisitionType.Premium, "Castle Armory", 1, "Warlord Helmet", 1, "Item", "75", "00004");

    Analytics.ItemAcquired (AcquisitionType.Premium, "Castle Armory", 1, "Warlord Boots", 1, "Item", "75", "00004");
    The player consumes resources through the course of gameplay. Spend A player uses a potion in battle:

    Analytics.ItemSpent (AcquisitionType.Soft, "Arena Combat", 1, "Health Potion", 5, "Item", "42", "00005");
    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:

    Analytics.ItemSpent (AcquisitionType.Soft, "Bazaar Trading Post", 50, "Silver", 150, "Currency", "25", "00006");

    Analytics.ItemAcquired (AcquisitionType.Soft, "Bazaar Trading Post", 25, "Arrowhead", 25, "Resource", "25", "00006",);
    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:

    Analytics.ItemSpent (AcquisitionType.Premium, "Arena Store", 300, "Gold Coin", 0, "Currency", "Grand Champion", "00007");

    Analytics.ItemAcquired (AcquisitionType.Soft, "Arena Store", 1, "Vorpal Blade", 1, "Item", "Grand Champion", "00007",);
    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:

    Analytics.ItemSpent (AcquisitionType.Soft, "Royal Blacksmith", 100, "Silver", 50, "Currency", "Royal Castle", "00008");

    Analytics.ItemSpent (AcquisitionType.Soft, "Royal Blacksmith", 1, "Iron Ore", 0, "Resource", "Royal Castle", "00008");

    Analytics.ItemSpent (AcquisitionType.Soft, "Royal Blacksmith", 1, "Stinging Blade Mold", 0, "Resource", "Royal Castle", "00008");

    Analytics.ItemAcquired (AcquisitionType.Soft, "Royal Blacksmith", 1, "Stinging Blade", 1, "Item", "Royal Castle", "00008",);

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

    Logging level failure

    Call the LevelFail 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.

    public static AnalyticsResult LevelFail (string name, IDictionary<string, object> eventData = null)

    Parameter Data type Description Examples
    name string (Required) Either the name of the failed level, or its index.
    • "Pirate Bay"
    • "4"
    eventData IDictionary (Optional) A dictionary of custom parameters.

    Logging level-ups

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

    public static AnalyticsResult LevelUp (string name, IDictionary<string, object> eventData = null)

    Parameter Data type Description Examples
    name string (Required) The new rank or level name.
    • "99"
    • "Grand Champion"
    eventData IDictionary (Optional) A dictionary of custom parameters.

    See the following code sample for an example implementation:

    using UnityEngine.Analytics; 
     public class GameEconomyEventManager : Monobehaviour { 
       // Call when a player acquires an item: 
       public void AcquireItem(AcquisitionType currencyType, string transactionContext, float amount, string itemId) { 
         Analytics.ItemAcquired(currencyType, transactionContext, amount, itemId);
         // Add commodity to the player’s inventory. 
       // Call when a player consumes or sells an item: 
       public void ConsumeItem(AcquisitionType currencyType, string transactionContext, float amount, string itemId) { 
         Analytics.ItemSpent(currencyType, transactionContext, amount, itemId);
         // Deduct commodity from the player’s inventory. 
       // Call when the player dies or fails a challenge: 
       public void FailMission(string missionName) { 
         // Deduct a life. 
         // Respawn the player or display the Game Over menu. 
       // Call when the player gains a level or similarly upgrades: 
       public void IncreaseLevel(string levelValue) { 
         // Increase the player’s stats. 
         // Unlock new skills. 

    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:

    • Name the Promo.
    • Select Products to include in the Promo.
    • 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 ads integration guide. If the Placement is configured properly, you will see a custom test ad indicating that Promos are enabled.

    Back to top

    Scaling to maximize value

    As every game is unique, Unity strives to ensure that you’re comfortable with the performance of Personalized Placements in your game before optimizing the experience of your entire player base. This rollout consists of two phases: observation and scaling.

    LTV reporting

    When your Personalized Placements are live, Unity monitors phase one performance and enables an LTV Reporting tab on the Operate dashboard when statistically significant data is available. The report will appear on the left navigation bar of your Organization-level menu.

    This report lets you view how Personalized Placements impact your revenue and retention. It includes analytics for eCPM lift, revenue lift, and average revenue per daily active user (ARPDAU).

    LTV reporting data in the Developer Dashboard.

    Note: During the beta period, the LTV reporting period defaults to performance over the past 30 days, which allows for statistically significant results.

    What to expect in the observation phase

    • Unity randomly assigns half of your users to an exposed group, while the other half constitutes a control group. The exposed users will experience content optimization, while the control group will not, to clearly demonstrate the difference in performance.
    • As Unity collects data on the preferences of every user in the Unity network (even those who have just entered your game), you will generally see an immediate impact to your game.
    • The observation phase typically lasts about a month, to generate statistically significant results. During this period, you will likely see a revenue impact within the first week of Placement conversion. However, to ensure solid data-driven decisions, Unity refrains from scaling optimized content to all users until the significance of that impact is clear.

      Note: The number of active Personalized Placements, size of your game, and complexity of its economy will heavily influence the actual length of the observation period. Unity recommends personalizing as many of your Placements as possible to improve the data sampling.

    What to expect in the scaling phase

    • Once you’ve accrued sufficient data, Unity adjusts the distribution of users to 90% exposed and 10% control. This allows Unity to maximize your revenue and still demonstrate the effect of optimization on your users.
    • After this change, your revenue lift will be projected by normalizing the data of both groups, so Unity can compare the results from two differently-sized experiment populations correctly.

    During the beta, your account manager will work closely with you to handle the transition between phases. Your dashboards will change automatically, adjusting to the new optimization settings.

    Note: If you use ads mediation, Unity is working to allow your mediation platform (e.g. Admob and Mopub) to correctly utilize the additional revenue you receive from our optimization in their autoranking of your meditation waterfall. This will be available in the near future, and allow you to correctly rank Unity against other monetization partners automatically.

    Back to top

    Still need help? Get in touch!
    Last updated on 18th Jan 2020