How to implement battle pass in application

Notice
Use this how-to when working only with the Game Commerce asset.

The battle pass lets you increase player engagement by issuing rewards for completing quests or playing actively during the period of the battle pass.

A free battle pass with limited rewards is available to all players. The final reward is also not included in the free pass.

Additionally, the player can purchase a premium pass with all the rewards, including the final one.

Battle pass progress is divided into levels. To unlock new levels and have time to open the final reward before the battle pass expires, the player needs to gain the necessary experience or purchase the level.

The demo project provides an example of implementing a battle pass using Xsolla products. To try battle pass:

  1. Start the Xsollus demo scene.
  2. Log in as a demo user or create a new user.
  3. Click Battle pass in the side menu.

To adapt the battle pass for your project:

  1. Add battle pass logic to your project.
  2. Create a set of reward coupons.
  3. Create a battle pass configuration.
  4. Create a battle pass item.
  5. Create a level-up item.

Add battle pass logic to project

All the logic for the battle pass is contained in the BattlepassPage prefab and is divided into the following blocks:

  • ScriptHolders — scripts for working with the battle pass configuration, items and player information
  • UIScriptHolders — scripts for player’s interaction

To add battle pass logic:

  1. In your project, instantiate the BattlepassPage prefab.
  2. Change the interface (optional).
  3. Modify the storing information logic.

Create set of reward coupons

Rewards can be virtual items and virtual currency packages.

In the current solution, rewards are granted to a player via the coupon redemption. To create a coupon set:

  1. Go to your project in Publisher Account.
  2. Create virtual items and virtual currency packs for rewarding players.
  3. For each reward set up a campaign with coupons using the following recommendations:

    • Specify the number of redemptions per user as the planned amount of coupon redemption in the battle pass. One coupon can be redeemed multiple times as a part of the battle pass (e.g., at different battle pass levels, at premium and free versions).
    • The campaign must be valid for the same period as the battle pass.

To build the battle pass configuration, it is recommended that you create a list of rewards in advance and for each of them indicate:

  • coupon code
  • virtual item or virtual currency package SKU
  • if the reward belongs to a specific level of the battle pass
  • If the reward belongs to the free or premium version

Note
You can configure rewards for the new battle pass before the previous one expires. In order not to break the logic of the application, don’t activate the coupon promotion before the start of the new battle pass.

Create battle pass configuration

The battle pass configuration is a JSON file containing:

  • the name of the battle pass
  • the expiry date of the battle pass
  • the structure of the levels, indicating the rewards for the free and premium versions

Note
The reward for the highest level of the premium battle pass version is automatically the final battle pass reward. Its display is different from the display of rewards for completing levels.

JSON file structure:

ParameterTypeDescription
Name
stringThe name of the battle pass. Must match the name of the battle pass item.
ExpiryDate
stringThe expiration date of the battle pass.
Levels
arrayBattle pass level structure.
Levels.Tier
integerLevel number.
Levels.Experience
integerThe amount of experience to reach the next level.
Levels.FreeItem
objectReward information for the free version of the battle pass. Can be null.
Levels.FreeItem.Sku
stringThe SKU of a virtual item or virtual currency package. Used to display the reward image and information about it to the user.

Note
For a virtual currency package, both the package SKU and the virtual currency SKU can be used.
| |
Levels.FreeItem.Quantity
| integer | The number of rewards. | |
Levels.FreeItem.Promocode
| string | The coupon code for the reward. | |
Levels.PremiumItem
| object | Reward information for the premium version of the battle pass. Can be null. | |
Levels.PremiumItem.Sku
| string | The SKU of a virtual item or virtual currency package. Used to display the reward image and information about it to the user.

Note
For a virtual currency package, both the package SKU and the virtual currency SKU can be used.
| |
Levels.PremiumItem.Quantity
| integer | The number of rewards. | |
Levels.PremiumItem.Promocode
| string | The coupon code for the reward. |

Battle pass configuration example:

Copy
Full screen
Small screen
{
  "Name": "BP2021JAN",
  "ExpiryDate": "29-03-2021",
  "Levels": [
    {
      "Tier": 1,
      "Experience": 1000,
      "FreeItem": {
        "Sku": "Sku",
        "Quantity": 10,
        "Promocode": "HELLO_WORLD"
      },
      "PremiumItem": {
        "Sku": "Sku2",
        "Promocode": "HELLO_WORLD2"
      }
    },
    {
      "Tier": 2,
      "Experience": 1000
    },
    {
      "Tier": 3,
      "Experience": 1000
    }
  ]
}

Create battle pass item

The battle pass item is a container for the battle pass configuration and is used to determine the player’s premium status (whether the player has purchased a premium version).

To create a battle pass item:

  1. Go to your project in Publisher Account.
  2. Create a virtual item group named #BATTLEPASS#.

Note
The #BATTLEPASS# group is a utility group and doesn’t appear in the in-game store and inventory.

  1. Create a virtual item with the following parameters:
    • Item name — the name of the battle pass specified in the configuration.
    • SKU — the battle pass ID. It is recommended to use the name of the battle pass specified in the configuration.
    • Item property — consumable or nonconsumable item.

Note
During the application debugging, it is recommended that you create the consumable item. This will allow you to test the reaction of the system to the presence or absence of the battle pass item.

    • Price — the price of the premium version of the battle pass. It is set in virtual or real currency.

Note
If a virtual item is priced in real and virtual currency, the application displays the real currency price.

    • Group — #BATTLEPASS#.

Note
During the application debugging, it is recommended to place an item in a group other than #BATTLEPASS# additionally. In this case, it will be visible in the inventory.

  1. Add the battle pass configuration to the created virtual item:
    1. Get the current description of the item in a JSON format using the Get virtual item API call.
    2. Convert the battle pass configuration to a string using an online service or the JSON.stringify() method in JavaScript.
    3. In the item description, specify the resulting string in the en object of the long_description parameter.
    4. Modify the item using the Update virtual item API call, specifying the updated item description in the request body.

Example of the battle pass item description:

Copy
Full screen
Small screen
{
  "sku": "BP2021JAN",
  "name":{
    "en": "BP2021JAN"
  },
  "type": "virtual_good",
  "description":{
    "en": "BP2021JAN"
  },
  "image_url": "https://cdn3.xsolla.com/img/misc/images/7cb1c2b719af329a9bc1df994d58b749.png",
  "long_description": {
    "en": "{
                \"Name\":\"BP2021JAN\",
                \"ExpiryDate\":\"01-07-2021\",
                \"Levels\":
                    [
                        {
                            \"Tier\":1,
                            \"Experience\":100,
                            \"FreeItem\":
                                {
                                    \"Sku\":\"Bullets\",
                                    \"Promocode\":\"B2021S1FL1E100\",
                                    \"Quantity\":50
                                }
                        }
                    ]
            }"
  },
  "attributes":[
  ],
  "is_free": false,
  "order": 1,
  "groups":[
    "Battlepass"
  ],
  "regional_prices":[
  ],
  "prices":[
    {
      "amount": 1,
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "media_list":[
  ],
  "vc_prices":[
  ],
  "is_enabled": true,
  "is_show_in_store": true,
  "regions":[
  ],
  "inventory_options":{
    "consumable": false,
    "expiration_period": null
  }
}

Create level-up item

The current battle pass solution lets players purchase levels for real or virtual currency. The price of a level is always the same. The experience the player gains within the current level is transferred to the next level.

To create a level-up item:

  1. Go to your project in Publisher Account.
  2. Create a virtual item with the following parameters:
    • Item name — the name of the level-up item in the format <battlepassname>_levelup_util, where <battlepassname> is the name of the battle pass specified in the configuration.
    • SKU — it is recommended to use the name of the battle pass specified in the configuration.
    • Item property — consumable or nonconsumable item.
    • Price — the price of a level. It is set in virtual or real currency.

Note
If a level-up item is priced in real and virtual currency, the application displays the real currency price.

    • Group — #BATTLEPASS#.

Note
During the application debugging, it is recommended that you place a level-up item in a group other than #BATTLEPASS# additionally. In this case, it will be visible in the inventory.

Specifics of current battle pass solution

Logic of displaying battle pass

The application displays only one battle pass according to the logic:

  • If one or more unexpired battle passes exist, the application displays the battle pass with the closest expiration date.
  • If all battle passes are expired, the application displays the last expired battle pass.

EXAMPLE 1

Current date: 03/04/2021.

The expiration dates of the battle passes: 03/01/2021, 04/01/2021, 05/01/2021.

The application displays a battle pass with an expiration date of 04/01/2021.

EXAMPLE 2

Current date: 03/04/2021.

Expiration dates for battle passes: 02/01/2021, 03/01/2021.

The application displays a battle pass with an expiration date of 03/01/2021.

Storing information logic

In the current solution, all information about a player’s progress on a battle pass (level, experience, received rewards, etc.) is stored in the user-editable attributes. As part of the demo, reading and editing these attributes is available on the Character page.

If the system doesn’t find the required attribute, a new one is automatically created. If the system finds attributes for the not current battle pass, those attributes are automatically deleted.

Notice
User-editable attributes can be changed on the client side of the game. To protect player progress data on a battle pass, it is recommended to use read-only attributes when implementing your own logic.

To determine the premium status of a player, the presence of the battle pass item in the player’s inventory is checked.

Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!
Last updated: August 8, 2022

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!