Season Pass

Last updated on 20 April, 2023 1:23 AM

Overview

The AccelByte Season Pass service provides a series of tiers within the pass time period, that players can progress through by completing specific tasks or challenges. As a player progresses through the tiers by earning experience points (XP) from completing a challenge, they can unlock various rewards that are set up by the game admin.

It is important to understand some of the key concepts used in the design of the Season Pass service.

• Season: a season in Season Pass refers to a specific period of time that includes special challenges in a series of tiers and rewards, for the players to claim after passing the tier. A Season will typically have a fixed duration (e.g., three months).
• Pass: a pass in Season Pass refers to the player subscription that grants them access to a series of tiers, over a specified season. There are two types of passes that you can set up in the Season Pass service, free and premium pass.
  • Free Pass: a type of pass that grants players access to a limited series of tiers without having to buy a pass. Typically, the rewards are more limited compared to premium passes.
  • Premium Pass: a type of pass that requires players to purchase before they are granted access to a more complete series of tiers. Generally, the rewards are more varied compared to free passes.
• Tier: a Tier in Season Pass refers to a level that a players can progress through by earning XP. As players earn XP by completing some challenge or activities within the game, they advance through the tiers, and claim the tier's rewards. The rewards that are claimed at each tier of a Season Pass can vary depending on what type of pass the players have.
• Reward: an Entitlement that is granted to the player who passes a specific tier. Season Pass rewards can include a wide variety of entitlements, such as in-game items, XP, coins, and many others.

The in-game Season Pass experience will be managed by the game client, which will retrieve a Season’s structured data through the SDK that can then be cached for the player.

Season passes can be managed through the AccelByte Admin Portal. You can create Seasons and their associated passes and tiers, as well as associate store items to rewards that players can unlock and then claim for each pass or tier.

Prerequisite

Create Season Pass-Specific Items

Before creating a Season event, ensure you’ve created a draft store containing the Season items or passes you will need for the event. Season pass items do not have to be in a published store to be used by a Season; in fact, we recommend creating the items for them in a draft store so that you can edit or delete them easily. Of course, if you want to make premium passes or tier level-ups available for purchase, those pass and tier items will need to be available in your published store.

Managing Seasons in the Admin Portal

Create a Season

You can create a Season event by following the steps below:

1. In the desired game title, expand the Game Management section and click Season Pass.

2. On the Season Pass page, click the Create Season button to create a new draft Season.

   

3. The Create New Season form appears. Fill in the required fields:

   

   • Name: Type the Season name.
   • Default Language: Select the default language for the Season. After creating your Season, you’ll be able to add additional languages for localization.
   • Start Date: Input the date and time the Season will start.
   • End Date: Input the date and time the Season will end.
   • Draft Store: Select the store that contains the tier related to this Season.
   • Tier Item: Choose the tier that will be used for this Season.
   • Default Exp. to Clear: Input the amount of XP required to clear each tier.
   • Automatically Claim Reward: If selected, players will granted the rewards they earn during the Season automatically.

4. When you’re finished, click the Create button. The new Season will be added to the list.

   NOTE

   After creating a Season, you can still Edit or Delete when it's no longer needed by clicking in the Action column next to the Season and selecting View.

   

Clone a Season

1. In the Draft Seasons section, choose the draft Season you want to clone by clicking in the Action column and selecting Clone.

   

2. The Clone Season form appears. Fill in the required fields:

   

   • Season Name: Type a name for the new clone.
   • Start Date: Type a start date for the new clone.
   • End Date: Type an end date for the new clone.

3. All other data will be cloned from the target Season. When you’re finished, click Clone. A new draft Season will be created in the list.

   

Add a Localization to a Season

1. In the Draft Season section, choose the draft Season you want to add localization to and click View All in the Publishing Contents column.

   

2. The Publishing Contents page for your Season opens. To add a new localization, click the Add Language button.

   

3. The Add Localization form appears. Fill in the required fields:

   

   • Language: Select the language for the new localization.
   • Title: Type the localized Season name.
   • Description: Type a localized description of the Season.

4. When you’ve completed the previous step, click Add. The localization will be added to the list.

   NOTE

   You can still edit the new localization by clicking the pencil button next to the fields or delete it when you no longer need it.

   

Upload a Background Image for a Season

1. In the Draft Season section, choose the draft Season you want to add an image to and click View All in the Season’s Publishing Contents column. \

   

2. The Publishing Contents page for your Season appears. Click the Images tab, then click the Upload button.

   

3. The Upload Images form appears. Click the Select Images button then select the desired image from your directory.

   

After the image is uploaded, make sure the image is correct. You can also change the name of the image.

4. Then, click Submit.

   

Managing Passes in the Admin Portal

Create a Pass

1. In the Draft Season section, choose the draft Season you want to add a pass to and click View in that Season’s Action menu.

   

2. On the Season Pass Details page, open the Passes tab and click the Create Pass button.

   

3. The Create New Pass form appears. Fill in the required fields:

   

   • Input the unique identifier for the pass in the Pass Code field.
   • Input the position you want this pass to occupy in-game in the Display Order field. The pass with the Display Order of 1 will appear at the top of the list, 2 will appear under 1, and so on.
   • Choose the item that you want to associate with this pass in the Pass Item field.
   • Select the Automatically enrolled option if you want all players who participate in the Season event to be automatically granted this pass.
   • Input the default name for the pass in the Title field.
   • Input the default description of the pass in the Description field.
   NOTE

   The Language selection is the same as the default language for the related Season and cannot be changed.

4. When you’ve completed the previous step, click Create. The new Pass has been added to the list.

   NOTE

   Once youhave created a Pass, you can still Edit or Delete it when you no longer need it. Note that when you delete a pass, all rewards tied to the pass will be removed.

   

Add a Localization to a Pass

1. In the Draft Season section, choose the draft Season that contains the pass you want to add a localization to, then click View in that Season’s Action menu.

   

2. On the Season Pass Details page, click the Passes tab and then click View All next to the pass you want to add a localization to.

   

3. The Publishing Contents fpage or your pass opens. To add a new localization, click the Add Language button.

   

4. The Add Localization form appears. Fill in the required fields:

   

   • Select the language for the new localization in the Default Language field.
   • Type the localized pass name in the Title field.
   • Type a localized description of the pass in the Description field.

5. When you’ve completed the previous steps, click Add. The localization will be added to the list.

   NOTE

   You can still edit the new localization by clicking the pencil button next to the fields or delete it when you no longer need it.

Upload a Background Image for a Pass

1. In the Draft Season section, choose the draft Season that contains the pass you want to upload a background image for, then click View in that Season’s Action menu.

   

2. On the Season Pass Details page, click the Passes tab and click View All next to the pass that you want to manage.

   

3. The Publishing Contents page for your pass appears. Click the Images tab, then click the Upload button.

   

4. The Upload Images form appears. Click the Select Images button and select the desired image from your directory.

   

5. Then click Submit. After the image is uploaded, make sure the image is correct. You can also change the name of the image.

Create a Reward

You can create a Reward by following the steps below:

1. In the Draft Season section, choose the draft Season you want to add a reward to, then click View in that Season’s Action menu.

   

2. On the Season Details page, click the Rewards tab. Then, click the Create Reward button.

   

3. The Create New Reward form appears. Fill in the form with the correct information. All of the fields are required.

   

   • Input a unique identifier for the code in the Reward Code field.
   • Choose the Reward Item type. The options are Items, Coins, and Bundles. For more information about item types, see the E-Commerce documentation.
   • Choose the item that will be awarded to players in the Reward Item field.
   • Type the quantity of the item to be awarded to players in the Reward Item Quantity field.
   • Upload a Thumbnail image for the item.

4. When you’ve completed the previous step, click the Create button. The new Reward will be added to the list.

   NOTE

   After creating a Reward, you can still Edit or Delete it when it's no longer needed. Note that when you edit a reward, the reward's Reward Code cannot be changed.

   

Managing Tiers in the Admin Portal

Create a Tier

You can create a Tier by following the steps below:

1. In the Draft Season section, choose the draft Season you want to add a pass to and click View in that Season’s Action menu.

   

2. On the Season Details page, click the Tiers tab and select the Create Tier button.

   

3. The Create New Tier form appears. Fill in the required fields:

   

   • Input the number of tiers you want this Season to have in the Tier Amount field.
   • Input the amount of XP a player needs to clear each tier in the Exp. to Clearfield.

4. When you’ve completed the previous step, click the Create button. Your new tier will appear in the associated Season Pass list.

   

5. You can also associate rewards with each pass and tier combination by clicking the View button under the Action column. The Tier No.1 Configuration form will appear.

   

   In the example above, only one pass currently exists. If you have more passes, more fields will appear. Fill in the field by choosing the rewards that you want to bind to that specific pass. You can select multiple rewards for a single pass.

6. When you’ve completed the previous step, click the Save button. The rewards will be tied to the pass in this tier.

   

Reorder Tiers

You can reorder a Season pass event’s tiers by following the steps below:

NOTE

Reordering tiers will also reorder their properties, such as the tiers' Experience to Clear and their associated Rewards.

1. Still in the Tiers tab of the Season Details page, You can see a list of tiers that have already been created for this event.

   

2. Click the pencil icon under the Order No. column of the tier that you want to move.

3. Input the desired order value, then click the checkmark. The tiers will be reordered. For example, if you change the 4th tier to order number 1, tiers 1-3 will become tiers 2-4.

   

Publishing and Retiring Seasons in the Admin Portal

Publish a Season

In order for a Season to start, it must be published before its start date. You can publish a draft Season by following the steps below:

1. Open the Season Pass page under the Game Management menu.

2. Go to the Draft Season section, click in the Action menu next to the draft Season you want to publish, and select Publish.

   

3. The Publish Season form appears. To publish this Season, type PUBLISH into the available field and click the Publish button.

   

Unpublish a Season

Unpublishing is a way to take a Season down temporarily to fix a problem with it, like a legal issue. Unpublishing a Season will prevent your players participating further in the Season event, but the data from that event will be saved. After you have fixed the problem you can publish the Season again and, because the event data was saved, players will be able to continue their progression from before the Season was unpublished. You can unpublish a Season by following the steps below:

1. In the Published Season section, click in the Action column next to the Season you want to unpublish, then select Unpublish.

   

2. A confirmation message appears. To unpublish this Season, click the Confirm button.

   

Retire a Season

Seasons already have end dates, following which players will no longer be able to participate in Season events, but will still be able to claim any rewards they have already earned. Retire a Season to prevent players claiming rewards or otherwise interacting with the Season. You can retire a current Season by following the steps below:

1. In the Published Season section, click in the Action menu next to the Season you want to retire, then select Retire.

   

2. A confirmation message appears. To retire this Season, click the Confirm button.

   

Managing User Advancement through Season Events in the Admin Portal

You can manually advance a user to the next tier by following the steps below:

1. In the Admin Portal, open yourgame title. Then, expand the User Management section of the left navigation menu and click Users.

   

2. In the Search User panel, select the search filter from the dropdown menu that corresponds to the player’s account information that you have on hand. For example, you can search by Email, Display Name or User Name filter if you have any of this information. Type that information in the text box and press Enter to search. The results of your search will appear. Browse the list to find the account you’re looking for and click View in the Action column of the account listing to open it.

   

3. The User Overview page will appear, giving you an overview of the player’s data such as wallet balance, ban status, and linked accounts, as well as more detailed records of the player’s activity. Open the Season Pass tab from the ribbon at the top of the page.

   

4. On the Season Pass Information page, click the View button next to the desired Season pass.

   

5. On the Season Pass tab of the User Management page, click the Level Up button to advance the user to the next tier.

   

6. A confirmation message appears. Fill in the following fields:

   • Fill the Source field with the options from the dropdown to define the source of the advancement.

     1. Choose Paid-For if the player got their advancement through purchasing a level upgrade.
     2. Choose Sweat if the player got their advancement through gameplay and engagement with your game.

   • Fill the Reason Tag with the reason the player got their advancement.

   

7. Click Yes, Level Up and the user will be advanced to the next tier. You can view the user’s advancement history in the User Accounts documentation.

Adding a Pass Item to a Bundle

After creating a Season, you can add a pass item to an item bundle.

Prerequisites

• Create a draft store
• Create a bundle category in the draft store
• Create a bundle item in the draft store
• Create a Season Pass item in the draft store

To add a pass item to a bundle, follow these steps:

1. In the Admin Portal, choose yourgame title. Expand the E-Commerce menu and click Stores.

2. On the Stores page, choose the draft store where the target bundle exists. Click Viewu nder the store’s Action column.

   

3. On the Draft Store page, click the Items tab and choose the bundle you want to add the pass item to. Open the bundle’s Action menu, then click View.

   

4. In the Bundle Items section of the Bundle page, click the Add/Edit Item button.

   

5. The Add/Edit Item form appears. Fill in the fields based on the Pass Item information you have on hand. Read our E-Commerce documentation about Adding a Bundle item for more information.

   

Implementing Season Pass using SDK

Retrieve the Current Season Pass

The game client can query the current active Season Pass to return information, such as the Item IDs of the items used as rewards, and tier progression information such as the required XP and reward passes for each tier.

Unreal Engine

FString Language = TEXT(“en”);

AccelByte::FRegistry::SeasonPass.GetCurrentSeason(
     Language,
     THandler<FAccelByteModelsSeasonInfo>::CreateLambda([&](const FAccelByteModelsSeasonInfo& Result)
    {
        /* do something when succeed*/
    }),
    FError::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        /* do something when failed */
    })
);

Retrieve the Current Player’s Season Pass Progression

The game client can query a player’s Season data to show the player their Season progression and rewards that can be claimed

Unreal Engine

FString Language = TEXT(“en”);

AccelByte::FRegistry::SeasonPass.GetCurrentUserSeason(
   THandler<FAccelByteModelsUserSeasonInfo>::CreateLambda([](const FAccelByteModelsUserSeasonInfo& Result)
    {
        /* do something when succeed*/
    }),
    FError::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        /* do something when failed */
    })
);

Grant XP to the Player using the Server API

The player can be granted XP by the Server API. The game server tracks player progress during Season events. If the player completes the challenges successfully, the game server will grant XP to the player.

Unreal Engine

int32 EXP = 300;
FString UserId = “TargetUserId”;

AccelByte:ServerSeasonPass.GrantExpToUser(
    UserId, EXP,
    THandler<FAccelByteModelsUserSeasonInfoWithoutReward>::CreateLambda(
    [](const FAccelByteModelsUserSeasonInfoWithoutReward& Result)
    {
        /* do something when succeeded */
    }),
    FError::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        /* do something when failed */
    })
);

Level Up in Tier

Players can move up in tier in two ways: either by gaining XP in Season challenges or by buying access to tiers. If a player moves up a tier from gaining XP, their tier will be leveled up automatically, their XP will be reset to 0, and any remainder from the last tier’s XP will be added back to the player’s XP. Players can also purchase access to advanced tiers.

When a player purchases access to a new tier, the tier information will have to be retrieved if it isn’t cached. This function retrieves the tier information if it isn’t cached.

TIP

This function isn’t necessary if the tier information is cached.

Unreal Engine

FAccelByteModelsItemCriteria ItemCriteria;
ItemCriteria.ItemType = EAccelByteItemType::INGAMEITEM;
ItemCriteria.CategoryPath = TEXT(“/seasonpass”);
int32 Offset = 0;
int32 Limit = 32;

AccelByte:FRegistry::Item.GetItemsByCriteria(
    ItemCriteria, Offset, Limit,
    THandler<FAccelByteModelsItemPagingSlicedResult>::CreateLambda(
    [](const FAccelByteModelsItemPagingSlicedResult& Result)
    {
        /* do something when succeeded */
    }),
    FError::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        /* do something when failed */
    })
);

This function now allows a player to purchase access to a tier.

Unreal Engine

FAccelByteModelsOrderCreate OrderTier;
OrderTier.CurrencyCode = TEXT(“CurrencyCode”);
OrderTier.DiscountedPrice = 100;
OrderTier.Price = 100;
OrderTier.Quantity = 1;
OrderTier.ReturnUrl = TEXT("https://example.com");
OrderTier.ItemId = TEXT(“ItemId”);
OrderTier.Region = "US";
OrderTier.Language = "en";

FRegistry::Order.CreateNewOrder(
    OrderTier,
    THandler<FAccelByteModelsOrderInfo>::CreateLambda([&](const FAccelByteModelsOrderInfo& Result)
    {
        /* do something when succeed */
    }),
    FError::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        /* do something when failed */
    })
);

Unlock a Premium Pass

Players can purchase a premium pass to gain access to additional rewards from Season events.

When a player purchases a premium pass, the pass information will have to be retrieved if it isn’t cached. This function retrieves the pass information.

TIP

This function isn’t necessary if the pass information is cached.

Unreal Engine

FAccelByteModelsItemCriteria ItemCriteria;
ItemCriteria.ItemType = EAccelByteItemType::INGAMEITEM;
ItemCriteria.CategoryPath = TEXT(“/seasonpass”);
int32 Offset = 0;
int32 Limit = 32;

AccelByte:FRegistry::Item.GetItemsByCriteria(
    ItemCriteria, Offset, Limit,
    THandler<FAccelByteModelsItemPagingSlicedResult>::CreateLambda(
    [](const FAccelByteModelsItemPagingSlicedResult& Result)
    {
        /* do something when succeeded */
    }),
    FError::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        /* do something when failed */
    })
);

The player can now purchase a premium pass.

Unreal Engine

FAccelByteModelsOrderCreate OrderPass;
OrderTier.CurrencyCode = TEXT(“CurrencyCode”);
OrderTier.DiscountedPrice = 100;
OrderTier.Price = 100;
OrderTier.Quantity = 1;
OrderTier.ReturnUrl = TEXT("https://example.com");
OrderTier.ItemId = TEXT(“ItemId”);
OrderTier.Region = "US";
OrderTier.Language = "en";

FRegistry::Order.CreateNewOrder(
    OrderPass,
    THandler<FAccelByteModelsOrderInfo>::CreateLambda([&](const FAccelByteModelsOrderInfo& Result)
    {
        /* do something when succeed */
    }),
    FError::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        /* do something when failed */
    })
);

Claim a Reward

If a Season wasn’t configured to grant players earned rewards automatically, the game client needs to claim the player’s reward manually. All rewards will be processed by the Fulfillment service.

Unreal Engine

FString PassCode = TEXT(“PremiumPassCode”);
int32 TierIndex = 0;
FString RewardCode = TEXT(“RewardCode”);

FAccelByteModelsSeasonClaimRewardRequest ClaimRequest{
   PassCode, TierIndex, RewardCode
};
AccelByte::FRegistry::SeasonPass.ClaimRewards(
     ClaimRequest,
     THandler<FAccelByteModelsSeasonClaimRewardResponse>::CreateLambda(
     [&](const FAccelByteModelsSeasonClaimRewardResponse& Result)
    {
        /* do something when succeed*/
    }),
    FError::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        /* do something when failed */
    })
);

Claim All Rewards

If a player has multiple rewards available to claim, they can be claimed all at once by the game client.

Unreal Engine

AccelByte::FRegistry::SeasonPass.BulkClaimRewards(
     THandler<FAccelByteModelsSeasonClaimRewardResponse>::CreateLambda(
     [&](const FAccelByteModelsSeasonClaimRewardResponse& Result)
    {
        /* do something when succeed*/
    }),
    FError::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
    {
        /* do something when failed */
    })
);