Managing entitlements
Overview
The AccelByte Gaming Services (AGS) Entitlements service manages individual player ownership of items that they have purchased or otherwise received. You can use Entitlements to grant or revoke instances of items to or from players. Item creation and configuration is handled in Stores.
There are two types of entitlement:
- Durable entitlements: are non-stackable and permanent. They do not disappear after use. Examples of durable entitlements include, game skins, weapons, unlockable characters, and many other possibilities.
- Consumables: disappear after use. Consumables can be stackable or non-stackable; multiple stackable items will be under the same entitlement whereas multiple non-stackable items will each have their own entitlement, even if they result from identical items. Examples of consumable entitlements include: ammo, potions, and food.
Entitlement management lets you see the entitlement history of a particular player, or the player who owns a particular entitlement.
Goals
The goals of this section are to explain how to:
- Grant an Entitlement to a Player
- Search for a Player's Entitlements
- Disable a Player's Entitlement
- Enable a Player's Entitlement
- Revoke a Player's Entitlement
- List a Player's Entitlement History
Prerequisites
- Access to the AccelByte Admin Portal
- You have created the appropriate Namespaces
Grant an Entitlement to a Player
You can grant an entitlement to a player through the AccelByte Admin Portal. To do so, follow the steps below:
In the Admin Portal, click the E-Commerce section and click Entitlements from the available options.
Next, in the Entitlements page, click the Grant Item button.
The Grant Item form will open.
Fill in the required fields:
- In the Add Item field, search for the item you want to grant to a player.
- Input the User ID of the player that you want to grant an entitlement to, in the Select User field. Then, click Add.
- Input the Quantity of the item you want to grant to the player.
Once you have completed all the fields, click the Grant button. The new entitlement will be granted to the player and will appear in the player's account.
Search for a Player's Entitlements
You can retrieve the list of the player's entitlements through the AccelByte Admin Portal. To do so, follow the steps below:
In the Admin Portal, click the E-Commerce section and click Entitlements from the options underneath.
In the Search field of the Entitlements panel, choose to search by Full Entitlement ID, User ID, or Email.
Search by Full entitlement ID will show the specific entitlement based on the entitlement ID which will display the user ID of the owning player
Input the search words, for example, for Email you would input the player's email address.
If you choose User ID or Email as a filter, you can also filter the result based on the Entitlement Class and Features Name.
noteThe Entitlement option in the Entitlement Class field gives you the option to choose an item type other than App, Code, Subscription, Media, or Option Box. To read more about item types, see the E-Commerce documentation.
Entitlement Class: filters results based on their item type. You can choose All, App, Entitlement, Code, Subscription, Media, Option Box, and Loot Box.
Use Features Name to filter results based on their features. You can enter multiple feature names by pressing Enter then adding another feature.
noteTo read more about adding feature names, including adding a feature to an item, see Set up a Store.
When you're done, click the Apply Filter button.
Disable a Player's Entitlement
You can disable a player's entitlement through the AccelByte Admin Portal. To do so, follow the steps below:
From the Admin Portal, click the E-Commerce section and click Entitlements from the options underneath.
In the Entitlements panel, search for the record you want to disable.
In the selected record, click the More Actions (...) icon under the Action column, then click Disable.
The Disable Entitlement form will open. Click Confirm.
The Status of the item will be changed to Inactive in the Admin Portal, and the item will be hidden from the player and unusable by them.
Enable a Player's Entitlement
You can enable a player's entitlement through the AccelByte Admin Portal. To do so, follow the steps below:
From the Admin Portal, click the E-Commerce section and click Entitlements from the options underneath.
In the Entitlements panel, search for the record you want to enable.
In the selected record, click the More Actions (...) icon under the Action column, then click Enable.
The Enable Entitlement form will open. Click Confirm.
The Status of the item will be changed to Active in the Admin Portal and the item will be again usable by the player.
Revoke a Player's Entitlement
You can revoke a player's entitlement through the AccelByte Admin Portal. To do so, follow the steps below:
Open the AccelByte Admin Portal, go to the E-Commerce section, and click Entitlements from the available options.
In the Entitlements panel, search for the entitlements for that player as described above.
In the selected record, click the More Actions (...) icon under the Action row, and then click Revoke.
The Revoke Entitlement form appears. Click Confirm.
In the Admin Portal, the Status of the item will be changed to Revoked and the item will be removed from the player's account.
List a Player's Entitlement History
Entitlement history is a list of the historical status of an entitlement. For example , it was initially granted and later revoked. You can see the history of a player's entitlements through the AccelByte Admin Portal. To do so, follow the steps below:
In the AccelByte Admin Portal, click the E-Commerce section and click Entitlements from the options underneath.
In the Search field of the Entitlements panel, search for the player's entitlement (refer to the Grant an Entitlement to a Player section).
Choose the record you want to view from the list of entitlements by clicking View.
The Entitlement History pop-up displays the entitlement history in descending order.
Implement Entitlements with the Client SDKs
An entitlement is granted automatically when a player places an order for an item. The entitlement is added to their account.
Check a Player's Entitlements
For Players with a Subscription
If your game or platform offers a subscription to your players, you can use the following code to check a player's entitlements and subscription plan
- Unreal SDK
- Unity SDK
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient("key");
FString EntitlementName = "Entitlement";
FString ItemId = "ItemId";
TArray<FString> Features = { "feature1" };
int Offset = 0;
int Limit = 20;
ApiClient->Entitlement.QueryUserEntitlements(EntitlementName, ItemId, Offset, Limit
, THandler<FAccelByteModelsEntitlementPagingSlicedResult>::CreateLambda(
[=](const FAccelByteModelsEntitlementPagingSlicedResult& Result)
{
UE_LOG(LogTemp Log, TEXT(" Success"));
})
, FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogTemp, Error, TEXT("Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage)
}
, EAccelByteEntitlementClass::NONE
, EAccelByteAppType::NONE);
string entitlementName = "Entitlement";
string itemId = "ItemId";
string[] features = new string[] { "feature1" };
int offset = 0;
int limit = 20;
Entitlement entitlements = AccelBytePlugin.GetEntitlement();
entitlements.QueryUserEntitlements(entitlementName, itemId, offset, limit, result => {
if (result.IsError)
{
Debug.Log("QueryUserEntitlements failed");
}
else
{
Debug.Log("QueryUserEntitlements successful");
}
},
EntitlementClazz.NONE,
EntitlementAppType.NONE,
features
);
For Players without a Subscription
If you don't offer subscriptions, you can use the following code to check a player's entitlements. To get all of the player's entitlements, set the EntitlementName
and ItemId
to ""
(i.e., an empty string).
- Unreal SDK
- Unity SDK
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient("key");
FString EntitlementName = "";
FString ItemId = "";
int32 Offset = 0;
int32 Limit = 20;
ApiClient->Entitlement.QueryUserEntitlements(EntitlementName, ItemId, Offset, Limit,
THandler<FAccelByteModelsEntitlementPagingSlicedResult>::CreateWeakLambda(this, [](const FAccelByteModelsEntitlementPagingSlicedResult& Result)
{
UE_LOG(LogTemp, Log, TEXT("Query User Entitlements Success!"));
}),
FErrorHandler::CreateWeakLambda(this, [](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogTemp, Error, TEXT("Query User Entitlements Failed, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}),
EAccelByteEntitlementClass::NONE,
EAccelByteAppType::NONE
);
string entitlementName = "";
string itemId = "";
int offset = 0;
int limit = 20;
Entitlement entitlements = AccelBytePlugin.GetEntitlement();
entitlements.QueryUserEntitlements(entitlementName, itemId, offset, limit, result => {
if (result.IsError)
{
Debug.Log("QueryUserEntitlements failed");
}
else
{
Debug.Log("QueryUserEntitlements successful");
}
},
EntitlementClazz.NONE,
EntitlementAppType.NONE
);
The response object from QueryUserEntitlements()
contains an array of entitlement info that includes all entitlement-related IDs. This includes EntitlementId
, ItemId
and SKUId
. These IDs can later be used to get item or specific entitlement information.
In some cases, we recommend using the SKU-related functions if you have your own item ID that isn't namespace and environment dependent. You can define the SKU ID manually in the Admin Portal, unlike ItemId
which is generated automatically. See our Create an Item documentation for more details.
Check Redeemed Items in Entitlements
To check redeemed items, you can call getUserEntitlementById
from the Entitlement API. The response includes itemSnapshot
which contains detailed information regarding the redeemed item. When the entitlement is a result of a redeem code process, the entitlement source shown in the response should be `REDEEM_CODE
.
- Unreal SDK
- Unity SDK
FString EntitlementId = "EntitlementId"
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient("key");
ApiClient->Entitlement.Entitlement.GetUserEntitlementById(EntitlementId, THandler<FAccelByteModelsEntitlementInfo>::CreateLambda([](const FAccelByteModelsEntitlementInfo& Result)
{
UE_LOG(LogTemp, Log, TEXT("The redeemed item ID: %s with name %s"), *Result.ItemId, *Result.ItemSnapshot.Name);
}), FErrorHandler::CreateLambda([](int32 Code, const FString& Message){}));
Entitlement entitlements = AccelBytePlugin.GetEntitlement();
entitlements.GetUserEntitlementById(
"entitlementId",
result => {
if (result.IsError)
{
Debug.Log("GetUserEntitlementById failed");
}
else
{
Debug.Log("GetUserEntitlementById successful");
}
});
Get User Entitlements By SKU
This function is not yet supported by our SDKs, but the endpoint is available in the API.
Third-party Item Entitlement Synchronization
Apple
To synchronize Apple entitlements, use the following function.
- Unreal SDK
- Unity SDK
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient("key");
//login with apple account
FString AppleAuthToken = “Token-from-apple”;
ApiClient->User.LoginWithOtherPlatform(EAccelBytePlatformType::Apple, AppleAuthToken), FVoidHandler::CreateLambda([&]()
{
UE_LOG(LogTemp, Log, TEXT(" Success"));
//do something when success
}), FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogTemp, Error, TEXT(" Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
//do something when error
}));
...
//sync apple item entitlement
bSyncDone = false;
FAccelByteModelsPlatformSyncMobileApple SyncReqApple;
SyncReqApple.ProductId = "testProductIdInvalid";
SyncReqApple.TransactionId = "testTransactionIdInvalid";
SyncReqApple.ReceiptData = "testReceiptDataInvalid";
SyncReqApple.ExcludeOldTransactions = true;
SyncReqApple.Region = "ID";
SyncReqApple.Language = "en";
ApiClient->Entitlement.SyncMobilePlatformPurchaseApple(SyncReqApple
, FVoidHandler::CreateLambda(
[=]()
{
UE_LOG(LogTemp, Log, TEXT(" Success"));
})
, FErrorHandler::CreateLambda(
[](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogAccelByteEcommerceTest, Log, TEXT("Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
})
);
User user = AccelBytePlugin.GetUser();
//login with apple account
string AppleAuthCode = "apple-auth-code";
Result loginAppleResults = null;
user.LoginWithOtherPlatform(PlatformType.Apple, AppleAuthCode, result =>
{
loginAppleResults = result;
});
...
Entitlement entitlements = AccelBytePlugin.GetEntitlement();
entitlements.SyncMobilePlatformPurchaseApple(platformSyncMobileApple, result =>
if (result.IsError)
{
Debug.Log("SyncMobilePlatformPurchaseApple failed");
}
else
{
Debug.Log("SyncMobilePlatformPurchaseApple successful");
});
Google
To synchronize Google entitlements, use the following function.
- Unreal SDK
- Unity SDK
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient("key");
//login with Google account
FString GoogleAuthToken = “Token-from-Google”;
ApiClient->User.LoginWithOtherPlatform(EAccelBytePlatformType::Google, GoogleAuthToken ), FVoidHandler::CreateLambda([&]()
{
UE_LOG(LogTemp, Log, TEXT(" Success"));
//do something when success
}), FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogTemp, Error, TEXT(" Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
//do something when error
}));
...
FAccelByteModelsItemInfo itemInfo;
ApiClient->Item.GetItemBySku(TEXT("sku-number")
, TEXT("en")
, TEXT("US")
, THandler<FAccelByteModelsItemInfo>::CreateLambda(
[=](const FAccelByteModelsItemInfo& Response)
{
itemInfo = Response;
})
,FErrorHandler::CreateLambda(
[&bGetItemDone](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogTemp, Log, TEXT("Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
})
);
...
FAccelByteModelsPlatformSyncMobileGoogle SyncReqGoogle;
SyncReqGoogle.OrderId = TEXT("test-OrderId");
SyncReqGoogle.PackageName = TEXT("test-packageName");
SyncReqGoogle.ProductId = TEXT("testProductId");
SyncReqGoogle.PurchaseTime = 0;
SyncReqGoogle.PurchaseToken = TEXT("test.PurchaseToken");
if (bGetItemSuccess == true && itemInfo.EntitlementType == EAccelByteEntitlementType::DURABLE)
{
SyncReqGoogle.AutoAck = true;
}
else
{
SyncReqGoogle.AutoAck = false;
}
SyncReqGoogle.Region = TEXT("ID");
SyncReqGoogle.Language = TEXT("en");
if (!GoogleConfig.ApplicationName.IsEmpty())
{
ApiClient->Entitlement.SyncMobilePlatformPurchaseGooglePlay(SyncReqGoogle
, THandler<FAccelByteModelsPlatformSyncMobileGoogleResponse>::CreateLambda(
[&bSyncDone](FAccelByteModelsPlatformSyncMobileGoogleResponse const& response)
{
UE_LOG(LogTemp, Log, TEXT(" Success"));
if (response.NeedConsume)
UE_LOG(LogTemp, Log, TEXT("The item is consumable"));
if (!response.NeedConsume)
UE_LOG(LogTemp, Log, TEXT("The item is durable"));
})
, FErrorHandler::CreateLambda(
[&bSyncDone](int32 ErrorCode, const FString& ErrorMessage)
{
bSyncDone = true;
UE_LOG(LogTemp, Log, TEXT("Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
})
);
}
User user = AccelBytePlugin.GetUser();
Entitlement entitlement = AccelBytePlugin.GetEntitlement();
//login with google account
string GoogleAuthCode = "google-auth-code";
Result loginGoogleResults = null;
user.LoginWithOtherPlatform(PlatformType.Google, GoogleAuthCode, result =>
{
loginGoogleResults = result;
});
...
//item entitlement type from google play store
String itemEntitlementType = "DURABLE";
bool autoAckValue = false;
If (itemEntitlementType == "DURABLE")
{
autoAckValue = true;
}
PlatformSyncMobileGoogle platformSyncMobileGoogle = new PlatformSyncMobileGoogle
{
orderId = "testOrderId",
packageName = "testpackageName",
productId = "testProductId",
purchaseTime = 160388387672672,
purchaseToken = "testPurchaseToken",
region = "ID",
language = "en",
autoAck = autoAckValue
};
Result syncGoogleResult = null;
entitlement.SyncMobilePlatformPurchaseGoogle(platformSyncMobileGoogle, result =>
{
syncGoogleResult = result;
});
Twitch
To synchronize Twitch entitlements, use the following function.
- Unreal SDK
- Unity SDK
FString TwitchAuthToken = "Token-from-twitch";
FApiClientPtr ApiClient = FMultiRegistry::GetApiClient("key");
//login with apple account
ApiClient->User.LoginWithOtherPlatform(EAccelBytePlatformType::Twitch, TwitchAuthToken), FVoidHandler::CreateLambda([&]()
{
UE_LOG(LogTemp, Log, TEXT(" Success"));
//do something when success
}), FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogTemp, Error, TEXT(" Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
//do something when error
}));
...
//sync twitch entitlement
FAccelByteModelsTwitchDropEntitlement model;
model.GameId = TEXT("123456"); //your gameId
model.Region = TEXT("US");
model.Language = TEXT("en-US");
ApiClient->Entitlement.SyncTwitchDropEntitlement(model,
FVoidHandler::CreateLambda([&]()
{
UE_LOG(LogTemp, Log, TEXT(" Success"));
//do something when success
}),FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogTemp, Warning, TEXT(" Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
//do something when error
}));
Coming Soon