Ecom Interface

By Peter Gustafson

Overview
The Epic Game Store is where games are purchased. For example, let’s say you purchase the Super Deluxe (SD) edition of a game. Below are descriptions and access limitations of your purchase.

Action	Description	Access
You buy the SD edition	An entitlementId is created in your account to manage your access permissions.	You have access to specific Audiences and levels.
AudienceId created	The AudienceId identifies the authorized audiences and your level of ownership.	Users with an authorized AudienceId can access your game. Make a call to the Ownership API to query all users with access to your AudienceId.
ArtifactId created	The ArtifactId is created in your account.	The ArtifactId identifies your purchase of the SD edition.

Warning: purchasing related functionality in the Ecom Interface will fail.

Ownership vs. Entitlements

Below are descriptions how Ownership and Entitlements work in the Epic Game Store.

Entitlements

• An Entitlement record is a unique identification number for each user.
• For consumable purchases, each transaction is assigned an entitlementId.
• Three games purchased means three entitlement ID numbers are created.
• Entitlement API queries return users who have purchased your game.

Ownership

The Ownership API is used for durable items. It returns the Epic users with access to your content and the offer they purchased.

Redeeming Consumables

Your game’s backend makes a call to Epic’s backend or the game client passes an entitlement token to the game’s backend. Here’s how it goes:

• You award the user with in-game items and mark the entitlements as redeemed. This step requires relating an outstanding entitlementName or the catalogItemId field which should be the same.
• These fields represent the immutable offer or item of the entitlement. The game’s backend stores a table which maps a particular catalogItemId to a specific set of in-game inventory.

Example

Catalog items for redemption are managed using the backend services. As an example use case, let’s say catalogItemId X is a 100 coins offer. But catalogItemId Y is a 500 coins offer. In this example, the game’s backend makes a call using either the SDK API or through RESTful service.

Upon the successful redemption, you add the appropriate in-game inventory items to the user’s account with the following parameters:

Parameter	Description
consumable	All consumable values are true regardless of the redemption state.
status	Changes from active pre-redemption to redeemed post-redemption.
active	The pre-redemption value is true; post-redemption is false.

Catalog Configuration

The catalog configuration is performed by the EGS Service Delivery team. Contact your Service Delivery team to set-up offers, audiences, and catalog items.

Testing

The Service Delivery team will create codes that grant redeemers a single DevAudience with access to all content for developers. Service Delivery can provide QA codes that have the base game and individual add-on content broken out to individual codes. This allows test teams to validate the process of starting from the base game and adding content individually.

Without EAS set to active, you can initialize the EOS SDK and the Ecom Interface, but all Ecom Interface function calls to the back-end service will fail. Below are common use cases working with the Ecom Interface:

• Make purchase offers
• Completing purchase transactions
• Verify ownership and redeem purchases

Access

To access the Ecom Interface you must get an EOS_HEcom handle through the Platform Interface function EOS_Platform_GetEcomInterface. All Ecom Interface functions require this handle as their first parameter.

Next, confirm the EOS_HPlatform handle is ticking to receive callbacks.

Social Overlay

The Social Overlay is an Epic Online Services (EOS) UI. It serves up Friends lists for in-game management and player presence. Find the Social Overlay using Shift+F3 on your keyboard.

Game management allows players to invite friends to their game session or to join friends who are already in a game session. Player presence provides details about their online state, active game, and any game-defined text.

The EOS SDK loads and initializes the Social Overlay, and then the user requests the latest Social Overlay version deployed to our Content Delivery Network (CDN). The EOS SDK and Social Overlay communicate via a bridge.

Initialization

When you open the Social Overlay for the first time, it displays your Friends List.

1. Once the application initializes the Social Overlay, a notification window confirms you’re online.
2. Press the hotkey combination to open the Social Overlay.

During initialization, the EOS SDK updates the Social Overlay which features you have enabled or disabled.

Localization

The Social Overlay supports the following locales:

Locale Code	Language
ar	Arabic
de	German
es-ES	Spanish (Spain)
es-MX	Spanish (Mexico)
fr	French
it	Italian
ja	Japanese
ko	Korean
pl	Polish
pt-BR	Portrugese (Brazil)
ru	Russian
th	Thai
tr	Turkish
zh-Hans	Chinese (Simplified)
zh-Hant	Chinese (Traditional)

Integration

Below are the Social Overlay tools and their uses:

Tool	Use
Presence	Tracks users online state and updates their status.
ProductName	Identifies the game the users are playing.
Rich presence text	Displays a friend’s status.
Lobbies	The game uses EOS_Lobby_AddNotifyJoinLobbyAccepted to update you about users that have joined your lobby. It uses the UiEventId to retrieve the lobby information using EOS_Lobby_CopyLobbyDetailsHandleByUiEventId.
Sessions matchmaking	The Social Overlay transmits an invite through the Sessions Interface on behalf of the user and the game using EOS_Sessions_SendInvite. The game uses EOS_Sessions_AddNotifySessionInviteAccepted to manage the status of users. The game must use the provided UiEventId to retrieve a session by using EOS_Session_CopySessionHandleByUiEventId.
Custom service	Set-up a player manually by using EOS_PresenceModification_SetJoinInfo
Invite button	The lifetime of an invite is tied to the session, not the user who sent the invite. The invite expires when the session is over. The Invite button isn’t available if the current session is full.
Lobbies	When the Invite button is clicked, the Social Overlay transmits an invite through the Lobbies Service on behalf of the user and the game using EOS_Lobby_SendInvite. The game uses EOS_Lobby_AddNotifyLobbyInviteAccepted to identify players in the Social Overlay. The callback data contains the Invite ID, which you can use to locate the information about the game within the Lobbies Interface.

In-Game Store

An in-game store provides two functions:

1. Presenting Catalog Offers for purchase and enabling the user to make purchases.
2. The EOS SDK provides functionality to retrieve lists of offers from the store’s catalog.

The checkout process pushes the data to the EGS Overlay to finalize the purchase. EOS notifies the game of the transaction and provides a transaction handle.

Catalog Offer Data

Catalog Offers EOS_Ecom_CatalogOffer are localized pricing information based on the user who is browsing the store. Price localization includes applied discounts and currency conversions. A localized price will include a currency code, such as USD (US dollars).

For example, an offer that costs 2.99 in US dollars has a value of 299.

Catalog Offer Lists

Retrieve the list of Catalog Offers defined in the Developer Portal by making a call to the EOS_Ecom_QueryOffers function. This function takes an EOS_Ecom_QueryOffersOptions data structure and returns type EOS_Ecom_QueryOffersCallbackInfo. Use the following parameters:

Parameter	Description
ApiVersion	Set to EOS_ECOM_QUERYOFFERS_API_LATEST.
LocalUserId	The local user Epic account ID.
OverrideCatalogNamespace	Optional product namespace.

• If the ResultCode in the EOS_Ecom_QueryOffersCallbackInfo that the delegate receives is successful, the offer data you requested is available in a cache.
• Use EOS_Ecom_GetOfferCount to find the number of offers stored in the cache.
• Use EOS_Ecom_CopyOfferByIndex to get a copy of an individual offer.
• Each Item within the offer contains data about images and release details associated with the item.
• Release the offer by using EOS_Ecom_CatalogOffer_Release.

Display Individual Item Data

Below are data parameters and how to use them.

Property	Use
EOS_Ecom_GetOfferItemCount	Retrieves offer count. After retrieving an offer from the cache, make a call to EOS_Ecom_GetOfferItemCount.
EOS_Ecom_CopyOfferItemByIndex	Provides a copy of an individual EOS_Ecom_CatalogItem. This structure contains localized text and the ID of the Entitlement.
EOS_Ecom_GetItemImageInfoCount	Returns the quantity of images.
EOS_Ecom_KeyImageInfo	Retrieves the image URL and dimensions.
EOS_Ecom_GetItemReleaseCount	Gets the release details for an item in your cache.
EOS_Ecom_CopyItemReleaseByIndex	Used to return an individual piece of data.
EOS_Ecom_CatalogRelease_Release	Releases the data once no longer needed.

Store Purchases

Three actions are involved in buying from the store:

1. Making the purchase.
2. Verifying ownership
3. Redeeming Entitlements (optional)

When a user makes a purchase, you make a call to EOS_Ecom_Checkout with an EOS_Ecom_CheckoutOptions structure. Below are the parameters to use in your call:

Parameter	Description
ApiVersion	Set to EOS_ECOM_QUERYOFFERS_API_LATEST.
LocalUserId	The local user Epic account ID.
EOS_EpicAccountId	The local user making the purchase.
OverrideCatalogNamespace	If not available, the current SandboxId is supplied as the catalog namespace.
EntryCount	The number of EOS_EcomCheckoutEntry elements supplied to the structure in the Entries parameter.
Entries	An array of EOS_Ecom_CheckoutEntry elements containing the EOS_Ecom_CatalogOfferId data for the purchase.

After making the call, EOS generates a purchase token.

• EOS uses the purchase token to open its own overlay for the user to review the purchase, select payment options, and confirm or cancel the transaction.
• When the overlay closes, the EOS_Ecom_CheckoutCallbackInfo will run with an EOS_Ecom_CheckoutCallbackInfo parameter detailing the transaction.
• Within the callback information, the TransactionId will be non-null if the transaction succeeded, and null if it failed or was canceled.
• If any additional calls to EOS_Ecom_Checkout are made before the callback, it will return an EOS_AlreadyPending error.

Accessing Purchase Data

Below are the properties to access the purchase data.

Property	Use
EOS_Ecom_CopyTransactionById	If you have a valid transaction ID following a successful user purchase, pass it to the EOS_Ecom_CopyTransactionById function to receive an EOS_Ecom_HTransaction.
EOS_Ecom_Transaction_GetEntitlementsCount	Returns the quantity of the Entitlements in the transaction.
EOS_Ecom_Entitlement_Release	Releases the data.

Fulfilling Purchases

After making a purchase, the user’s Epic account is assigned an Entitlement. Some users may not see the notification in the developer portal.

In some cases, fulfilling a purchase can be as simple as checking if the user owns a specific Entitlement. In these cases, verifying ownership through the EOS SDK is sufficient. In other cases, such as purchases involving consumable items or game currency, you may need to fulfill the order in-game or with a third-party backend service by redeeming the Entitlement.

Enumerating Entitlements

To retrieve a user’s Entitlements, call the EOS_Ecom_QueryEntitlements function with an EOS_Ecom_QueryEntitlementsOptions using the parameters below:

Parameter	Description
ApiVersion	Set to EOS_ECOM_QUERYOFFERS_API_LATEST.
LocalUserId	The local user Epic account ID.
EntitlementNames	An array of Entitlement names.
EntitlementNameCount	The quantity of Entitlement names included in the EntitlementNames property. Accepts up to a maximum of EOS_ECOM_QUERYENTITLEMENTS_MAX_ENTITLEMENT_IDS. If 0 is provided, your request returns all Entitlements associated with the user account.
bIncludeRedeemed	If true, the user’s redeemed Entitlements is returned.
EOS_Ecom_GetEntitlementsCount (optional)	Returns the quantity of Entitlements in cache.
EOS_Ecom_CopyEntitlementByIndex (optional)	Retrieves a copy of an individual element.

When the operation completes, EOS caches the resulting information and invokes your callback function. If the ResultCode returns EOS_Success, the cache contains the data you requested.

Redeeming an Entitlement

After fulfilling an Entitlement, make a call to EOS_Ecom_RedeemEntitlements with an EOS_Ecom_RedeemEntitlementsOptions structure. Below are the parameters:

Parameter	Description
ApiVersion	Set to EOS_ECOM_QUERYOFFERS_API_LATEST.
LocalUserId	The local user Epic account ID.
EntitlementIdCount	The number of elements in the EntitlementIds.
EntitlementIds	The Entitlements identification numbers.

Your EOS_Ecom_OnRedeemEntitlementsCallback callback returns an EOS_Ecom_RedeemEntitlementsCallbackInfo structure.

After redeeming an Entitlement, it will no longer display in the results from EOS_Ecom_QueryEntitlements calls unless the EOS_Ecom_QueryEntitlementsOptions parameter has its bIncludeRedeemed set to true.

Edits based on Ecom PDF
Jeff White will send me Swagger docs to add call and response code
Delete offline and online methods replace with calls and responses
Focus more on REST for entitlements
Add ownership vs entitlements calls
Query offers needs rest stuff
Don’t mention club API

If you are offline the SDK won’t work. Here’s some recommendations to handle offline scenarios

Delete

Connect Interface doesn’t sign you into US connect. It doesn’t talk to Epic accounts.

Game services is the agnostic backend.

You don’t need to use Epic account services if you want to use EOS.

Add client policy stuff in EOS explained to Developer Portal.

Add features to game services as agnostic, not tied to the Epic Store

SDKs are higher level so edit as a broad topic

EOS Game Services vs Epic Account Services is Epic Online Services — Jeff will check if this is true.

Auth vs Connect table to digest the two pieces of Auth or Connect for use cases that are explicit to developers; then link out to individual docs for support. Game Services can use any authentication. Or you can use EOS backend but keep using any authentication provider.

Here’s both, use whichever applies to you (Game Services vs EOS).

Jason Ji is the keeper of the Swagger docs.