Integrate SDK on application side
General information
- Design an interface for the login system, in-game store, and other pages for your application.
- In your application, implement logic for user authentication, store display, purchase, and more using SDK methods.
Quick start
Below are instructions for the simplest implementation of the in-game sales scenario.
Interaction flow:
- The user launches the game.
- The application launches the Xsolla Login web widget.
- The user logs into the game and goes to the item catalog.
- The application requests the item catalog from Xsolla.
- After successfully receiving item data, the application displays the item catalog.
- The user clicks the item purchase button.
- The application initiates the purchase process and displays the payment UI in the browser.
- The user makes the payment.
- The application closes the payment UI and passes the payment data to Xsolla.
- The application outputs a message to the log about the results of payment processing.
Sequence diagram for interaction of your application (StoreController
script) and SDK:
Scenario limitations:
- The ready-made Xsolla Login web widget is used for user authorization. Xsolla provides standard widget templates. Their appearance and content is determined by the Login method chosen for your project and widget customization settings from Publisher Account.
- The scenario implements the sale of items for real currency only, without using a shopping cart, i.e. the user can buy only one item.
Create item widget script
Create a new script named VirtualItemWidget
:
- Open your project in the Unity editor.
- In the main menu, go to
Assets > Create > C# Script . - Specify the name of the new file in the
Assets folder asVirtualItemWidget
. - Open the created file in the editor and add the following code to it:
- C#
using UnityEngine;
using UnityEngine.UI;
namespace Xsolla.Example
{
public class VirtualItemWidget : MonoBehaviour
{
public Image IconImage;
public Text NameText;
public Text DescriptionText;
public Text PriceText;
public Button BuyButton;
}
}
- Save the changes.
Create item widget prefab
Create the UI to display an item in the store:
- Create a
Canvas
object to display UI elements. To do this, in the main menu go toGameObject > UI > Canvas . This will create the following objects on the scene:- The
Canvas
object with theCanvas
,Canvas Scaler
, andGraphic Raycaster
components. - The
EventSystem
object, if such an object doesn’t already exist on the scene.
- The
- Create the
VirtualItemWidget
child object:- In the
Hierarchy panel, select theCanvas
object. - In the main menu, go to
GameObject > UI > Image . This will create a new game object, this object will be a child of theCanvas
object. - Rename the created object to
VirtualItemWidget
.
- In the
- Add UI objects to display item information:
- Create an object to display the widget icon:
- In the
Hierarchy panel, select theVirtualItemWidget
object. - In the main menu, go to
GameObject > UI > Image . - Rename the created object to
IconImage
.
- In the
- Create an object to display the item name:
- In the
Hierarchy panel, select theVirtualItemWidget
object. - In the main menu, go to
GameObject > UI > Legacy > Text . - Rename the created object to
NameText
.
- In the
- Create an object to display the item description:
- In the
Hierarchy panel, select theVirtualItemWidget
object. - In the main menu, go to
GameObject > UI > Legacy > Text . - Rename the created object to
DescriptionText
.
- In the
- Create an object for the item purchase button:
- In the
Hierarchy panel, select theVirtualItemWidget
object. - In the main menu, go to
GameObject > UI > Legacy > Button . This will create a button object with theText
child object. - Rename the created object to
BuyButton
. - Rename the
Text
object toPriceText
.
- In the
- Create an object to display the widget icon:
- Add the item widget script as a component to the
VirtualItemWidget
object:- In the
Hierarchy panel, select theVirtualItemWidget
object. - In the
Inspector panel, clickAdd Component and select theVirtualItemWidget
script.
- In the
- Assign UI elements to the required script slots:
- In the
Hierarchy panel, select theVirtualItemWidget
object. - Drag and drop child UI objects from the
Hierarchy panel to their correspondingVirtualItemWidget
component slots in theInspector panel.
- In the
- Convert the created
VirtualItemWidget
object to a prefab:- In the
Hierarchy panel, select theVirtualItemWidget
object. - Drag and drop the object to the
Project panel in theAssets folder. As a result, a new object appears in theAssets folder, and the object on the scene changes its color to blue.
- In the
Example of the item widget prefab:

Create store script
Create a new script named StoreController
:
- Open your project in the Unity editor.
- In the main menu, go to
Assets > Create > C# Script . - Specify the name of the new file in the
Assets folder asStoreController
. - Open the created file in the editor and add the following code to it:
- C#
using System.Linq;
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Catalog;
using Xsolla.Core;
namespace Xsolla.Example
{
public class StoreController : MonoBehaviour
{
[SerializeField] private VirtualItemWidget WidgetPrefab;
[SerializeField] private Transform WidgetsContainer;
private void Start()
{
StartAuthorization();
}
private void StartAuthorization()
{
Debug.Log("Start the authorization process with the Xsolla Login Widget");
XsollaAuth.AuthWithXsollaWidget(OnAuthSuccess, OnError, null);
}
private void OnAuthSuccess()
{
Debug.Log("Authorization successful");
Debug.Log("Get the catalog of virtual items");
XsollaCatalog.GetItems(OnCatalogReceived, OnError);
}
private void OnCatalogReceived(StoreItems items)
{
Debug.Log("Catalog received successfully");
BuildStoreUI(items.items);
}
private void BuildStoreUI(StoreItem[] items)
{
// Create a widget for each item in the catalog
foreach (var item in items)
{
// Check if the item has a price for real money. If not, skip the item (e.g., it is a virtual currency)
if (item.price == null)
continue;
// Instantiate a widget prefab
var widget = Instantiate(WidgetPrefab, WidgetsContainer, false);
// Fill the widget with data
widget.NameText.text = item.name;
widget.DescriptionText.text = item.description;
widget.PriceText.text = $"{item.price.amount} {item.price.currency}";
// Loading the item image and assigning it to the UI element
ImageLoader.LoadSprite(item.image_url, sprite => widget.IconImage.sprite = sprite);
// Add a click listener to the Buy button
widget.BuyButton.onClick.AddListener(() => StartPurchase(item.sku));
}
}
private void StartPurchase(string sku)
{
Debug.Log($"Start the purchase process for the item: {sku}");
XsollaCatalog.Purchase(sku, OnPurchaseCompleted, OnError);
}
private void OnPurchaseCompleted(OrderStatus status)
{
Debug.Log("Purchase completed");
}
private void OnError(Error error)
{
Debug.LogError($"Error message: {error.errorMessage}");
}
}
}
- Save the changes.
Create store object
Create the UI to display item list in the store:
- Add a component that arranges widgets of individual items in a grid, manages the location and size of nested objects. To do this:
- In the
Hierarchy panel, select theCanvas
object. - In the
Inspector panel, clickAdd Component and select theGrid Layout Group
script. - In the
Inspector panel, change the component settings if necessary: set the cell size, spacing, etc.
- In the
VirtualItemWidget
object for a better visualization and easier configuration. This allows you to evaluate the general layout of your store right away.- Add the store script as a component to the
Canvas
object:- In the
Hierarchy panel, select theCanvas
object. - In the
Inspector panel, clickAdd Component and select theStoreController
script.
- In the
- Assign the elements to the required slots of the
StoreController
script:- In the
Hierarchy panel, select theCanvas
object. - Drag and drop the
Canvas
object from theHierarchy panel to theWidgetsContainer slot in theInspector panel. - Drag and drop the
VirtualItemWidget
object from theHierarchy panel to theWidgetPrefab slot in theInspector panel.
- In the
Example of the store object:

Launch and test store
Launch the store in the Unity editor and check its operation:
- For the
Canvas
object, delete all child objects. - Click
Play . As a result, when the application starts, a browser window with the Xsolla Login widget opens.

- Log into the application. After successful user authorization, the application requests the item catalog from Xsolla. After successfully receiving items’ data, the application creates necessary widgets. As a result, a list of store items is displayed.

- Click the purchase button in any item widget. The application initiates the purchase process, and shows the payment UI in the browser.

- Complete the purchase process. Use test cards for payment. After a successful purchase, the
Purchase completed
message appears in the logs.

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