Dependencies

• You have a working Offers integration. See Getting Started with In-Game Offers for details.

Overview

The example Offers and OfferGroups sheets in the Quick Guide use only a subset of the supported fields. This page documents the full set of fields supported by each sheet.

Offers Fields

• OfferId: The unique identifier of the Offer.

• DisplayName and Description: Human-readable name and description strings shown in the LiveOps Dashboard.

• InAppProduct: A reference into the InAppProducts sheet; specifies the SKU to use when purchasing the offer.

• Rewards: A list of MetaPlayerRewards defining the contents of the Offer.

• MaxActivations: Total limit on how many times the Offer can be activated for a player. An offer is "activated" when the containing Offer Group is activated (i.e., is shown to the player) and also the Offer-specific conditions (if any) are fulfilled. Leave empty for no limit.

• MaxPurchasesPerPlayer: Total limit on how many times the Offer can be purchased by a player. This limit applies across all purchases of the Offer, even when it appears in multiple Offer Groups. Leave empty for no limit.

• MaxPurchasesPerOfferGroup: Total limit on how many times the Offer can be purchased via a single Offer Group. This limit applies across different activations of the same Offer Group, but does not apply across different Offer Groups. Leave empty for no limit.

• MaxPurchasesPerActivation: Limit on how many times the Offer can be purchased during a single activation. The per-activation purchase count resets when the activation of the Offer Group expires. Leave empty for no limit.

• Segments: The list of Player Segments to which this Offer is shown. If this list is non-empty, the player must belong to at least one of the Segments in order to be shown the Offer. If this list is empty, the Offer does not have Segment targeting.

• PrecursorId, PrecursorConsumed, PrecursorDelay: Used for defining dependencies from other Offers. With these, you can define "chains" of Offers: Initially, StarterPack1 is offered. Later, StarterPack2 is only offered if the player purchased StarterPack1.

  The Precursor* fields are parallel lists, and each (Id, Consumed, Delay) tuple specifies a dependency on another Offer, identified by Id, of the following form:

  • The Offer Id must have been previously shown to the player...

  • ... and it either was (if Consumed is TRUE) or wasn't (if Consumed is FALSE) purchased by the player...

  • ... and at least the duration given by Delay has elapsed since it expired.

    When more than one dependency is specified, all of them must be fulfilled for the Offer to be shown.

• IsSticky: Whether the offer will remain available in the offer group if the offer's conditions become unfulfilled during the group's activation.

  • This is true by default, meaning that as long as the offer's conditions were fulfilled when the offer group became active, the offer will remain available for the duration of the containing group's activation, even if the offer-specific conditions become unfulfilled in the meantime.
  • If this is false, the offer will become unavailable if its offer-specific conditions (segments and additional dependencies) become unfulfilled while the offer is active.
  • Note that the other direction is still "non-sticky" regardless of this flag: if a previously unavailable offer's conditions become fulfilled during the offer group's activation, the offer can become available (as long as permitted by other criteria, such as activation limits).

• DeveloperOnly: When TRUE, the Offer is only shown to Developer Players. This can be used to test offers before releasing them to all players.

OfferGroups Fields

• GroupId: The unique identifier of the Group.
• DisplayName and Description: Human-readable name and description strings shown in the LiveOps Dashboard.
• Enabled: Whether the Group is enabled and activates normally according to its targeting, schedule, and other conditions.
• DeveloperOnly: When TRUE, the whole Group is only shown to Developer Players. Like the per-Offer DeveloperOnly, it lets you validate a Group live before releasing it to all players.
• Timeline.Row and Timeline.Color: For scheduled Groups, these fields make it appear on the LiveOps Timeline in the LiveOps Dashboard. See Configuring Offer Groups for the Timeline.
• Placement: The Placement id for the Group. At most one Group can be active at a time in each Placement. Other than that, the Offers feature does not impose further meaning on what a Placement means.
• Priority: When multiple Groups are available for the same Placement, the one with the lowest Priority number is selected. Think of these as ordinal numbers in a priority ordering: 1 means "1st," 2 means "2nd," etc.
• Offers: The list of Offers in this Group. Note that not all Offers are necessarily always shown when the Group is shown, in case the Offers have individual Segments and Precursor conditions.
• Segments: The list of Player Segments to which this Group is shown. If this list is non-empty, the player must belong to at least one of the Segments in order to be shown the Group. If this list is empty, the Group does not have Segment targeting. Note that individual Offers can have targeting in addition to the Group; in order for an Offer to be shown, both the Group's and the Offer's targeting must be fulfilled.
• Lifetime: How long a Group is shown until it expires, e.g., 5h for 5 hours. If omitted, the lifetime follows the calendar schedule, if any; if lifetime and schedule are both omitted, then there is no time-based expiration. Besides expiration, a Group will deactivate if all Offers in it are sold out.
• Cooldown: How long must elapse after a Group has expired until it can be shown again. Empty means no cooldown.
• A calendar schedule defining when the Group can be shown. A schedule consists of optionally recurring "occasions," i.e., spans of time when the schedule is enabled. A schedule consists of the following fields:
  • Schedule.TimeMode: Either Utc or Local. Local means the schedule obeys the player's local time.
  • Schedule.Start.Date and Schedule.Start.Time: The start date and time of the first occasion of the schedule. For example, Schedule.Start.Date could be 2021-11-04 and Schedule.Start.Time could be 15:00.
  • Schedule.Duration: How long a single occasion lasts. For example, 5h 30m, i.e., 5 hours and 30 minutes. The supported units are y, mo, d, h, m, and s for years, months, days, hours, minutes, and seconds, respectively.
  • Schedule.Recurrence: Interval between occasions. For example, 7d, i.e., weekly. If the schedule should not repeat, leave this empty. The supported units are the same as for Schedule.Duration, but here multiple units cannot be mixed.
  • Schedule.NumRepeats: For how many occasions the schedule repeats. Leave empty for no limit.
• MaxOffersActive: The number of offers within this group that can be made active for a player simultaneously. When a player would be otherwise eligible for activating a larger number of offers, the set of active offers is limited by only activating the first MaxOffersActive offers, in the order that they are declared in the Offers list. Previously omitted offers can become active within the group if offers in the active set get deactivated during the offer group activation period, for example, due to the player no longer matching the segmentation criteria of a non-sticky offer.
• IncludeSoldOutOffers: Whether to include sold-out offers when the offer group becomes active.
  • This is true by default, meaning that sold-out offers can still become active and count against the MaxOffersActive limit, even though they're not purchasable. This is likely appropriate if you intend to still display sold-out items in the UI. However, if an offer group would contain only sold-out items, it will not be activated.
  • If this is false, sold-out offers will not be included when the offer group becomes active. Note, however, that offers that become sold-out during the current activation can still remain active until the end of the activation.