Entitlements

Last updated on 20 April, 2023 1:23 AM

Overview

AccelByte Gaming Services (AGS) Starter Entitlements service ensures players’ ownership of items they have purchased or earned. You can use Entitlements to grant or revoke items to or from players. There are two types of entitlements:

• Durable items that are non-stackable and permanent, meaning that they do not disappear after use. Examples of durable items include: game skins, weapons, and unlockable characters.

• Consumable items disappear after use and can be stackable or non-stackable. Multiple stackable items are listed under the same entitlement whereas multiple non-stackable items each have their own entitlement, even if they’re identical items. Examples of consumable items include: ammo, potions, and food.

Entitlement Source

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

Entitlement Source	Description
Purchase	Granted from normal purchase via virtual currency.
Redeem Code	Granted from a code redemption.
Other	Granted from some other entitlement source other than the above options.

IMPORTANT

For now, you can only choose between Purchase, Redeem_Code, or Other. If you choose any other source of entitlement, the source you create will not work.

Manage Entitlements in the Admin Portal

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

Retrieve a Player’s Entitlements

1. In the desired game title, expand the E-Commerce section and click Entitlements.

2. Selectthe filter to search for a player's entitlements by Full Entitlement ID, User ID, or Email. Input the keyword based on the chosen filter and press Enter to search.

   

3. If you choose User ID or Email as a filter, you can also filter the result based on the Entitlement Class and Features Name.

   Entitlement Class filters results based on their item type. You can choose All, App, Entitlement, Code, Subscription, Media, and Option Box.

   :::info NOTE The Entitlement option in the Entitlement Class field gives you the option to choose an item type other than App, Code, Subscription, Media, or Optionbox. To read more about item types, see Create an Item in a Store. :::

   Use Features Name to filter results based on their features. You can enter multiple feature names by pressing Enter then adding another feature.

   The results will appear. Here you can see the information about the player’s entitlements.

   

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 steps below:

1. In the desired game title, expand the E-Commerce section and click Entitlements.

2. Select the filter to search for a player's entitlements by Full Entitlement ID, User ID, or Email. Input the keyword based on the chosen filter and press Enter to search.

   

3. Choose the record you want from the list that appears and click View next to that record.

4. The Entitlement History pop-up will appear showing the transaction history of that entitlement in descending order.

   

Grant an Entitlement to a Player

You can grant entitlements to a player from the AccelByte Gaming Services (AGS) Starter Admin Portal.

1. In the desired game title, expand the E-Commerce section and click Entitlements.

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

   

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

   

   • Select the item you want to grant the player in the Add Item dropdown .
   • Input the User ID of the player to whom you want to grant the entitlement and click Add.
   • Input the Quantity of the item you want to grant to the players.

4. Once completed, click the Grant button. The new entitlement will be granted to the players.

Disable a Player’s Entitlements

1. In the desired game title, expand the E-Commerce section and click Entitlements.

2. Select the filter to search for a player's entitlements by Full Entitlement ID, User ID, or Email. Input the keyword based on the chosen filter and press Enter to search.

   

3. The player’s entitlement information will appear. Choose the record you want to disable, click the corresponding More Options (...) button, and select Disable.

4. In the Admin Portal, the Status of the item will be changed to Inactive.

   

Revoke a Player’s Entitlement

1. In the desired game title, expand the E-Commerce section and click Entitlements.

2. Select the filter to search for a player's entitlements by Full Entitlement ID, User ID, or Email. Input the keyword based on the chosen filter and press Enter to search.

   

3. The player’s entitlement information will appear. Choose the record you want to revoke, click the corresponding More Options (...) button, and select Revoke.

4. In the Admin Portal, the Status of the item will be changed to Revoked.

   

Implement Entitlements using 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.

Unreal Engine

...  
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
);

Unity

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.

Unity

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 Entitlements

To check redeemed items, 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 redemption code process, the entitlement source shown in the response will be REDEEM_CODE.

Unreal Engine

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){}));  

Unity

Result<EntitlementInfo> getUserEntitlementResult = null;  

AccelBytePlugin.GetEntitlement().GetUserEntitlementById(  
 “entitlementId”,  
 result => { getUserEntitlementResult = result; });  

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

if(!getUserEntitlementResult.IsError)  
{  
 Debug.Log("The redeemed item ID: " + getUserEntitlementResult.Value.itemId + "with name" + getUserEntitlementResult.Value.itemSnapshot.name );  
}  

Third-party Item Entitlement Synchronization

Apple

Use the following function to synchronize Apple entitlements.

Unreal Engine

//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);
}));

Unity

User user = AccelBytePlugin.GetUser();
Entitlement entitlement = AccelBytePlugin.GetEntitlement();

//login with apple account
string AppleAuthCode = "apple-auth-code";
Result loginAppleResults = null;
user.LoginWithOtherPlatform(PlatformType.Apple, AppleAuthCode, result =>
{
  loginAppleResults = result;
});

PlatformSyncMobileApple platformSyncMobileApple = new PlatformSyncMobileApple
{
    productId = "testProductId",
    transactionId = "TransactionId",
    receiptData = "testReceiptData",
    excludeOldTransactions = true,
    region = "ID",
    language = "en"
};
Result syncAppleResult = null;
entitlement.SyncMobilePlatformPurchaseApple(platformSyncMobileApple, result =>
{
     syncAppleResult = result;
});

Google Play

Use the following function to synchronize Google Play entitlements.

Unreal Engine

//Get Item info by SKU
FRegistry::Item.GetItemBySku("sku-number", "en", "us", THandler<FAccelByteModelsItemInfo>::CreateLambda([&bGetItemSuccess, &bGetItemDone, &itemInfo]
        (const FAccelByteModelsItemInfo& Response)
    {
        UE_LOG(LogAccelByteEcommerceTest, Log, TEXT("    Success"));
        itemInfo = Response;
    }),FErrorHandler::CreateLambda([&bGetItemDone](int32 ErrorCode, const FString& ErrorMessage)
    {
        UE_LOG(LogAccelByteEcommerceTest, Log, TEXT("Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
    }));

FAccelByteModelsPlatformSyncMobileGoogle SyncReqGoogle;
SyncReqGoogle.OrderId = "test-OrderId";
SyncReqGoogle.PackageName = "test-packageName";
SyncReqGoogle.ProductId = "testProductId";
if (itemInfo.EntitlementType == EAccelByteEntitlementType::DURABLE)
    {
        SyncReqGoogle.autoAck = true;
    }
    else
    {
        SyncReqGoogle.autoAck = false;
    }
SyncReqGoogle.PurchaseTime = 0;
SyncReqGoogle.PurchaseToken = "test.PurchaseToken";

SyncReqGoogle.Region = "ID";
SyncReqGoogle.Language = "en";

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

Unity

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

Use the following function to synchronize Twitch Drops entitlements.

Unreal Engine

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
  }));