SDKs for Unity / Integrate SDK on application side
  Back to Docs

SDKs for Unity

Integrate SDK on application side

  1. Design an interface for the login system, in-game store, and other pages for your application.
  2. Implement in your application logic for user authentication, store display, purchase, and more using SDK methods.
Note
You can create your own solution by following Unity instructions, or use the demo scene as a template. To adapt the demo scene UI to your application, use the UI builder.
To get started with the basic SDK features, follow these step-by-step tutorials:You can find the scripts used in the Assets/Xsolla/Samples directory of SDK.

User login via username/email and password

This instruction shows how to use SDK methods to implement:

  • user sign-up
  • resend request for a sign-up confirmation email
  • user login
  • user password reset

You can authenticate users with their username or email address. In the following examples we authenticate users with their username, whereas the email address is used to confirm sign-up and to reset the password.

Note
If you use the Login widget on your site (in a web store, for example), make sure that you implemented the same user authentication methods on your site and in your application. The widget uses the email address for authentication by default. To set up user login via username, contact your Customer Success Manager or email to csm@xsolla.com.
The logics and interface in the examples are less complicated than they will be in your application. A possible authentication system implementation option is described in the demo project.

Implement user sign-up

This tutorial describes the implementation of the following logic:

Create page interface

Create a scene for a sign-up page and add the following elements on it:

  • username field
  • user email address field
  • user password field
  • sign-up button

The following picture shows the example of a page structure.

Create page controller

  1. Create a script RegistrationPage inherited from the MonoBehaviour base class.
  2. Declare variables for the page interface elements and set values for them in the Inspector panel.
  3. Add logic to process clicking on the sign-up button, as shown in the script example.
Note

In the script’s examples, the OnSuccess and OnError methods call the standard Debug.Log method. In case of an error, the error code and description are passed in the error parameter.

You can add other actions like opening a page with a resend request for a sign-up email or opening a login page if sign-up is successful.

Example of a script for a sign-up page:
Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;
using Xsolla.Auth;
using Xsolla.Core;

namespace Xsolla.Samples.Authorization
{
	public class RegistrationPage : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public InputField UsernameInput;
		public InputField EmailInputField;
		public InputField PasswordInputField;
		public Button RegisterButton;

		private void Start()
		{
			// Handling the button click
			RegisterButton.onClick.AddListener(() =>
			{
				// Get the username, email and password from input fields
				var username = UsernameInput.text;
				var email = EmailInputField.text;
				var password = PasswordInputField.text;

				// Call the user registration method
				// Pass credentials and callback functions for success and error cases
				XsollaAuth.Register(username, password, email, OnSuccess, OnError);
			});
		}

		private void OnSuccess(LoginLink loginLink)
		{
			Debug.Log("Registration successful");
			// Add actions taken in case of success
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Registration failed. Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

Set up sign-up confirmation email

After successful sign-up, a user receives a sign-up confirmation email to a specified address. You can customize emails sent to users in Publisher Account.

If you are developing an Android application, set up deep links to return a user to an application after they confirm sign-up.

Note
You can disable sign-up confirmation via an email address if your security standards allow you to do this. Contact your Customer Success Manager to disable it or contact us at csm@xsolla.com.

Implement sign-up confirmation email resend request

This tutorial describes the implementation of the following logic:

Create page interface

Create a scene for a page with a request to resend a confirmation email and add the following elements to it:

  • username/email field
  • resend email button

The following picture shows an example of the page structure.

Create page controller

  1. Create a script ResendConfirmationEmail inherited from the MonoBehaviour base class.
  2. Declare variables for page interface elements and set values for them in the Inspector panel.
  3. Add logic to process clicking on the resend email button, as shown in the script example.

Example of a script for an email resend page:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;
using Xsolla.Auth;
using Xsolla.Core;

namespace Xsolla.Samples.Authorization
{
	public class ResendConfirmationEmailPage : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public InputField UsernameInput;
		public Button ResendEmailButton;

		private void Start()
		{
			// Handling the button click
			ResendEmailButton.onClick.AddListener(() =>
			{
				// Get the username from the input field
				var username = UsernameInput.text;

				// Call the resend confirmation email method
				// Pass the username and callback functions for success and error cases
				XsollaAuth.ResendConfirmationLink(username, OnSuccess, OnError);
			});
		}

		private void OnSuccess()
		{
			Debug.Log("Resend confirmation email successful");
			// Add actions taken in case of success
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Resend confirmation email failed. Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

If the request is successful, the user receives a sign-up confirmation email to the email address specified during sign-up.

Implement user login

This tutorial describes the implementation of the following logic:

Create page interface

Create a scene for a login page and add the following elements to it:

  • username field
  • password field
  • remember me checkbox
  • login button

The following picture shows an example of the page structure.

Create page controller

  1. Create a script AutorizationPage inherited from the MonoBehaviour base class.
  2. Declare variables for page interface elements and set values for them in the Inspector panel.
  3. Add logic to process clicking on the login button, as shown in the script example.

Example of a script for a login page:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;
using Xsolla.Auth;
using Xsolla.Core;

namespace Xsolla.Samples.Authorization
{
	public class AuthorizationPage : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public InputField UsernameInput;
		public InputField PasswordInputField;
		public Button SignInButton;

		private void Start()
		{
			// Handling the button click
			SignInButton.onClick.AddListener(() =>
			{
				// Get the username and password from input fields
				var username = UsernameInput.text;
				var password = PasswordInputField.text;

				// Call the user authorization method
				// Pass credentials and callback functions for success and error cases
				XsollaAuth.SignIn(username, password, OnSuccess, OnError);
			});
		}

		private void OnSuccess()
		{
			Debug.Log("Authorization successful");
			// Add actions taken in case of success
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Authorization failed. Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

Implement password reset

This tutorial describes the implementation of the following logic:

Create page interface

Create a scene for a password reset page and add the following elements to a page:

  • username/email field
  • password reset button

The following picture shows an example of the page structure.

Create page controller

  1. Create a script ResetPasswordPage inherited from the MonoBehaviour base class.
  2. Declare variables for page interface elements and set values for them in the Inspector panel.
  3. Add logic to process clicking on the password reset button, as shown in the script example.

Example of a script for a password reset page:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;
using Xsolla.Auth;
using Xsolla.Core;

namespace Xsolla.Samples.Authorization
{
	public class ResetPasswordPage : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public InputField UsernameInput;
		public Button ResetPasswordButton;

		private void Start()
		{
			// Handling the button click
			ResetPasswordButton.onClick.AddListener(() =>
			{
				// Get the username from the input field
				var username = UsernameInput.text;

				// Call the password reset method
				// Pass the username and callback functions for success and error cases
				XsollaAuth.ResetPassword(username, OnSuccess, OnError);
			});
		}

		private void OnSuccess()
		{
			Debug.Log("Password reset successful");
			// Add actions taken in case of success
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Password reset failed. Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

After a successful password reset request, the user receives an email with a password reset link. In Publisher Account > your Login project > Security > OAuth 2.0 > OAuth 2.0 redirect URIs, you can configure a URL address or a path a user is redirected to after successful authentication, email confirmation, or password reset.

Social login

This guide shows how you can use SDK methods to implement user sign-up and login via their social network account.

Unlike for user authentication via username/user email address and password, you don’t have to implement separate logics for user sign-up. If the user’s first login is via a social network, a new account is created automatically.

If you have implemented social login in your application as an alternative authentication method, the social network account automatically links to an existing user account if the following conditions are met:

  • A user who signed up with username/email address and password logged into your application via a social network account.
  • A social network returns an email address.
  • User email address in a social network is the same as the email address used for sign-up in your application.
Note
You can implement manual linking of a social network account. Add the page to your application where users can link a social network account to their account. In the page controller, use the LinkSocialProvider SDK method.
This tutorial describes the implementation of the following logic:

The examples show how to set up user login via a Facebook account. You can set up all social networks in the same way.

The logics and interface in the examples are less complicated than they will be in your application. A possible authentication system implementation option is described in the demo project.

Create page interface

Create a scene for a login page and add the social login button to it. The following picture shows an example of the page structure.

Create page controller

  1. Create a script SocialAuthorizationPage inherited from the MonoBehaviour base class.
  2. Declare variables for the application login page interface elements and set values for them in the Inspector panel.
  3. Add logic to process clicking on the login button, as shown in the script example.
Note

In the script’s examples, the OnSuccess and OnError methods call the standard Debug.Log method. You can add other actions.

In case of an error, the error code and description are passed in the error parameter.

Example of a script for a login page:
Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;
using Xsolla.Auth;
using Xsolla.Core;

namespace Xsolla.Samples.Authorization
{
	public class SocialAuthorizationPage : MonoBehaviour
	{
		// Declaration of variables for SocialProvider and signIn button
		public SocialProvider SocialProvider = SocialProvider.Facebook;
		public Button SignInButton;

		private void Start()
		{
			// Handling the button click
			SignInButton.onClick.AddListener(() =>
			{
				// Call the social authorization method
				// Pass the social network provider and callback functions for success, error and cancel cases
				XsollaAuth.AuthViaSocialNetwork(SocialProvider, OnSuccess, OnError, OnCancel);
			});
		}

		private void OnSuccess()
		{
			Debug.Log("Social authorization successful");
			// Add actions taken in case of success
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Social authorization failed. Error: {error.errorMessage}");
			// Add actions taken in case of error
		}

		private void OnCancel()
		{
			Debug.Log("Social authorization cancelled by user.");
			// Add actions taken in case the user canceles authorization
		}
	}
}

Display of item catalog

This tutorial shows how to use the SDK methods to display the following items in an in-game store:

  • virtual items
  • groups of virtual items
  • bundles
  • packages of virtual currency

Before you start, configure items in Publisher Account:

  1. Configure virtual items and groups of virtual items.
  2. Configure packages of virtual currencies.
  3. Configure bundles.

This tutorial describes the implementation of the following logic:

The logics and interface in the examples are less complicated than they will be in your application. A possible item catalog in an in-game store implementation option is described in the demo project.

Note

The example of every item in a catalog shows:

  • item name
  • item description
  • item price
  • image

You can also show other information about the item if this information is stored in an in-game store.

Implement display of virtual items

Create item widget

  1. Create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Convert the created game object in a prefab by dragging a game object from a Hierarchy panel to a Project panel.
  3. Select a created prefab and click Open Prefab in the Inspector panel.
  4. Add the following UI elements as prefab child objects and configure their visuals:
    • item background image
    • item name
    • item description
    • item price
    • item image

The following picture shows an example of the widget structure.

Create item widget script

  1. Create a script VirtualItemWidget inherited from the MonoBehaviour base class.
  2. Declare variables for the item widget interface elements and set values for them in the Inspector panel.

Example of the widget script:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Samples.DisplayCatalog
{
	public class VirtualItemWidget : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public Text NameText;
		public Text DescriptionText;
		public Text PriceText;
		public Image IconImage;
	}
}

Create page to show list of items

  1. On the scene, create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Add the following UI elements as prefab child objects and configure their visuals:
    • page background image
    • item widgets display area

The following picture shows an example of the page structure.

Create page controller

  1. Create a script VirtualItemsPage inherited from the MonoBehaviour base class.
  2. Declare the following variables:
    • WidgetsContainer — container for widgets
    • WidgetPrefab — item widget prefab

  1. Attach a script to a page game object:
    1. Select an object in the Hierarchy panel.
    2. In the Inspector panel, click Add Component and select a VirtualItemsPage script.
  2. Set values for variables in the Inspector panel.

  1. Add login logic and logic for getting the list of items, as shown in the script example.
Note

In the script example to login we use the credentials of a demo account (username: xsolla, password: xsolla).

The script sample doesn’t contain implementation of the page-by-page display of items in the catalog (pagination). Use the offset and limit parameters of the GetCatalog SDK method to implement pagination. The maximum number of items on a page is 50. If the catalog has more than 50 items, pagination is necessary.

Example of a page controller script:
Copy
Full screen
Small screen
using System.Linq;
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Catalog;
using Xsolla.Core;

namespace Xsolla.Samples.DisplayCatalog
{
	public class VirtualItemsPage : MonoBehaviour
	{
		// Declaration of variables for widget's container and prefab
		public Transform WidgetsContainer;
		public GameObject WidgetPrefab;

		private void Start()
		{
			// Starting the authentication process
			// Pass the credentials and callback functions for success and error cases
			// The credentials (username and password) are hard-coded for simplicity
			XsollaAuth.SignIn("xsolla", "xsolla", OnAuthenticationSuccess, OnError);
		}

		private void OnAuthenticationSuccess()
		{
			// Starting the items request from the store after successful authentication
			XsollaCatalog.GetCatalog(OnItemsRequestSuccess, OnError);
		}

		private void OnItemsRequestSuccess(StoreItems storeItems)
		{
			// Iterating the items collection
			foreach (var storeItem in storeItems.items)
			{
				// Instantiating the widget prefab as child of the container
				var widgetGo = Instantiate(WidgetPrefab, WidgetsContainer, false);
				var widget = widgetGo.GetComponent<VirtualItemWidget>();

				// Assigning the values for UI elements
				widget.NameText.text = storeItem.name;
				widget.DescriptionText.text = storeItem.description;

				// The item can be purchased for real money or virtual currency
				// Checking the price type and assigning the values for appropriate UI elements
				if (storeItem.price != null)
				{
					var realMoneyPrice = storeItem.price;
					widget.PriceText.text = $"{realMoneyPrice.amount} {realMoneyPrice.currency}";
				}
				else if (storeItem.virtual_prices != null)
				{
					var virtualCurrencyPrice = storeItem.virtual_prices.First(x => x.is_default);
					widget.PriceText.text = $"{virtualCurrencyPrice.name}: {virtualCurrencyPrice.amount}";
				}

				// Loading the item image and assigning it to the UI element
				ImageLoader.LoadSprite(storeItem.image_url, sprite => widget.IconImage.sprite = sprite);
			}
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

The following picture shows the result of the script’s work.

Implement display of virtual item groups

Create item widget

  1. Create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Convert the created game object in a prefab by dragging a game object from a Hierarchy panel to a Project panel.
  3. Select a created prefab and click Open Prefab in the Inspector panel.
  4. Add the following UI elements as prefab child objects and configure their visuals:
    • item background image
    • item name
    • item description
    • item price
    • item image

The following picture shows an example of the widget structure.

Create item widget script

  1. Create a script VirtualItemWidget inherited from the MonoBehaviour base class.
  2. Declare variables for the item widget interface elements and set values for them in the Inspector panel.

Example of the widget script:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Samples.DisplayCatalog
{
	public class VirtualItemWidget : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public Text NameText;
		public Text DescriptionText;
		public Text PriceText;
		public Image IconImage;
	}
}

Create widget for button that opens groups of items

  1. Create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Convert the created game object in a prefab by dragging a game object from a Hierarchy panel to a Project panel.
  3. Select a created prefab and click Open Prefab in the Inspector panel.
  4. Add the button that allows displaying of the group of items as a child object for a prefab and configure its visuals.

The following picture shows an example of the widget structure.

Create script for button that opens groups of items

  1. Create the VirtualItemGroupButton script inherited from the MonoBehaviour base class.
  2. Declare variables for the button that opens the group of items and set values for the variables in the Inspector panel.
  3. Add a script to the root object of a prefab:
    1. Select an object in the Hierarchy panel.
    2. In the Inspector panel, click Add Component and select a VirtualItemGroupButton script.

Example of the widget script:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Samples.DisplayCatalog
{
	public class VirtualItemGroupButton : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public Text NameText;
		public Button Button;
	}
}

Create page to show list of items

  1. On the scene, create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Add the following UI elements as prefab child objects and configure their visuals:
    • page background image
    • item groups buttons display area
    • item widgets display area

The following picture shows an example of the page structure.

Create page controller

  1. Create the VirtualItemsByGroupsPage script inherited from the MonoBehaviour base class.
  2. Declare the following variables:
    • GroupButtonsContainer — container for group buttons
    • GroupButtonPrefab — button prefab
    • ItemWidgetsContainer — container for item widgets
    • WidgetPrefab — item widget prefab

  1. Attach a script to a page game object:
    1. Select an object in the Hierarchy panel.
    2. In the Inspector panel, click Add Component and select a VirtualItemsByGroupsPage script.
  2. Set values for variables in the Inspector panel.
  3. Add login logic and logic for getting the list of items, as shown in the script example.
Note

In the script example to login we use the credentials of a demo account (username: xsolla, password: xsolla).

The script sample doesn’t contain implementation of the page-by-page display of items in the catalog (pagination). Use the offset and limit parameters of the GetCatalog SDK method to implement pagination. The maximum number of items on a page is 50. If the catalog has more than 50 items, pagination is necessary.

Example of a page controller script:
Copy
Full screen
Small screen
using System.Collections.Generic;
using System.Linq;
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Catalog;
using Xsolla.Core;

namespace Xsolla.Samples.DisplayCatalog
{
	public class VirtualItemsByGroupsPage : MonoBehaviour
	{
		// Declaration of variables for widget's container and prefab
		public Transform GroupButtonsContainer;
		public GameObject GroupButtonPrefab;
		public Transform ItemWidgetsContainer;
		public GameObject ItemWidgetPrefab;

		private void Start()
		{
			// Starting the authentication process
			// Pass the credentials and callback functions for success and error cases
			// The credentials (username and password) are hard-coded for simplicity
			XsollaAuth.SignIn("xsolla", "xsolla", OnAuthenticationSuccess, OnError);
		}

		private void OnAuthenticationSuccess()
		{
			// Starting the items request from the store after successful authentication
			// Pass the callback functions for success and error cases
			XsollaCatalog.GetCatalog(OnItemsRequestSuccess, OnError);
		}

		private void OnItemsRequestSuccess(StoreItems storeItems)
		{
			// Selecting the group’s name from items and order them alphabetically
			var groupNames = storeItems.items
				.SelectMany(x => x.groups)
				.GroupBy(x => x.name)
				.Select(x => x.First())
				.OrderBy(x => x.name)
				.Select(x => x.name)
				.ToList();

			// Add group name for catalog category with all items regardless of group affiliation
			groupNames.Insert(0, "All");

			// Iterating the group names collection
			foreach (var groupName in groupNames)
			{
				// Instantiating the button prefab as child of the container
				var buttonGo = Instantiate(GroupButtonPrefab, GroupButtonsContainer, false);
				var groupButton = buttonGo.GetComponent<VirtualItemGroupButton>();

				// Assigning the values for UI elements
				groupButton.NameText.text = groupName;

				// Adding listener for button click event
				groupButton.Button.onClick.AddListener(() => OnGroupSelected(groupName, storeItems));
			}

			// Calling method for redraw page
			OnGroupSelected("All", storeItems);
		}

		private void OnGroupSelected(string groupName, StoreItems storeItems)
		{
			// Clear container
			DeleteAllChildren(ItemWidgetsContainer);

			// Declaring variable for items to be displayed on the page
			IEnumerable<StoreItem> itemsForDisplay;
			if (groupName == "All")
			{
				itemsForDisplay = storeItems.items;
			}
			else
			{
				itemsForDisplay = storeItems.items.Where(item => item.groups.Any(group => group.name == groupName));
			}

			// Iterating the items collection and assigning values for appropriate UI elements
			foreach (var storeItem in itemsForDisplay)
			{
				// Instantiating the widget prefab as child of the container
				var widgetGo = Instantiate(ItemWidgetPrefab, ItemWidgetsContainer, false);
				var widget = widgetGo.GetComponent<VirtualItemWidget>();

				// Assigning the values for UI elements
				widget.NameText.text = storeItem.name;
				widget.DescriptionText.text = storeItem.description;

				// The item can be purchased for real money or virtual currency
				// Checking the price type and assigning the appropriate value for price text
				if (storeItem.price != null)
				{
					var realMoneyPrice = storeItem.price;
					widget.PriceText.text = $"{realMoneyPrice.amount} {realMoneyPrice.currency}";
				}
				else if (storeItem.virtual_prices != null)
				{
					var virtualCurrencyPrice = storeItem.virtual_prices.First(x => x.is_default);
					widget.PriceText.text = $"{virtualCurrencyPrice.name}: {virtualCurrencyPrice.amount}";
				}

				// Loading the image for item icon and assigning it to the UI element
				ImageLoader.LoadSprite(storeItem.image_url, sprite => widget.IconImage.sprite = sprite);
			}
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Error: {error.errorMessage}");
			//  Add actions taken in case of error
		}

		// Utility method to delete all children of a container
		private static void DeleteAllChildren(Transform parent)
		{
			var childList = parent.Cast<Transform>().ToList();
			foreach (var childTransform in childList)
			{
				Destroy(childTransform.gameObject);
			}
		}
	}
}

The following picture shows the result of the script’s work.

Implement display of bundles

Create bundle widget

  1. Create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Convert the created game object in a prefab by dragging a game object from a Hierarchy panel to a Project panel.
  3. Select a created prefab and click Open Prefab in the Inspector panel.
  4. Add the following UI elements as prefab child objects and configure their visuals:

    • widget background image
    • bundle name
    • bundle description
    • bundle price
    • bundle content description (items and their quantity)
    • bundle image

The following picture shows an example of the widget structure.

Create widget script

  1. Create a script BundleWidget inherited from the MonoBehaviour base class.
  2. Declare variables for the item widget interface elements and set values for them in the Inspector panel.

Example of the widget script:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Samples.DisplayCatalog
{
	public class BundleWidget : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public Text NameText;
		public Text DescriptionText;
		public Text PriceText;
		public Text ContentText;
		public Image IconImage;
	}
}

Create page to show bundles

  1. On the scene, create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Add the following UI elements as prefab child objects and configure their visuals:
    • page background image
    • bundle widgets display area

The following picture shows an example of the page structure.

Create page controller

  1. Create the BundlesPage script inherited from the MonoBehaviour base class.
  2. Declare the following variables:
    • WidgetsContainer — container for widgets
    • WidgetPrefab — bundle widget prefab

  1. Attach a script to a page game object:
    1. Select an object in the Hierarchy panel.
    2. In the Inspector panel, click Add Component and select a BundlesPage script.

  1. Set values for variables in the Inspector panel.
  2. Add login logic and logic for getting the list of items, as shown in the script example.
Note

In the script example to login we use the credentials of a demo account (username: xsolla, password: xsolla).

The script sample doesn’t contain implementation of the page-by-page display of items in the catalog (pagination). Use the offset and limit parameters of the GetCatalog SDK method to implement pagination. The maximum number of items on a page is 50. If the catalog has more than 50 items, pagination is necessary.

Example of a page controller script:
Copy
Full screen
Small screen
using System.Linq;
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Catalog;
using Xsolla.Core;

namespace Xsolla.Samples.DisplayCatalog
{
	public class BundlesPage : MonoBehaviour
	{
		// Declaration of variables for widget's container and prefab
		public Transform WidgetsContainer;
		public GameObject WidgetPrefab;

		private void Start()
		{
			// Starting the authentication process
			// Pass the credentials and callback functions for success and error cases
			// The credentials (username and password) are hard-coded for simplicity
			XsollaAuth.SignIn("xsolla", "xsolla", OnAuthenticationSuccess, OnError);
		}

		private void OnAuthenticationSuccess()
		{
			// Starting the bundle request from the store after successful authentication
			// Pass the callback functions for success and error cases
			XsollaCatalog.GetBundles(OnBundlesRequestSuccess, OnError);
		}

		private void OnBundlesRequestSuccess(BundleItems bundleItems)
		{
			// Iterating the bundles collection
			foreach (var bundleItem in bundleItems.items)
			{
				// Instantiating the widget prefab as child of the container
				var widgetGo = Instantiate(WidgetPrefab, WidgetsContainer, false);
				var widget = widgetGo.GetComponent<BundleWidget>();

				// Assigning the values for UI elements
				widget.NameText.text = bundleItem.name;
				widget.DescriptionText.text = bundleItem.description;

				// Creating the string with bundle content and assigning it to the UI element
				var bundleContent = bundleItem.content.Select(x => $"{x.name} x {x.quantity}");
				widget.ContentText.text = string.Join("\n", bundleContent);

				// The bundle can be purchased for real money or virtual currency
				// Checking the price type and assigning the values for appropriate UI elements
				if (bundleItem.price != null)
				{
					var realMoneyPrice = bundleItem.price;
					widget.PriceText.text = $"{realMoneyPrice.amount} {realMoneyPrice.currency}";
				}
				else if (bundleItem.virtual_prices != null)
				{
					var virtualCurrencyPrice = bundleItem.virtual_prices.First(x => x.is_default);
					widget.PriceText.text = $"{virtualCurrencyPrice.name}: {virtualCurrencyPrice.amount}";
				}

				// Loading the bundle image and assigning it to the UI element
				ImageLoader.LoadSprite(bundleItem.image_url, sprite => widget.IconImage.sprite = sprite);
			}
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

The following picture shows the result of the script’s work.

Implement display of virtual currency packages

Create widget for virtual currency package

  1. Create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Convert the created game object in a prefab by dragging a game object from a Hierarchy panel to a Project panel.
  3. Select a created prefab and click Open Prefab in the Inspector panel.
  4. Add the following UI elements as prefab child objects and configure their visuals:

    • widget background image
    • package name
    • package description
    • package price
    • package image

The following picture shows an example of the widget structure.

Create widget script

  1. Create a script VirtualCurrencyPackageWidget inherited from the MonoBehaviour base class.
  2. Declare variables for the item widget interface elements and set values for them in the Inspector panel.

Example of the widget script:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Samples.DisplayCatalog
{
	public class VirtualCurrencyPackageWidget : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public Text NameText;
		public Text DescriptionText;
		public Text PriceText;
		public Image IconImage;
	}
}

Create page to show list of virtual currency packages

  1. On the scene, create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Add the following UI elements as prefab child objects and configure their visuals:
    • page background image
    • virtual currency package widgets display area

The following picture shows an example of the page structure.

Create page controller

  1. Create the VirtualCurrencyPackagesPage script inherited from the MonoBehaviour base class.
  2. Declare the following variables:
    • WidgetsContainer — container for widgets
    • WidgetPrefab — virtual currency package prefab

  1. Attach a script to a page game object:
    1. Select an object in the Hierarchy panel.
    2. In the Inspector panel, click Add Component and select a VirtualCurrencyPackagesPage script.
  2. Set values for variables in the Inspector panel.
  3. Add login logic and logic for getting the list of virtual currency packages, as shown in the script example.
Note

In the script example to login we use the credentials of a demo account (username: xsolla, password: xsolla).

The script sample doesn’t contain implementation of the page-by-page display of items in the catalog (pagination). Use the offset and limit parameters of the GetCatalog SDK method to implement pagination. The maximum number of items on a page is 50. If the catalog has more than 50 items, pagination is necessary.

Example of a page controller script:
Copy
Full screen
Small screen
using System.Linq;
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Catalog;
using Xsolla.Core;

namespace Xsolla.Samples.DisplayCatalog
{
	public class VirtualCurrencyPackagesPage : MonoBehaviour
	{
		// Declaration of variables for widget's container and prefab
		public Transform WidgetsContainer;
		public GameObject WidgetPrefab;

		private void Start()
		{
			// Starting the authentication process
			// Pass the credentials and callback functions for success and error cases
			// The credentials (username and password) are hard-coded for simplicity
			XsollaAuth.SignIn("xsolla", "xsolla", OnAuthenticationSuccess, OnError);
		}

		private void OnAuthenticationSuccess()
		{
			// After successful authentication starting the request for packages from store
			// Pass the callback functions for success and error cases
			XsollaCatalog.GetVirtualCurrencyPackagesList(OnPackagesRequestSuccess, OnError);
		}

		private void OnPackagesRequestSuccess(VirtualCurrencyPackages packageItems)
		{
			// Iterating the virtual currency packages collection
			foreach (var packageItem in packageItems.items)
			{
				// Instantiating the widget prefab as child of the container
				var widgetGo = Instantiate(WidgetPrefab, WidgetsContainer, false);
				var widget = widgetGo.GetComponent<VirtualCurrencyPackageWidget>();

				// Assigning the values for UI elements
				widget.NameText.text = packageItem.name;
				widget.DescriptionText.text = packageItem.description;

				// The package can be purchased for real money or virtual currency
				// Checking the price type and assigning the values for appropriate UI elements
				if (packageItem.price != null)
				{
					var realMoneyPrice = packageItem.price;
					widget.PriceText.text = $"{realMoneyPrice.amount} {realMoneyPrice.currency}";
				}
				else if (packageItem.virtual_prices != null)
				{
					var virtualCurrencyPrice = packageItem.virtual_prices.First(x => x.is_default);
					widget.PriceText.text = $"{virtualCurrencyPrice.name}: {virtualCurrencyPrice.amount}";
				}

				// Loading the package image and assigning it to the UI element
				ImageLoader.LoadSprite(packageItem.image_url, sprite => widget.IconImage.sprite = sprite);
			}
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

The following picture shows the result of the script’s work.

Sell virtual items for real currency

This section explains how to use the SDK methods to implement selling items for real currency using virtual items.

Before you start, implement a display of virtual items in a catalog. In the following example, we describe how to implement purchasing of virtual items. Configuration for other item types is similar.

This tutorial describes the implementation of the following logic:

The logic and interface in the examples are less complicated than they will be in your application. A possible implementation option for selling items for real currency and displaying a catalog of items is described in the demo project.

Complete item widget

Add a purchase button to the item widget and configure its visuals.

The following picture shows an example of the widget structure.

Complete item widget script

  1. Open the VirtualItemWidget script.
  2. Declare variables for the purchase button and set values for them in the Inspector panel.

Example of the widget script:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Samples.SellForRealMoney
{
	public class VirtualItemWidget : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public Text NameText;
		public Text DescriptionText;
		public Text PriceText;
		public Image IconImage;
		public Button BuyButton;
	}
}

Complete page controller to show list of items

  1. Open the VirtualItemsPage script.
  2. Add logic for processing clicking on the virtual item purchase button, as shown in the script example.
Note

In the script example, we call the Debug.Log base method if the item purchase is successful. You can add other actions like inventory display, etc.

By default, the payment page opens in a built-in browser. To open it in an external browser, go to Window > Xsolla > Edit Settings in the Unity editor main menu and uncheck the Enable in-app browser? box in the Inspector panel. If you use the external browser for Android applications, we recommend setting up the deep links to redirect the user to the app after they make a payment.

Example of a script for a page:
Copy
Full screen
Small screen
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Catalog;
using Xsolla.Core;

namespace Xsolla.Samples.SellForRealMoney
{
	public class VirtualItemsPage : MonoBehaviour
	{
		// Declaration of variables for widget's container and prefab
		public Transform WidgetsContainer;
		public GameObject WidgetPrefab;

		private void Start()
		{
			// Starting the authentication process
			// Pass the credentials and callback functions for success and error cases
			// The credentials (username and password) are hard-coded for simplicity
			XsollaAuth.SignIn("xsolla", "xsolla", OnAuthenticationSuccess, OnError);
		}

		private void OnAuthenticationSuccess()
		{
			// Starting the items request from the store after successful authentication
			// Pass the callback functions for success and error cases
			XsollaCatalog.GetCatalog(OnItemsRequestSuccess, OnError);
		}

		private void OnItemsRequestSuccess(StoreItems storeItems)
		{
			// Iterating the items collection
			foreach (var storeItem in storeItems.items)
			{
				// Skipping items without prices in real money
				if (storeItem.price == null)
					continue;

				// Instantiating the widget prefab as child of the container
				var widgetGo = Instantiate(WidgetPrefab, WidgetsContainer, false);
				var widget = widgetGo.GetComponent<VirtualItemWidget>();

				// Assigning the values for UI elements
				widget.NameText.text = storeItem.name;
				widget.DescriptionText.text = storeItem.description;

				// Assigning the price and currency values for UI elements
				var price = storeItem.price;
				widget.PriceText.text = $"{price.amount} {price.currency}";

				// Loading the item image and assigning it to the UI element
				ImageLoader.LoadSprite(storeItem.image_url, sprite => widget.IconImage.sprite = sprite);

				// Assigning the click listener for the buy button
				widget.BuyButton.onClick.AddListener(() =>
				{
					// Starting the purchase process
					// Pass the item SKU and callback functions for success and error cases
					XsollaCatalog.Purchase(storeItem.sku, OnPurchaseSuccess, OnError);
				});
			}
		}

		private void OnPurchaseSuccess(OrderStatus status)
		{
			Debug.Log("Purchase successful");
			// Add actions taken in case of success
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

Sell virtual items for virtual currency

This section explains how to use the SDK methods to implement selling items for virtual currency using virtual items.

Before you start, implement a display of virtual items in a catalog. In the following example, we describe how to implement purchasing of virtual items. Configuration for other item types is similar.

This tutorial describes the implementation of the following logic:

The logic and interface in the examples are less complicated than they will be in your application. A possible implementation option for selling items for virtual currency and displaying a catalog of items is described in the demo project.

Complete item widget

Add a purchase button to the item widget and configure its visuals.

The following picture shows an example of the widget structure.

Complete item widget script

  1. Open the VirtualItemWidget script.
  2. Declare variables for the purchase button and set values for them in the Inspector panel.

Example of the widget script:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Samples.SellForVirtualCurrency
{
	public class VirtualItemWidget : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public Text NameText;
		public Text DescriptionText;
		public Text PriceText;
		public Image IconImage;
		public Button BuyButton;
	}
}

Complete page controller to show list of items

  1. Open the VirtualItemsPage script.
  2. Add logic for processing clicking on the virtual item purchase button, as shown in the script example.
Note

In the script example, we call the Debug.Log base method if the item purchase is successful. You can add other actions like inventory display, virtual currency balance change, etc.

Implementation of logic for adding purchased items to the inventory isn’t required — it’s done automatically.

Example of a script for a page:
Copy
Full screen
Small screen
using System.Linq;
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Catalog;
using Xsolla.Core;

namespace Xsolla.Samples.SellForVirtualCurrency
{
	public class VirtualItemsPage : MonoBehaviour
	{
		// Declaration of variables for containers and widget prefabs
		public Transform WidgetsContainer;
		public GameObject WidgetPrefab;

		private void Start()
		{
			// Starting the authentication process
			// Pass the credentials and callback functions for success and error cases
			// The credentials (username and password) are hard-coded for simplicity
			XsollaAuth.SignIn("xsolla", "xsolla", OnAuthenticationSuccess, OnError);
		}

		private void OnAuthenticationSuccess()
		{
			// After successful authentication starting the request for catalog from store
			// Pass the callback functions for success and error cases
			XsollaCatalog.GetCatalog(OnItemsRequestSuccess, OnError);
		}

		private void OnItemsRequestSuccess(StoreItems storeItems)
		{
			// Iterating the items collection
			foreach (var storeItem in storeItems.items)
			{
				// Skipping items without prices in virtual currency
				if (storeItem.virtual_prices.Length == 0)
					continue;

				// Instantiating the widget prefab as child of the container
				var widgetGo = Instantiate(WidgetPrefab, WidgetsContainer, false);
				var widget = widgetGo.GetComponent<VirtualItemWidget>();

				// Assigning the values for UI elements
				widget.NameText.text = storeItem.name;
				widget.DescriptionText.text = storeItem.description;

				// Assigning the price and currency values for UI elements
				// The first price is used for the sake of simplicity
				var price = storeItem.virtual_prices.First(x => x.is_default);
				widget.PriceText.text = $"{price.name}: {price.amount}";

				// Loading the item image and assigning it to the UI element
				ImageLoader.LoadSprite(storeItem.image_url, sprite => widget.IconImage.sprite = sprite);

				// Assigning the click listener for the buy button
				widget.BuyButton.onClick.AddListener(() =>
				{
					// Starting the purchase process
					// Pass the item SKU, the price virtual currency SKU and callback functions for success and error cases
					XsollaCatalog.PurchaseForVirtualCurrency(storeItem.sku, price.sku, OnPurchaseSuccess, OnError);
				});
			}
		}

		private void OnPurchaseSuccess(OrderStatus status)
		{
			Debug.Log("Purchase successful");
			// Add actions taken in case of success
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

Display of virtual currency balance

This tutorial shows how to use the SDK methods to display the balance of virtual currency in your app.

The logics and interface in the examples are less complicated than they will be in your application. A possible item catalog in an in-game store implementation option is described in the demo project.

Create widget for display of balance

  1. Create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Convert the created game object in a prefab by dragging a game object from a Hierarchy panel to a Project panel.
  3. Select a created prefab and click Open Prefab in the Inspector panel.
  4. Add the following UI elements as prefab child objects and configure their visuals:
    • widget background image
    • virtual currency name
    • virtual currency quantity
    • virtual currency image

The following picture shows an example of the widget structure.

Create widget script to show balance

  1. Create a script VirtualCurrencyWidget inherited from the MonoBehaviour base class.
  2. Declare variables for the item widget interface elements and set values for them in the Inspector panel.

Example of the widget script:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Samples.DisplayVirtualCurrencyBalance
{
	public class VirtualCurrencyWidget : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public Text NameText;
		public Text AmountText;
		public Image IconImage;
	}
}

Create page with list of virtual currencies

  1. On the scene, create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Add the following UI elements as prefab child objects and configure their visuals:
    • page background image
    • widgets display area

The following picture shows an example of the page structure.

Create controller for page with list of virtual currencies

  1. Create a script VirtualCurrenciesPage inherited from the MonoBehaviour base class.
  2. Declare the following variables:
    • WidgetsContainer — container for widgets
    • WidgetPrefab — balance display widget prefab

  1. Attach a script to a page game object:
    1. Select an object in the Hierarchy panel.
    2. In the Inspector panel, click Add Component and select a VirtualCurrenciesPage script.

  1. Set values for variables in the Inspector panel.
  2. Add login logic and logic of getting a list of virtual currencies, as shown in the script example.
Note
In the script example, to login we use the credentials of a demo account (username: xsolla, password: xsolla).
Example of the page controller script:
Copy
Full screen
Small screen
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Core;
using Xsolla.Inventory;

namespace Xsolla.Samples.DisplayVirtualCurrencyBalance
{
	public class VirtualCurrenciesPage : MonoBehaviour
	{
		// Declaration of variables for widget's container and prefab
		public Transform WidgetsContainer;
		public GameObject WidgetPrefab;

		private void Start()
		{
			// Starting the authentication process
			// Pass the credentials and callback functions for success and error cases
			// The credentials (username and password) are hard-coded for simplicity
			XsollaAuth.SignIn("xsolla", "xsolla", OnAuthenticationSuccess, OnError);
		}

		private void OnAuthenticationSuccess()
		{
			// Starting the virtual currencies request from the store after successful authentication
			// Pass the callback functions for success and error cases
			XsollaInventory.GetVirtualCurrencyBalance(OnBalanceRequestSuccess, OnError);
		}

		private void OnBalanceRequestSuccess(VirtualCurrencyBalances balance)
		{
			// Iterating the virtual currency balances collection
			foreach (var balanceItem in balance.items)
			{
				// Instantiating the widget prefab as child of the container
				var widgetGo = Instantiate(WidgetPrefab, WidgetsContainer, false);
				var widget = widgetGo.GetComponent<VirtualCurrencyWidget>();

				// Assigning the values for UI elements
				widget.NameText.text = balanceItem.name;
				widget.AmountText.text = balanceItem.amount.ToString();

				ImageLoader.LoadSprite(balanceItem.image_url, sprite => widget.IconImage.sprite = sprite);
			}
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

The following picture shows the result of the script’s work.

Display of items in inventory

This tutorial shows how to use the SDK methods to display items in the user inventory.

The logics and interface in the examples are less complicated than they will be in your application. A possible inventory implementation option is described in the demo project.

Create item widget

  1. Create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Convert the created game object in a prefab by dragging a game object from a Hierarchy panel to a Project panel.
  3. Select a created prefab and click Open Prefab in the Inspector panel.
  4. Add the following UI elements as prefab child objects and configure their visuals:
    • item background image
    • item name
    • item description
    • item quantity
    • item image

The following picture shows an example of the widget structure.

Create item widget script

  1. Create a script InventoryItemWidget inherited from the MonoBehaviour base class.
  2. Declare variables for the item widget interface elements and set values for them in the Inspector panel.

Example of the widget script:

Copy
Full screen
Small screen
using UnityEngine;
using UnityEngine.UI;

namespace Xsolla.Samples.DisplayItemsInInventory
{
	public class InventoryItemWidget : MonoBehaviour
	{
		// Declaration of variables for UI elements
		public Text NameText;
		public Text DescriptionText;
		public Text QuantityText;
		public Image IconImage;
	}
}

Create page to show inventory

  1. On the scene, create an empty game object. To do this, go to the main menu and select GameObject > Create Empty.
  2. Add the following UI elements as prefab child objects and configure their visuals:
    • page background image
    • item widgets display area

The following picture shows an example of the page structure.

Create page controller

  1. Create a script InventoryItemsPage inherited from the MonoBehaviour base class.
  2. Declare the following variables:
    • WidgetsContainer — container for item widgets
    • WidgetPrefab — item widget prefab

  1. Attach a script to a page game object:
    1. Select an object in the Hierarchy panel.
    2. In the Inspector panel, click Add Component and select an InventoryItemsPage script.

  1. Set values for variables in the Inspector panel.
  2. Add login logic and logic for getting the list of items in the inventory.
Note
In the script example, to login we use the credentials of a demo account (username: xsolla, password: xsolla).
Example of the page controller script:
Copy
Full screen
Small screen
using UnityEngine;
using Xsolla.Auth;
using Xsolla.Core;
using Xsolla.Inventory;

namespace Xsolla.Samples.DisplayItemsInInventory
{
	public class InventoryItemsPage : MonoBehaviour
	{
		// Declaration of variables for widget's container and prefab
		public Transform WidgetsContainer;
		public GameObject WidgetPrefab;

		private void Start()
		{
			// Starting the authentication process
			// Pass the credentials and callback functions for success and error cases
			// The credentials (username and password) are hard-coded for simplicity
			XsollaAuth.SignIn("xsolla", "xsolla", OnAuthenticationSuccess, OnError);
		}

		private void OnAuthenticationSuccess()
		{
			// Starting the items request from the store after successful authentication
			// Pass the callback functions for success and error cases
			XsollaInventory.GetInventoryItems(OnItemsRequestSuccess, OnError);
		}

		private void OnItemsRequestSuccess(InventoryItems inventoryItems)
		{
			// Iterating the items collection
			foreach (var inventoryItem in inventoryItems.items)
			{
				// Skipping virtual currency items
				if (inventoryItem.VirtualItemType == VirtualItemType.VirtualCurrency)
					continue;

				// Instantiating the widget prefab as child of the container
				var widgetGo = Instantiate(WidgetPrefab, WidgetsContainer, false);
				var widget = widgetGo.GetComponent<InventoryItemWidget>();

				// Assigning the values for UI elements
				widget.NameText.text = inventoryItem.name;
				widget.DescriptionText.text = inventoryItem.description;
				widget.QuantityText.text = inventoryItem.quantity.ToString();

				// Loading the item image and assigning it to the UI element
				ImageLoader.LoadSprite(inventoryItem.image_url, sprite => widget.IconImage.sprite = sprite);
			}
		}

		private void OnError(Error error)
		{
			Debug.LogError($"Error: {error.errorMessage}");
			// Add actions taken in case of error
		}
	}
}

The following picture shows the result of the script’s work.

Your progress
Thank you for your feedback!

Useful links

Last updated: October 10, 2023

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!