Last Updated: 9/27/2022, 8:02:36 AM

# Season Pass

# Overview

Season Pass is a service that provides a tiered reward structure that grants special rewards to players that participate in limited-time challenges. As a player earns XP in the challenge, they will unlock tiers and get to claim rewards.

season-pass

The Season Pass feature is built from four main components: Seasons, Passes, Tiers, and Rewards.

  • A Season is a limited-time event that includes special challenges and rewards for players.
  • A Pass is an item that grants players access to a certain class of rewards available during a season event. Passes can be freely granted to players, or can be made available for purchase. Passes are represented by items you create, but they do not have to be actual in-game items granted to players.
  • A Tier is a level that players occupy during participation in a season event. Players can move up into new tiers by gaining XP or by purchasing access to higher tiers. Players will be granted a reward each time they clear a tier. Tiers are represented by items you create, but they do not have to be actual in-game items granted to players.
  • A Reward is an entitlement that is granted to a player when they finish a tier. For example, if a player moves from Tier 1 to Tier 2, they will be granted the rewards from Tier 1. Rewards can be items, XP, or any other entitlement.

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.

# Prerequisites and Permissions

# Prerequisites

# Create Season Pass Specific Items

Before you can create a Season event, make sure you make any pass or tier items you’ll need for the event in a draft store. 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. To learn how to create season pass items, see the Catalog documentation.

# 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 season pass in the Admin Portal.

Usage Permission Tag Action
Grant XP to the Player Using the Server API ADMIN:NAMESPACE:{namespace}:USER:{userId}:SEASONPASS Update
Level a Player Up in Tier ADMIN:NAMESPACE:{namespace}:USER:*:SEASONPASS Read, Update
Unlock a Premium Pass for a Player ADMIN:NAMESPACE:{namespace}:USER:*:SEASONPASS [READ, UPDATE] Read, Update

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.

# Managing Seasons in the Admin Portal

# Create a Season

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

  1. In the AccelByte Admin Portal, choose the target Game Namespace. Then go to the Game Management section of the left navigation menu and click Season Pass.

    season-pass

  2. On the Season Pass page, create a new draft season by clicking the Create Season button.

    season-pass

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

    season-pass

    • Input the Season Name.
    • Select the default language for the season in the Default Language field. After creating your season, you’ll be able to add additional languages for localization.
    • Input the date and time the season will begin in the Start Date field.
    • Input the date and time the season will end in the End Date field.
    • Choose the store that contains the tier related to this season in the Draft Store field.
    • Choose the tier that will be used for this season in the Tier Item field.
    • Input the amount of XP required to clear each tier in the Default Exp. to Clear field.
    • Select the Automatically Claim Reward option if you want players to be automatically granted the rewards they earn during the season.
  4. When you’re finished, click the Create button. The new season will be added to the list.

    Once you created a Season, you can View, Edit, or Delete the season. You can also Publish and Clone the Season.

# Clone a Season

You can clone a Season by following the steps below:

  1. In the Draft Season section, choose the draft season you want to clone by opening the season’s Action menu and clicking Clone.

    season-pass

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

    season-pass

    • Input a name for the new clone in the Season Name field.
    • Input a start date for the new clone in the Start Date field.
    • Input an end date for the new clone in the End Date field.

    All other season 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 Localization to a Season

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

    season-pass

  2. The Season Details Page will appear. In the Basic Information tab, scroll down to the Publishing Contents section. To add a new localization, click the Add Language button.

    season-pass

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

    season-pass

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

    When you’re finished, click Add.

  4. The localization will be added to the list.

    Once you’ve added the localization, you can edit it at any time by clicking on the pencil button.

# 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 Action column.

    season-pass

  2. The Season Details Page will appear. In the Basic Information tab, scroll down to the Publishing Contents section. Select the Images tab and then click the Upload button.

    season-pass

  3. The Upload Images form will appear. Click the **Select Images **button to browse for your desired image from your directory.

    season-pass

    Upload the image. After it is uploaded, make sure to check that the image is correct. You can also change the name of the image by clicking the pencil icon next to the image’s Name field. Once you’re done, click Submit.

    season-pass

  4. The background image will be uploaded.

# Managing Passes in the Admin Portal

# Create a Pass

You can create a Pass 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 column.

    season-pass

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

    season-pass

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

    season-pass

    • Input 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. A pass with a 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 dropdown menu.
    • Select Automatically enrolled if you want all players who participate in the season event to be automatically granted this pass.

    NOTE

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

    • Input the default name for the pass in the Title field.
    • Input the default description of the pass in the Description field.

    When you’re finished, click the Create button.

  4. The new Pass will be added to the list.

    Once you’ve created a Pass, you can still Edit or Delete it when it’s no longer needed. Note that when you delete a Pass, all the rewards tied to that Pass will be removed.

# Add Localization to a Pass

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

    season-pass

  2. On the Season Details page, select the Passes tab and then click View in that pass’s Action column.

    season-pass

  3. The Passes Details Page will appear. Scroll down to the Publishing Contents section. To add a new localization, click the Add Language button.

    season-pass

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

    season-pass

    • 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.

    When you’re finished, click Add.

  5. The localization will be added to the list.

    Once you’ve added the localization, you can edit it by clicking on the pencil icon or delete it when no longer needed.

# 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 column.

    season-pass

  2. On the Season Details page, click the Passes tab and click the View in the pass’s Action column.

    season-pass

  3. The Passes Details Page will appear. Scroll down to the Publishing Contents section. Select the Images tab and click the Upload button.

    season-pass

  4. The Upload Images form will appear. Click the Select Images button, upload the desired image from your directory, and click Submit.

    season-pass

    After the image is uploaded, make sure the image is correct. You can also change the name of the image. Once you’re done, click Submit.

    season-pass

  5. The background image will be uploaded.

# Manage Rewards in the Admin Portal

# 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 column.

    season-pass

  2. On the Season Details page, click the Rewards tab and select the Create Reward on the right-hand side.

    season-pass

  3. The Create New Reward form will appear. Fill in the required fields:

    season-pass

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

    When you’re finished, click Create.

  4. The new Reward will be added to the list.

    Once you’ve created a Reward, you can Edit or Delete it when no longer needed. Note that while you can 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 Season Pass menu, go to the Draft Seasons section, choose the draft season you want to edit, and click View in that season’s Action column.

    season-pass

  2. On the Season Details page, click the Tiers tab and select Create Tier on the right-hand side.

    season-pass

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

    season-pass

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

    Once completed, click the Create button.

  4. Your new tier will appear in the associated Season Pass list.

# 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 tier’s Exp. to Clear requirements and their associated Rewards.

  1. In the Draft Season section of the Season Pass page in the Admin portal, choose the desired draft season, then click View in that season’s Action column.

    season-pass

  2. On the Season Details page, select the Tiers tab. You will see a list of tiers that have already been created for this event.

    season-pass

  3. Click the pencil icon in the Order No. column of the tier that you want to move. Input the desired order value, then click the check mark. The tiers will be reordered. For example, if you change the 3rd tier to order number 1, tiers 1 and 2 will become tiers 2 and 3.

    season-pass

# Associate Rewards with Passes and Tiers

You can associate rewards with each pass and tier combination by following the steps below:

  1. In the Draft Season section, choose the draft season that contains the passes and tiers you want to associate to rewards, then click View in that season’s Action column.

    season-pass

  2. On the Season Details page, click the Tiers tab. Then, click the View button your desired tier’s Action column.

    season-pass

  3. The Tier No. 1 Configuration form will appear. Fields will appear for each of the passes in this season. Fill in each field by choosing the rewards that you want to bind to that specific pass. You can select multiple rewards for a single pass.

    season-pass

    When you’re finished, click the Save button. The rewards will be tied to the pass in this tier.

# 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. In the Draft Season section, choose the draft season you want to publish and click Publish in that season’s Action column.

    season-pass

  2. The Publish Season form will appear. To publish the season, type PUBLISH into the available field and click the Publish button.

    season-pass

  3. The draft season will be published.

# Unpublish a Season

Unpublishing is a way to take a season down temporarily to fix a minor problem with it, such as a legal issue. Unpublishing a season will make it so that your players cannot participate 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. Because the event data is still saved using this method, 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, choose the season you want to unpublish and click Unpublish in that season’s Action column.

    season-pass

  2. A confirmation message will appear. To unpublish this season, click the Confirm button.

    season-pass

  3. The current season will be unpublished.

# Retire a Season

Seasons have end dates, upon 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. You can retire a season to make it so that players can no longer claim rewards or otherwise interact with the season. Retire a current season by following the steps below:

  1. In the Published Season section, choose the season you want to retire and click Retire in that season’s Action column.

    season-pass

  2. A confirmation message will appear. To retire the season, click Confirm.

    season-pass

  3. The current season will be retired.

# 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, choose the target game namespace. Then go to the User Management section of the left navigation menu and select Users.

    season-pass

  2. Select the search filter from the dropdown menu in the Search User panel that corresponds to the player’s account information that you have on hand. 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.

    season-pass

    TIP

    Fuzzy search is allowed here, so you can find the player you’re looking for by typing just the first few characters of the player’s credentials that you have.

  3. The User Overview will appear, giving you a quick look at player 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.

    season-pass

  4. On the Season Pass Information page, click the View button of the selected season pass.

    season-pass

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

    season-pass

  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. Choose Paid-For if the player got their advancement through purchasing a level upgrade. Choose Sweat if the player got their advancement through gameplay and engagement with your game.
    • Fill the Reason Tag with the reason why the player got their advancement.

    season-pass

  7. To advance the user to the next tier, click Yes, Level Up. The user will be advanced to the next tier.

NOTE

You can view a 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. Before adding a pass item to a bundle, make sure you’ve already done the following actions:

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

  1. In the AccelByte Admin Portal, choose the target game namespace and then go to the E-Commerce section in the left navigation menu and click Stores.

    season-pass

  2. On the Stores page, choose the draft store where the target bundle exists and click View in the Action column.

    season-pass

  3. On the Draft Store page, click the Items tab. Choose the bundle you want to add the pass item to and click View under the bundle’s Action column.

    season-pass

  4. In the Bundle Items section of the Bundle page, click the Add New button.

    season-pass

  5. The Add Items form will appear. Type the name of the pass item you want to add to the bundle in the Add Items field. When you’re done, click the Add button.

    season-pass

# 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.

# 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.

# Grant XP to the Player using the Server API

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

# 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 data.

TIP

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

Then this function enables a player to purchase access to a tier.

# 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 data.

TIP

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

Then this function enables a player to purchase a premium pass.

# 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.

# Claim All Rewards

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

  • Using Season Pass requires you to create items, or use existing items you’ve already created. For more information about items and how to create them, see the Catalog documentation.
  • Season Pass is just one way to reward players for their engagement. For more information about rewards, see the Rewards documentation.