Skip to main content

Entitlements

Last updated on

Overview​

AccelByte Cloud's Entitlements service ensures player's ownership of a specific item that they have purchased or earned. You can use Entitlements to grant or revoke items to or from players. There are two types of entitlements, as explained below:

  • Durable items are non-stackable and permanent. They do not disappear after use. Examples of durable items are, but not limited to: game skins, weapons, and unlockable characters.

  • Consumable items 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're identical items. Examples of consumable items are, but not limited to: ammo, potions, and food.

Entitlement management lets you see the entitlement history of all players or of a particular player.

Permissions​

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage entitlement in the Admin Portal. For a full list of permissions that impact entitlement management, see the Platform/Commerce tab of the permissions reference.

UsageResourceAction
Get User EntitlementADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTRead
Get User Entitlement HistoryADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTRead
Grant User EntitlementADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTCreate
Disable User EntitlementADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTUpdate
User EntitlementADMIN:NAMESPACE:{namespace}:USER:{userId}:ENTITLEMENTUpdate

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

Entitlement Source​

There are many different types of entitlement sources that can be applied to players. Here is the description of each credit source:

Entitlement SourceDescription
PurchaseEntitlement from normal purchase via real or virtual currency.
PromotionEntitlement grant from some promotion/activity.
Referral BonusEntitlement grant from inviting someone.
Redeem CodeEntitlement from code redemption.
OtherAnother kind of entitlement source that does not belong to above categories.

Please note that for now, you can only choose between Purchase, Redeem_Code, and Other. If you choose any other source of entitlement except those three, you'll only make a record that doesn't affect anything.

Manage Entitlements in the Admin Portal​

The Admin Portal gives community managers and game admins an easy way to manage players' entitlement.

Get a Player's Entitlements​

You retrieve the list of the player's entitlement from the AccelByte Admin Portal. To do so, follow the steps below:

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

  2. Specify the filter to search the player's entitlement by Full Entitlement ID, User ID, or Email. After that, input the keyword based on the chosen filter. Then, press the Enter button from your keyboard.

  3. Results appeared. Here you can see the information about the player's entitlement.

List a Player's Entitlement History​

You can see the list of the player's entitlement history from the AccelByte Admin Portal. To do so, follow the steps below:

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

  2. Specify the filter to search the player's entitlement by Full Entitlement ID, User ID, or Email. After that, input the keyword based on the chosen filter. Then, press the Enter button from your keyboard.

  3. The player's entitlement information appeared. Choose the record in which you want to view the entitlement history, then click View.

  4. The Entitlement History pop-up appears and displays the transaction history in descending order.

Grant an Entitlement to a Player​

You can grant an entitlement to a player from the AccelByte Admin Portal. To do so, follow the steps below:

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

  2. In the Entitlement page, click the Grant Item button.

  3. The Grant Item form appears. Fill in the required fields:

    • In the Add Item field, select the item you want to grant to a player.
    • Input the User ID with the player's id that you want to grant an entitlement. Then, click Add.
    • Input the Quantity of the item you want to grant to the player.

  4. Once completed, click the Grant button. The new entitlement will be granted to the player and will appear in the player's account in the Player Portal.

Disable a Player's Entitlement​

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

  2. Specify the filter to search the player's entitlement by Full Entitlement ID, User ID, or Email. After that, input the keyword based on the chosen filter. Then, press the Enter button from your keyboard.

  3. The player's entitlement information appeared. Choose the record in which you want to disable.

  4. Click the three-dot button of the desired entitlement and click Disable.

  5. In the Admin Portal, the Status of the item will be changed to Inactive and the item will be removed from the player's account in the Player Portal.

Revoke a Player's Entitlement​

  1. In the AccelByte Admin Portal, click the E-Commerce section and click the Entitlements menu.

  2. Specify the filter to search the player's entitlement by Full Entitlement ID, User ID, or Email. After that, input the keyword based on the chosen filter. Then, press the Enter button from your keyboard.

  3. The player's entitlement information appeared. Choose the record in which you want to revoke.

  4. Click the three-dot button of the desired entitlement and click Revoke.

  5. 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 in the Player Portal.

Implement Entitlements with the Client SDKs​

An entitlement is granted automatically when a player places an order for an item. If this process is successful, the item will be granted 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.

...  
FRegistry::User.GetUserEligibleToPlay(THandler<bool>::CreateLambda([](bool result)  
 {  
 if(result)  
 {  
 UE_LOG(LogTemp, Log, TEXT("User eligible to play."));  
 }  
 else  
 {  
 UE_LOG(LogTemp, Log, TEXT("User is not eligible to play, no App or Subscription found in user's entitlements"));  
 }  
 }), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)  
 {  
 UE_LOG(LogTemp, Log, TEXT("Failed to check user entitlements ownership. Error: %d | Message: %s"), ErrorCode, *ErrorMessage);  
 }));  
...

For Players without a Subscription​

If you don't offer subscriptions, you can use the following code to check a player's entitlements. 

string itemId = "22c2bc2924d84755a7fd52fe300f231d";  

Result<EntitlementPagingSlicedResult> entitlementResult = null;  
AccelBytePlugin.GetEntitlement().QueryUserEntitlements("", itemId, 0, 0, result =>  
{  
 entitlementResult = result;  
});  

while(entitlementResult == null){ yield return new WaitForSeconds(0.1f); }  

if(entitlementResult.Value.data[0].status == EntitlementStatus.REVOKED)  
{  
 //Quit the game  
}

Check Redeemed Items in Entitlement​

To check the redeemed items, we 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. 

FString EntitlementId = "123456789"  
FRegistry::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){}));

3rd Party Item Entitlement Synchronization​

Apple​

To synchronize Apple entitlement, use the following function.

//login with apple account
FString AppleAuthToken = “Token-from-apple”;
FRegistry::User.LoginWithOtherPlatform(EAccelBytePlatformType::Apple, AppleAuthToken), FVoidHandler::CreateLambda([&]()
{
  UE_LOG(LogAccelByteUserTest, Log, TEXT("    Success"));
  //do something when success
}), FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& ErrorMessage)
{
  UE_LOG(LogAccelByteUserTest, Warning, 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";

FRegistry::Entitlement.SyncMobilePlatformPurchaseApple(SyncReqApple, FVoidHandler::CreateLambda([&bSyncDone]()
{
  UE_LOG(LogAccelByteEcommerceTest, Log, TEXT("    Success"));
  bSyncDone = true;
}), FErrorHandler::CreateLambda([&bSyncDone](int32 ErrorCode, const FString& ErrorMessage)
{
  bSyncDone = true;
  UE_LOG(LogAccelByteEcommerceTest, Log, TEXT("Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
}));

Google Play​

To synchronize Google Play entitlement, use the following function.

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;
});
//Query user items entitlement

Twitch​

To synchronize Twitch Drop entitlement, use the following function.

FString TwitchAuthToken = “Token-from-twitch”;
FRegistry::User.LoginWithOtherPlatform(EAccelBytePlatformType::Twitch, TwitchAUthToken), FVoidHandler::CreateLambda([&]()
{
  UE_LOG(LogAccelByteUserTest, Log, TEXT("    Success"));
  //do something when success
}), FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& ErrorMessage)
{
  UE_LOG(LogAccelByteUserTest, Warning, 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");
FRegistry::Entitlement.SyncTwitchDropEntitlement(model,
  FVoidHandler::CreateLambda([&]()
  {
    UE_LOG(LogAccelByteUserTest, Log, TEXT("    Success"));
  //do something when success
  }),FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& ErrorMessage)
  {
    UE_LOG(LogAccelByteUserTest, Warning, TEXT("    Error. Code: %d, Reason: %s"),   ErrorCode, *ErrorMessage);
    //do something when error
  }));
  • Check out the API Reference for more information about entitlements.
  • Learn more about our Fulfillments service, which is used to grant players entitlements.
  • One way you can grant your players entitlements is through promotional campaigns with Code Redemption.