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 maps 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 UE4 project in Unreal Editor.
  2. Set up the demo map to log in to the application via the platform account:
    1. Go to Settings > Project Settings > Plugins > Xsolla Login. Enable the Use Cross-Platform Account Linking option. Specify Platform and Platform Account ID.

    1. Go to Settings > Project Settings > Plugins > Xsolla Store. Enable the Use Cross-Platform Account Linking option. Select the same Platform as in Xsolla Login.

  1. Start the Demo_Store demo map from the Content Browser > Xsolla Content > Maps folder. The demo simulates authentication via the platform account, so you automatically authenticate and proceed to the in-game store.

  1. Click User account and then Account linking in the demo map. 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 UE demo map.
  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 of the demo map.

  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 map 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 Demo demo map from the Content Browser > Xsolla Content > Maps folder.

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

  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 UE demo map.

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 plug-in.

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

To add battle pass logic:

  1. Copy the BP_BattlepassPanel and BP_StoreDemo blueprints with all dependencies into your project.
  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 virtual currency price.

    • Group — #BATTLEPASS#.

  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 virtual currency price.

    • Group — #BATTLEPASS#.

Specifics of the 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 global settings that affect UI elements’ visuals — color, texture, and font. These properties group into a theme.

To swap the UI elements of the same type, you can use the widget wrappers — containers for created UI elements.

The UI builder contains 2 independent parts:

  • Themes are responsible for working with visuals.
  • Widget manager is responsible for working with widgets and lets you replace whole parts of the UI.

Work with themes

Theme is a XsollaUtilsTheme type asset. It contains the list of colors, fonts, and textures that are used by the UI elements. Every list is a set of key-value pairs where the key is a unique name of a theme parameter, and the value is a corresponding color, font, or texture.

You can work with themes in Settings > Project Settings > Plugins > Xsolla Utils:

  • To set the theme of the UI, select it in the Interface Theme field.
  • To edit the selected theme, click the 🔎 icon near the Interface Theme field.

Note
If the SDK is installed via Epic Games Launcher, modifying the standard themes from the SDK will make changes in other projects that use these themes. We recommend creating a separate theme for your application.

  • To create a new theme, click the + icon near the Interface Theme field.
  • To delete a selected theme, click the × icon near the Interface Theme field.

Note
If you change the theme parameter name, all its widgets will require editing.

Connect UI element to theme

To connect the UI element to the theme:

  1. In the UI element widget blueprint, get access to the theme by the following methods:
    • GetCurrentTheme — returns the current theme specified in the plug-in settings.
    • GetTheme — returns a theme by the name specified in the ThemeClass parameter.
  2. Use the following methods to get the values of definite parameters from the theme by passing the theme parameter name to them:
    • GetColor — gets color value.
    • GetFont — gets font.
    • GetBrush — gets texture.

In the demo project, every widget that supports themes has a set of String type parameters with theme parameter names. These parameters are used for setting up a visual for the UI element.

To find examples of widgets that support themes, go to Content Browser > Xsolla Content > Common > Components > Primitives.

Work with widget manager

The widget manager is a mechanism that lets you automatically replace the UI elements with the UI elements of the same type by changing their visuals and behavior.

To create the UI that supports the widget manager, the following conditions should be met:

  • Create a widget with the specified unified interface for the UI element.
  • Define the type name for the UI element widget in the widget library.
  • Pass the widget type for the UI element to the wrapper. The wrapper is a container for creating the UI elements. The name of the widget type should be identical to the name in the library.
  • When creating a UI, use the wrapper instead of the widget.

Widget wrappers

A wrapper is a container that creates a required widget in the area of the page that is occupied by the wrapper.

Using the widget wrappers when creating the UI lets you automatically change the UI elements within the whole UI. To do this, change the widget in the wrapper. The standard flow, that uses UI primitives, suggests replacing all widgets manually in this scenario.

Here are the following wrappers for different widget types:

  • W_ButtonWrapper — for a button
  • W_InputWrapper — for an input field
  • W_TextWrapper — for text
  • W_RichTextWrapper — for rich text
  • W_ImageWrapper — for an image
  • W_CheckBoxWrapper — for a box

In the Details panel, you can configure the display parameters of the widgets created by a wrapper. In the Widget Library Name field, you should specify the name of the widget type from the current widget library.

You can find the widget wrappers blueprints in Content Browser > Xsolla Content > Common > Components > Wrappers.

The wrappers use the widget manager methods to interact with the widgets.

Widget interfaces

To make the UI primitives interact with the widget wrapper as they would with the usual widget, the wrappers use unified interfaces.

There are the following wrappers for different widget types:

  • BPI_PrimitivesButton — for a button
  • BPI_PrimitivesInput — for an input field
  • BPI_PrimitivesText — for text
  • BPI_PrimitivesRichText — for rich text
  • BPI_PrimitivesImage — for an image
  • BPI_PrimitivesCheckbox — for a box

You can configure interfaces for the UI elements widgets in the Implemented Interfaces section of the Details panel.

You can find the widget interfaces in Content Browser > Xsolla Content > Common > Components > Interface.

Widget library

The widget library is an asset of the XsollaUtilsWidgetsLibrary type that contains the list of widget classes in a form of key-value pairs. The key contains the name of the widget type and the value contains the widget class that will be created by a corresponding wrapper with this key.

The widget library works as a connector between the wrappers and widget classes.

The BP_DefaultWidgetLibrary default widget library is included in the SDK. This library contains the list of UI elements from the demo project.

You can work with the widget library in Settings > Project Settings > Plugins > Xsolla Utils:

  • To install the current widget library, select it in the Widgets Library field.
  • To edit the selected widget library, click the 🔎 icon near the Widgets Library field.

Note
If the SDK is installed via Epic Games Launcher, modifying the standard widget library from the SDK will make changes in other projects that use this library. We recommend creating a separate widget library for your application.

  • To create a new widget library, click the + icon near the Widgets Library field.
  • To delete the selected widget library, click the × icon near the Widgets Library field.

Use the following methods in the wrapper blueprints to get access to the widget library:

  • GetCurrentWidgetsLibrary — returns the current widget library specified in the plug-in settings.
  • GetWidgetsLibrary — returns the specified widget library by the name specified in the WidgetLibraryClass parameter.

Use the GetWidget method in the wrapper blueprints, to get the widget type from the library.

Methods of widget manager

The following methods are used by the wrappers to interact with the widgets. Use them when creating your own wrappers and widgets that support themes.

Methods for working with buttons

Method nameDescription
SetButtonEnabledSets the button state that defines whether the button reacts to the keyboard, mouse, timer events, etc.
IsButtonEnabledReturns the button state that defines whether the button reacts to the keyboard, mouse, timer events, etc.
GetWidgetReturns the list of UI primitives that contain the widget. Is used for subscribing to the button-clicking event.
ConstructButtonInitializes the button widget. Is used by the widget wrapper.
SetExtraDataSets a list of additional data for a button. Every widget processes the received data, demonstrates it, or uses it according to the inner logic. For example, you can use the set of additional data to pass the list of the drop-down menu elements to the button that has a drop-down menu.
SetIconDataSets a list of icons to display for a button. Use this method to specify the icon size and the distance between the icon and other button elements.
SetButtonSelectedSets the toggle position. For example: on or off, in cart or not in cart, etc.
GetThemeDataReturns the set of theme parameters used by the button widget.
SetButtonTextSets the text for a button.

Methods for working with boxes

Method nameDescription
SetIsCheckedSets the state of the box whether it’s checked or unchecked.
GetIsCheckedReturns the state of the box.
IsTickHoveredChecks whether the cursor hovers the box area.
ConstructCheckboxInitializes the box widget. Is used by the widget wrapper.
GetWidgetReturns the list of UI primitives contained by the widget. Used for subscribing to the box events.
GetThemeDataReturns the set of theme parameters used by the box widget.
SetTextSets the text for the box.
GetTextReceives the text for the box.

Methods for working with text or rich text

Method nameDescription
GetTextReturns the text value.
SetTextSets the text value.
GetWidgetReturns the list of UI primitives contained by the widget. Used for subscribing to the text events.
GetThemeDataReturns the set of theme parameters used by the text widget.
ConstructTextInitializes the text widget. Is used by the widget wrapper.

Methods for working with images

Method nameDescription
GetImageReturns the image.
SetImageSets the image.
GetWidgetReturns the list of UI primitives contained by the widget. Used for subscribing to the image events.
GetThemeDataReturns the set of theme parameters used by the image widget.
ConstructImageInitializes the image widget. Is used by the widget wrapper.

Method for working with input fields

Method nameDescription
GetTextReturns the text to the input field.
SetTextSets the text to the input field.
GetWidgetReturns the list of UI primitives contained by the widget. Used for subscribing to the input field events.
ConstructInputInitializes the input field widget. Is used by the widget wrapper.
GetHintReturns the tip text for the input field.
SetHintSets the tip text for the input field.
SetupFocusSets the focus on the input field.
GetThemeDataReturns the set of theme parameters used by the input field widget.
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 30, 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!