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 thecatalogItemId
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.
- Once the application initializes the Social Overlay, a notification window confirms you’re online.
- 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:
- Presenting Catalog Offers for purchase and enabling the user to make purchases.
- 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:
- Making the purchase.
- Verifying ownership
- 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 anEOS_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 anEOS_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.