Additional features

Learn about advanced setups from our how-tos.

How to try account linking in demo

You can implement the following features by linking a player’s account on different platforms to the main account:

  • automatic player identification on different platforms
  • manage a single cross-platform inventory on different platforms

Use demo scenes to check the linking of platform accounts to the main account for a preset Publisher Account project.

Note
You can link only one account of each platform to the main account.

To try account linking in a demo project:

  1. Go to your Unity project.
  2. Set up the demo scene to log in to the application via the platform account:
    1. In the main menu, go to Window > Xsolla > Edit Settings.
    2. Set the following parameters in the Inspector panel:
      1. Specify Publishing platform. The selected value must be different from Xsolla and None.
      2. Change Username from console.

  1. Start the Xsollus demo scene from the Assets > Xsolla > DemoCommon > Scene folder.

  1. Click User account and then Account linking in the demo scene. The demo project will open in the default browser to simulate the start of the application on another platform.

  1. Click Create an account.

  1. Specify email and password. Click Accept and create.

  1. Select an item in the catalog and click Buy on Xsolla. Purchase the item using one of the test bank cards. Close the receipt.

  1. Click on the email at the top of the screen to open the menu. Click Inventory. Make sure that the purchased item is available in the inventory.

  1. Click Get code. Click Request the code in the opened window. Write down the received account linking code.

  1. Go to the demo scene in Unity.
  2. Enter the received account linking code (see step 9) and click Confirm.

  1. Now the platform account is linked to the main account. Make sure that the purchased item is available in the inventory in the Unity demo scene.

  1. Since this account is already linked to the main account, you can get the account linking code from it. Click Get account link. Write down the received code.

  1. Set up the demo scene to log in to the application via another platform account (see step 2). The Publishing platform should be different from the one selected in step 2.
  2. Start the Xsollus demo scene from the Assets > Xsolla > DemoCommon > Scene folder.

  1. Make sure the player’s inventory is empty.
  2. Click Account linking. Stay in the Unity demo scene.

  1. Enter the received account linking code (see step 13) and click Confirm.

  1. Now the account from the new platform is also linked to the main account. Make sure that the purchased item is available in the inventory of the Unity demo scene.

Follow the recipe to configure account linking for your project.

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

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
integerThe number of rewards.
Levels.FreeItem.Promocode
stringThe coupon code for the reward.
Levels.PremiumItem
objectReward information for the premium version of the battle pass. Can be null.
Levels.PremiumItem.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.PremiumItem.Quantity
integerThe number of rewards.
Levels.PremiumItem.Promocode
stringThe 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.
Hide

How to use SDK to configure application UI

The SDK includes a UI builder. The UI builder lets you configure the visuals of the application UI.

You can change the UI by editing the visual properties of the UI elements — colors, sprites, and fonts. These properties group into one theme. Unity themes and visual components are connected by the decorators. When you change the visual property, the decorators change the visuals of the Unity components.

Use widgets to replace the UI elements with other elements of the same type. These widgets are independent and easily replaceable parts that are in the form of prefabs.

The UI is made of 2 independent parts:

  • Theme editor that is responsible for working with visuals.
  • Widget editor that is responsible for working with prefabs and lets you fully replace the UI elements.

Work with themes

Theme editor

To open a theme editor, go to the Unity editor main menu and open Window > Xsolla > UI Themes Editor.

The theme editor UI includes the following components:

  • Buttons with theme names used for selecting and applying the themes.

Note
During the application runtime, you can change the theme only by the SetCurrentThemeByName static method of the ThemesLibrary class. Pass a theme name to this method as a parameter.

  • Refresh button — lets you apply the theme properties or their changes to the application UI.
  • Auto Refresh box — lets you automatically apply the theme properties or their changes to the application UI.
  • Themes section — contains the list of existing themes.
  • Colors section — contains the list of theme colors.
  • Sprites section — contains the list of theme sprites.
  • Fonts section — contains the list of theme fonts.

You can do the following actions to the lists:

  • To add a new element, click the + icon in the lower part of the list.
  • To delete the selected element, click the - icon in the lower part of the list.
  • To change the order, click and hold the = icon and drag the element to the necessary position in the list.
  • To rename the element, change the text in the field with the element name.

The property values are changed in the standard Unity ways:

  • To change the color, click the property’s field and select a new value.
  • You can change the font or sprite in one of the following ways:
    • Drag an asset to the property field.
    • Click the icon and select an asset.

Theme library

The theme library is inherited from the ScriptableObject class and is situated in the Resources/UIBuilder/ThemesLibrary directory.

Note
It’s not recommended to change the directory of the theme library. As it is a singleton object that is loaded upon request from the definite resource directory.

Connect UI element to theme

To make the UI element visuals change according to the applied theme:

  1. Add decorators to the object and configure them.
  2. Add the property provider components to the object and configure them.

Decorators

Decorators are components that apply theme properties (color, sprite, or font) to standard Unity UI elements and change them.

Decorators contain property IDs, not the values of properties, and a link to the UI element (image or text). Generally, decorators are like connectors between themes and UI elements. You configure decorators in the Inspector panel.

List of decorators:

  • ImageColorDecorator — changes image color
  • ImageSpriteDecorator — changes image sprite
  • TextFontDecorator — changes text color
  • TextColorDecorator — changes text font

A decorator changes the element properties if the following events happen:

  • Object is activated in the theme editor or during a game runtime.
  • Current theme is changed in the editor or during the game runtime.
  • Connection between an object property and theme is changed in the Inspector panel.
  • Property value is changed in the theme editor.
  • Object prefab is opened for editing in the theme editor.

To add a connection between the UI element and a theme, do the following:

  1. Add a decorator component to the object.
  2. Select the ID of the property from the theme.

After the decorator is added to the object, it tries to find a required UI element on this object and assign it to the Comp variable.

Example of decorator application:

The ImageColorDecorator decorator is added to the image object. The Main Button ID for the color is specified in the example. As a result, the color specified in the theme for Main Button will be used for the image.

The decorator can dynamically change the component’s visuals while the game is being played and the user points at the object with a cursor or clicks the object.

To dynamically change visuals of the UI element:

  1. Add a decorator component to the object.
  2. Select the ID of the property from the theme.
  3. Add the DecoratorPointerEvents component to the object. This component tracks the events of clicking the object and pointing a cursor at it.
  4. In the decorator component, change the TransitionMode variable value to Override.
  5. Assign the added DecoratorPointerEvents component to the PointerEvents variable of the decorator.
  6. To change the visuals when pointing with a cursor:
    1. Check the Override on hover box.
    2. In the field near the box, select the ID of a property from the theme.
  7. To change the visuals when clicking:
    1. Check the Override on press box.
    2. In the field near the box, select the ID of a property from the theme.

Example of decorator’s application for dynamic change of visuals:

The ImageColorDecorator decorator is added to the image object. The Main Button ID for the color and the Main Button Hover ID for the color when pointing a cursor is specified in the example. As a result, the color specified in the theme for Main Button will be used for the image. When pointing a cursor, the color will change to the one specified in the theme for Main Button Hover.

Property providers

Property providers are classes in the form of containers for theme properties. They are used for more convenient connections between the user code and themes.

List of property providers:

  • ColorProvider — contains a link to the color property.
  • SpriteProvider — contains a link to the sprite property.
  • FontProvider — contains a link to the font property.

All property providers have a PropertyDrawer for more convenient configuration via the Inspector panel.

To configure a property provider and get the property value in a code:

  1. Add a property provider component to the object.
  2. Select an ID of a property from the theme.

Example of property providers configuration:

  1. In the script, declare a variable and assign a property provider component to it.
  2. To get a color value, call the GetValue method.

Example of the script:

Copy
Full screen
Small screen
public class ProviderExample : MonoBehaviour
{

  [SerializeField] private ColorPrivider ColorPrivider;

  private void Start()
  {
      Color color = ColorProvuder.GetValue();
  }

}

Work with widgets

Widget editor

To open a widget editor, go to the Unity editor main menu and open Window > Xsolla > UI Widgets Editor.

The widget editor UI includes the following components:

  • Refresh button — lets you apply widget changes in prefabs.
  • Auto Refresh box — lets you automatically apply widget changes in prefabs.
  • Widgets section — contains the list of widgets.

You can do the following actions to the list of widgets:

  • To add a new widget, click the + icon in the lower part of the list.
  • To delete the selected widget, click the - icon in the lower part of the list.
  • To change the order, click and hold the = icon and drag the element to the necessary position in the list.
  • To rename the widget, change the text in the field with the element name.
  • You can change the font or sprite in one of the following ways:

    • Drag a prefab to the field with a widget.
    • Click the icon and select a prefab.

Widget library

The widget library is inherited from the ScriptableObject class and is situated in the Resources/UIBuilder/WidgetsLibrary directory.

Note
It’s not recommended to change the directory of the widget library. As it’s a singleton object and is loaded upon request from the definite resource directory.

Connect UI element to widget

To easily replace UI elements with others, you should use widget containers instead of using widgets directly when building the UI. If you do so, you can simply configure the widget created by a container to change UI elements of the same type. The standard approach would require replacing all widgets manually.

The container creates a widget object as a child object and configures the RectTransform class properties for it, making the widget fill the whole space in the container.

When adding a container component to the UI element object, this object is used as a parent object for creating widgets.

The container changes the widget properties if the following events happen:

  • Connection between an object property and widget is changed in the Inspector panel.
  • Widget prefab is changed in the widget editor.

To connect the UI element and widget:

  1. Add the WidgetContainer component to the object.
  2. Select a widget ID.

Note

If an object with a widget container is a prefab, you can change the container settings only in the prefab editing mode. This is because you can change the hierarchy of child objects inside a Unity prefab only in this mode.

When replacing the widget, the current widget is deleted and the new widget is created. Keep this in mind when designing the working logic of objects and their connections.

Example of using a widget container:

For the WidgetA object, the widget with the Red Button ID is specified in the example. As a result, the WidgetA object will be created using a prefab specified for the Red Button widget in the editor.

UI builder structure

While operating, the UI builder uses the following components:

  • UIProperty — objects with the following data:
    • ID of the property
    • Property name
    • Visual data (colors, sprites, fonts, etc.)

  • Theme — theme component. The theme lets you change the visuals of the UI and represents a collection of properties in different groups (colors, sprites, and fonts). Every theme has a name and unique identifier. You can access the theme property using the ID of the property.
  • ThemesLibrary — library of all themes that exist in the project. It also contains the value of a current theme and provides methods for changing this value.
  • ThemeDecorator — the MonoBehaviour class components that refer to the theme properties and apply the values of these properties to standard Unity UI components. The ImageColorDecorator decorator, for example, changes the image color.
  • UIPropertyProvider — classes that give access to themes’ properties. Use these components to easily connect the user code with the data from themes. The ColorProvider class, for example, provides data about the colors.
  • WidgetContainer — the MonoBehaviour class component that lets you change the whole widget.
  • WidgetsLibrary — collection of widgets that exist in a project. The component contains the list of all widgets and provides methods for getting the widget by its ID.

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.
Hide
Last updated: July 20, 2021

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!