Ecom Interface

Interface to handle purchases and verification of ownership

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.

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.