By Peter Gustafson
The Ecom Interface provides two methods for ownership verification. The first is the online method.
Online Method
The online method integrates directly with the Epic Entitlement Service. It’s useful for trusted game servers or less-secure checks on client systems for simple validation.
To determine if a user owns a specific Catalog item, make a call to EOS_Ecom_QueryOwnership to get ownership information from the server. The callback receives a void pointer containing information about the user.
Make a call to EOS_Ecom_QueryOwnershipOptions using the parameters below:
| Parameter | Description |
|---|---|
ApiVersion | Set to EOS_ECOM_QUERYOFFERS_API_LATEST. |
LocalUserId | The local user Epic account ID. |
CatalogItemIds | The number of elements in EntitlementIds. |
CompletionDelegate | Called when the operation completes using a EOS_Achievements_OnQueryDefinitionsCompleteCallback signature. |
CatalogNamespace | Optional product namespace. |
EOS returns the data you requested (and your void pointer) stored in an EOS_Ecom_OnQueryOwnershipCallback structure. This structure contains an array of EOS_Ecom_EntitlementOwnership users. Items that the server doesn’t recognize are returned as not owned.
Offline Method
The second option is the offline method. It provides a signed token that the user verifies, or passes to a third-party service. When integrating with a third-party service for ownership verification, the offline method is recommended because it avoids granting the outside service access to the user’s data.
To check ownership and cache the results locally, make a call to EOS_Ecom_QueryOwnershipToken. Use the parameters below:
| Parameter | Description |
|---|---|
ApiVersion | Set to EOS_ECOM_QUERYOFFERS_API_LATEST. |
LocalUserId | The local user Epic account ID. |
CatalogItemIdCount | The quantity of Catalog items. |
CompletionDelegate | Called when the operation completes using a EOS_Achievements_OnQueryDefinitionsCompleteCallback signature. |
CatalogNamespace | Optional product namespace. |
Upon success, you will receive an EOS_Ecom_QueryOwnershipTokenCallbackInfo structure that includes a JSON Web Token (JWT) with a five-minute expiration time.
Verify the JWT with a public key and unpack it to extract the Key ID. Send the Key ID to third-party services if needed to verify the Entitlement information came from Epic Games Services (EGS).
Example
Below is an example request. Use this endpoint:
https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid}Below is the example response:
GET/ecommerceintegration/api/public/publickeys/pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g HTTP/1.1
Host: ecommerceintegration-public-service-ecomprod02.ol.epicgames.com
{
"kty": "RSA",
"e": "AQAB",
"kid": "pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g",
"n": "gcStqtD8XD9c9ifNuxXT9Xd_EEZLLCw34yxINRQPt0MxEWkoOFsuisRWGktSFtGrnUuQnp8GQY0k4Pyl_yDItWAcRtO7JUjrhQnxx3xXp_0P8xJMH1ny-RcxHF3bEJWhDzNW5PBpBjQTQZis-83499z-4OlNA7oUnDKEJkqNfzh4mMDFluPxvW_Hwpaw71nhzJI7-N-BdsPsLdqUANajLsFKq9fr06Lek_tm-6-RUxNPE3yS0x0UIsGyapA4Apcczz0xTzRDfwOkq_TyKGZiZc7vtgjkWnqdsCyXZC7dzKJvg0ggO3mKXhqZNNC_2pz24o1X_xCbG8rXtuvX8-ux-Q"
}Token Details
The Ownership Verification Token is a JWT signed using RS512 (RSA PKCS#1 signature with SHA-512, RSA key size 2048). The token contains the following claims:
| Claim | Description |
|---|---|
jti | Set to A unique identifier for this token. |
sub | The account ID that was used to request the token. |
clid | The client ID used to request the token. |
ent | An array of Entitlements that were verified for this token. If the value is empty, the account is not entitled to any of the requested Entitlements for a given sandboxId. |
iat | The token expiration. |
Below is the flow diagram:
