Integrate SDK on application side

General information

1. Design an interface for the login system, in-game store, and other pages for your application.
2. 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:

1. The user launches the game.
2. The application launches the Xsolla Login web widget.
3. The user logs into the game and goes to the item catalog.
4. The application requests the item catalog from Xsolla.
5. After successfully receiving item data, the application displays the item catalog.
6. The user clicks the item purchase button.
7. The application initiates the purchase process and displays the payment UI in the browser.
8. The user makes the payment.
9. The application closes the payment UI and passes the payment data to Xsolla.
10. 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:

1. Open your project in the Unity editor.
2. In the main menu, go to Assets > Create > C# Script.
3. Specify the name of the new file in the Assets folder as VirtualItemWidget.
4. Open the created file in the editor and add the following code to it:

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;
    }
}

5. Save the changes.

Create item widget prefab

Create the UI to display an item in the store:

1. Create a Canvas object to display UI elements. To do this, in the main menu go to GameObject > UI > Canvas. This will create the following objects on the scene:
   • The Canvas object with the Canvas, Canvas Scaler, and Graphic Raycaster components.
   • The EventSystem object, if such an object doesn’t already exist on the scene.
2. Create the VirtualItemWidget child object:
   1. In the Hierarchy panel, select the Canvas object.
   2. In the main menu, go to GameObject > UI > Image. This will create a new game object, this object will be a child of the Canvas object.
   3. Rename the created object to VirtualItemWidget.
3. Add UI objects to display item information:
   1. Create an object to display the widget icon:
      1. In the Hierarchy panel, select the VirtualItemWidget object.
      2. In the main menu, go to GameObject > UI > Image.
      3. Rename the created object to IconImage.
   2. Create an object to display the item name:
      1. In the Hierarchy panel, select the VirtualItemWidget object.
      2. In the main menu, go to GameObject > UI > Legacy > Text.
      3. Rename the created object to NameText.
   3. Create an object to display the item description:
      1. In the Hierarchy panel, select the VirtualItemWidget object.
      2. In the main menu, go to GameObject > UI > Legacy > Text.
      3. Rename the created object to DescriptionText.
   4. Create an object for the item purchase button:
      1. In the Hierarchy panel, select the VirtualItemWidget object.
      2. In the main menu, go to GameObject > UI > Legacy > Button. This will create a button object with the Text child object.
      3. Rename the created object to BuyButton.
      4. Rename the Text object to PriceText.
4. Add the item widget script as a component to the VirtualItemWidget object:
   1. In the Hierarchy panel, select the VirtualItemWidget object.
   2. In the Inspector panel, click Add Component and select the VirtualItemWidget script.
5. Assign UI elements to the required script slots:
   1. In the Hierarchy panel, select the VirtualItemWidget object.
   2. Drag and drop child UI objects from the Hierarchy panel to their corresponding VirtualItemWidget component slots in the Inspector panel.
6. Convert the created VirtualItemWidget object to a prefab:
   1. In the Hierarchy panel, select the VirtualItemWidget object.
   2. Drag and drop the object to the Project panel in the Assets folder. As a result, a new object appears in the Assets folder, and the object on the scene changes its color to blue.

Example of the item widget prefab:

Create store script

Create a new script named StoreController:

1. Open your project in the Unity editor.
2. In the main menu, go to Assets > Create > C# Script.
3. Specify the name of the new file in the Assets folder as StoreController.
4. Open the created file in the editor and add the following code to it:

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}");
		}
	}
}

5. Save the changes.

Create store object

Create the UI to display item list in the store:

1. Add a component that arranges widgets of individual items in a grid, manages the location and size of nested objects. To do this:
   1. In the Hierarchy panel, select the Canvas object.
   2. In the Inspector panel, click Add Component and select the Grid Layout Group script.
   3. In the Inspector panel, change the component settings if necessary: ​​set the cell size, spacing, etc.

2. Add the store script as a component to the Canvas object:
   1. In the Hierarchy panel, select the Canvas object.
   2. In the Inspector panel, click Add Component and select the StoreController script.
3. Assign the elements to the required slots of the StoreController script:
   1. In the Hierarchy panel, select the Canvas object.
   2. Drag and drop the Canvas object from the Hierarchy panel to the WidgetsContainer slot in the Inspector panel.
   3. Drag and drop the VirtualItemWidget object from the Hierarchy panel to the WidgetPrefab slot in the Inspector panel.

Example of the store object:

Launch and test store

Launch the store in the Unity editor and check its operation:

1. For the Canvas object, delete all child objects.
2. Click Play. As a result, when the application starts, a browser window with the Xsolla Login widget opens.

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

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

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

Useful links