The Ecom Interface gives developers using Epic Online Services (EOS) the ability to support in-game purchases through the Epic Games Store (EGS). With this interface, you can manage products ranging from full games and downloadable content (DLC) to virtual goods and in-game currency. This includes making offers, completing purchase transactions, verifying ownership, and redeeming purchased items.
See the Ecom Web APIs documentation for using Web APIs with the Ecom Interface.
To access the Ecom Interface, acquire an
EOS_HEcom handle through the Platform Interface function,
EOS_Platform_GetEcomInterface. All Ecom Interface functions require this handle as their first parameter. You must ensure that the
EOS_HPlatform handle is ticking in order for callbacks to trigger when requests are completed.
To use the Ecom Interface, your product must have Epic Account Services (EAS) active, and must obtain player/user consent to access Basic Profile data. You can activate EAS on the Developer Portal, or learn more in Epic's documentation. Without EAS and player consent, you will still be able to initialize the EOS SDK and the Ecom Interface, but all Ecom Interface function calls to the back-end service will fail.
Operating an In-Game Store
An in-game store under EOS operates by carrying out two functions: presenting Catalog Offers (sometimes called "Offers") from the store to the player for purchase, and enabling the player to make purchases. The EOS SDK provides functionality to retrieve lists of offers from the store's catalog for display in whatever way the game developer desires. Offer data includes one or more items that the player will gain, as well as key images and release details that you can use to present information about the offer to the player.
Once the player chooses to make a purchase, the checkout process pushes the data to the EGS Overlay, which finalizes the purchasing process. EOS will then notify the game of the result of the transaction, providing a transaction handle so that the game can carry out fulfillment in the event that the purchase was completed successfully.
Purchase related functionality of the Ecom interface is disabled if the
EOS_PF_DISABLE_OVERLAY flag is set.
Catalog Offer Data
Catalog Offers (type
EOS_Ecom_CatalogOffer) contain localized pricing information and descriptive text, based on the player browsing the store. Price localization includes applying discounts and converting to the local currency. A localized price will include a currency code, such as "USD" (to represent US dollars), and is represented in the smallest possible unit of that currency. For example, an Offer that costs 2.99 US dollars would correspond to the value 299.
Presenting the Store's Catalog
You can retrieve the list of Catalog Offers defined in the Developer Portal by calling the
EOS_Ecom_QueryOffers function. This function takes an
EOS_Ecom_QueryOffersOptions data structure and will call your delegate, of type
EOS_Ecom_QueryOffersCallbackInfo, upon completion. Initialize your
EOS_Ecom_QueryOffersOptions structure as follows:
|Optional product namespace, if not the one specified during initialization|
ResultCode in the
EOS_Ecom_QueryOffersCallbackInfo that the delegate receives indicates success, the Offer data you requested is available in a temporary cache. Use
EOS_Ecom_GetOfferCount to determine the number of Offers stored in the cache, and
EOS_Ecom_CopyOfferByIndex to get a copy of an individual Offer (of type
EOS_Ecom_CatalogOffer) from it. Each Item within the Offer contains data about images and release details associated with that Item, which you can pull out separately. When you no longer need your copy of an Offer, use
EOS_Ecom_CatalogOffer_Release to release it.
Displaying Individual Item Data
After retrieving an Offer from the cache, you can call
EOS_Ecom_GetOfferItemCount to determine how many Items that Offer includes, and then use
EOS_Ecom_CopyOfferItemByIndex to retrieve a copy of an individual
EOS_Ecom_CatalogItem. This structure contains additional localized text as well as the ID of the Entitlement that it will provide upon purchase. To release the memory allocated to your copy of the data, call
Images associated with Items are also available in the cache; you can call
EOS_Ecom_GetItemImageInfoCount to determine how many images are associated with a given Item, and then use
EOS_Ecom_CopyItemImageInfoByIndex to obtain an
EOS_Ecom_KeyImageInfo for the image's URL, dimensions, and intended usage. When you no longer need your copy of this data, use
EOS_Ecom_KeyImageInfo_Release to free the memory it used.
To retrieve release details for an Item from the cache, first use
EOS_Ecom_GetItemReleaseCount to discover the number of data entries present. You can then use
EOS_Ecom_CopyItemReleaseByIndex to get an individual piece of data (of type
EOS_Ecom_CatalogRelease_Release to release this data when you no longer need it.
Buying from the Store
When a player buys something from the store, that player is accepting a Catalog Offer. Once the purchase is complete, the player will own the Item (or Items) contained within the Offer, each of which adds one or more Entitlements to the buyer's player account.
There are three actions involved in buying from the store: Making the purchase, verifying ownership, and (optionally) redeeming Entitlements.
When a player decides to make a purchase, call
EOS_Ecom_Checkout with an
EOS_Ecom_CheckoutOptions structure. Initialize the structure as follows:
|If not provided, the current |
|The number of |
|An array of |
After making this call, EOS will use this information to generate a purchase token. EOS will then use this purchase token to open its own overlay, enabling the player to review the purchase, select payment options, and confirm or cancel the transaction. When the overlay closes, whether by succeeding, failing, or being canceled by the player, your callback (of type
EOS_Ecom_OnCheckoutCallback) 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 first returns via the callback then it will give an
Accessing Completed Purchase Data
If you have a valid transaction ID following a successful player purchase, you can pass it to the
EOS_Ecom_CopyTransactionById function to receive an
EOS_Ecom_Transaction_GetEntitlementsCount returns the number of Entitlements associated with the transaction, and
EOS_Ecom_Transaction_CopyEntitlementByIndex will retrieve an individual Entitlement. Call
EOS_Ecom_Entitlement_Release to release this data when you no longer need it.
Entitlements associated with transaction IDs contain the same data as those obtained through the
EOS_Ecom_QueryEntitlement function, but are subject to a different caching policy. Because of this difference, Entitlements that you acquire using a transaction ID following a purchase will remain in a transaction-specific cache until you explicitly call
Verifying ownership within the game client is not recommended and may be bypassed by players using software cheats. If possible, verify ownership on a trusted server using the Ecom Web APIs.