Entitlements and Store

Module PulseOnlineCommerce (UPulseOnlineCommerceSubsystem, one per game instance) answers “does the player own this DLC?”, reads store offers with prices and buys offers through the platform store. It works for the first local user.

Backend Entitlements Offers and purchases
OSS IOnlinePurchase receipts (EOS: Ecom entitlements and ownership), else IOnlineEntitlements IOnlineStoreV2, checkout through IOnlinePurchase (EOS overlay)
OSSv2 (add-on PulseOnlineOSSv2) ICommerce entitlements ICommerce offers and checkout
Mock Per mock user, GrantMockEntitlement or the cheat PulseOnlineMockGrant Sample offers MOCK_DLC_ISLANDS and MOCK_COINS_500, SetMockOffer

Products

Game code should not know platform ids. Describe what the game sells as products in Project Settings > Pulse > Online Commerce (Products):

Field Meaning
Tag Tag the game uses, e.g. Game.DLC.Islands.
ItemIds Item ids that grant the product, for every platform (EOS catalog item id, Steam DLC id, …). Owning any of them counts.
OfferIds Offers that sell it, per platform. A purchase uses the first one the store knows.
bConsumable Currency packs and other consumables: GetProductQuantity sums the quantities.
UPulseOnlineCommerceSubsystem* Commerce = UPulseOnlineCommerceSubsystem::Get(this);
if (Commerce->IsProductOwned(TAG_Game_DLC_Islands))
{
	UnlockIslandPack();
}
Commerce->OnEntitlementsChangedNative.AddUObject(this, &UMyDlcManager::RefreshUnlocks);

Entitlements

After the first local user logged in online, the subsystem reads the entitlements (Query Entitlements On Login) and again after every purchase. IsProductOwned, GetProductQuantity, IsItemOwned and GetEntitlements answer from that cache; HasEntitlements says whether it was read since the last login. Redeemed and expired entitlements do not count. Logging out clears the cache.

FPulseOnlineEntitlement has the entitlement id, the item id, a name, the quantity, bRedeemed and the expiry date.

Offers and purchases

Commerce->QueryOffers({});                     // offers of the products (all offers without products)
FPulseOnlineOffer Offer;
if (Commerce->GetProductOffer(TAG_Game_DLC_Islands, Offer))
{
	PriceLabel->SetText(Offer.PriceText);       // "4,99 €"; Offer.IsDiscounted() and RegularPriceText for sales
}

UPulseOnlinePurchaseRequest* Purchase = Commerce->PurchaseProduct(TAG_Game_DLC_Islands);
Commerce->OnPurchaseFinishedNative.AddUObject(this, &UMyStoreWidget::HandlePurchase);

The purchase opens the store overlay of the platform; the request has no timeout, the player may take their time. It finishes with:

  • success: Receipt (transaction id, granted entitlements if the store says), the entitlements are read again (Refresh Entitlements After Purchase), message Pulse.Message.Online.Commerce.Purchased;
  • failure with bCancelled: the player closed the overlay; show nothing;
  • other failures: GetErrorText() (unknown offer, not allowed to buy, store error).

Prices: PriceText / RegularPriceText are formatted by the store; Price / RegularPrice are in the smallest unit of the currency with PriceDecimals (Pulse::Online::Commerce::FormatPrice formats them when a store gives no text).

Requests

Request Inputs Result
UPulseOnlineQueryEntitlementsRequest UserId (empty: first local user) Entitlements
UPulseOnlineQueryOffersRequest OfferIds (empty: products, else all) Offers
UPulseOnlinePurchaseRequest Items (offer id + quantity) Receipt, bCancelled

They run in the queue Commerce (see Requests); use Create Pulse Online Request in Blueprint.

Messages

Channel Payload
Pulse.Message.Online.Commerce.EntitlementsChanged FPulseOnlineCommerceMessage (user, entitlement count)
Pulse.Message.Online.Commerce.Purchased FPulseOnlineCommerceMessage (user, items, transaction id)

EOS

  • The EOS OSS reads ownership through Ecom (IOnlinePurchase receipts: entitlements plus ownership of items granted by other services). The item id of an entitlement is the catalog item id of the EOS developer portal; put it into ItemIds of the product.
  • Offers and checkout need offers in the Epic Games Store catalog of the product; checkout shows the EOS overlay.
  • With bUseNewEcomFlow in the EOS settings, the OSS also offers IOnlineEntitlements; Pulse Online still prefers the receipts.
  • Clients report what they own; a dedicated server cannot check a client’s entitlements through the OSS. Do not grant server-side rewards only because a client says it owns a DLC.

Mock backend

Two sample offers exist after every reset: MOCK_DLC_ISLANDS (grants item MOCK_DLC_ISLANDS, 4.99 instead of 9.99 EUR) and MOCK_COINS_500 (grants item MOCK_COINS). A checkout grants the items right away. FailNextOperation knows Entitlements, Offers and Checkout; with the error id Pulse.Online.Cancelled a checkout counts as cancelled.

Cheats

PulseOnlineEntitlements, PulseOnlineOffers [OfferId,OfferId], PulseOnlinePurchase <OfferId|ProductTag> [Quantity], PulseOnlineOwns <ProductTag|ItemId>, PulseOnlineMockGrant <ItemId> [Quantity] (see Debugging).


This site uses Just the Docs, a documentation theme for Jekyll.