SDK for Unity

SDK for Unity#

A simple wrapper around the Xsolla Backend C# SDK exists that provides a Unity-friendly interface for accessing the Xsolla Backend API. This package also contains tests that can be run from within Unity to verify the functionality of the SDK.

Prerequisites#

This plug-in requires the following:

  1. Unity 2021.3 LTS (or newer)

Installation#

There are 2 ways to import the SDK into your project:

  1. Install From Git URL Recommended

  2. Clone The Repo and Install From Local Disk

Opt 1: Install from Git Url#

Recommended

  1. Open your project in Unity and navigate to the Package Manager window (Windows > Package Manager).

  2. In the Package Manager window click the + button in the top left corner and select Add package from git URL...

  3. Enter the following URL into the text box and click Add:

    https://unity:4sWpuQS6dnuSqa-Ki_nV@source.goxbe.io/Core/sdk/sdk_unity.git

  4. Xsolla Backend SDK should now be listed in the package manager.

  5. Next, see Configuration

Opt 2: Install From Local Disk#

  1. Clone the sdk_unity repo to your local machine:

    git clone https://source.goxbe.io/Core/sdk/sdk_unity.git

  2. Open your project in Unity and navigate to the Package Manager window (Windows > Package Manager).

  3. In the Package Manager window click the + button in the top left corner and select Add package from disk...

  4. Browse to the root folder of your local sdk_unity checkout, select the package.json file, and click Open.

  5. Xsolla Backend SDK should now be listed in the package manager.

Configuration#

In order for your game or application to communicate with an Xsolla Backend cluster you must first create a configuration asset to configure the SDK. This can be accomplished by creating a new Asset of type XBECoreSDK by selecting Assets > Create > Xsolla Backend > Core SDK. Once created, you will see the new object selected in the Project window and the configuration options shown in the Inspector window.

The most important setting is BaseUrl. This is the URL to your Xsolla Backend cluster that your app will communicate with.

The JWT settings are optional and only needed if you will be using the ClientSDK.LocalLogin() function. The JWT Settings section and LocalLogin function is provided for debugging purposes and is not recommended for production use. For production builds make sure that the JWTPassword field is blank.

The default values in the XBECoreSDK asset correspond to the Xsolla Backend demo environment.

Using the XBE Demo Env#

You can use the following settings to access Xsolla Backend’s demo environment. This environment is a shared environment that is reset daily and is intended for testing purposes only. You can use the demo environment to test your integration with the Xsolla Backend API before deploying your own cluster:

Global Settings
URL: https://api.demo.goxbe.cloud/v1

JWT Settings
Audience: demo.goxbe.cloud
Issuer: api.demo.goxbe.cloud
Password:

💡 Access the web admin console for the demo environment via https://admin.demo.goxbe.cloud

Note

The demo environment has a limited feature set that may result in runtime failures when using certain SDK services

API Access via XBECoreSDK#

Assign your desired XBECoreSDK configuration asset to a field on a behavior or scriptable object that’s referenced in your scene, and use the Instance property to access the CoreSDK features. The Instance property on XBECoreSDK will always return the same reference for a given XBECoreSDK asset.

Create a new XBEExample.cs script:

 1using xbe.sdk; // Required for XBECoreSDK, base Object, and other SDK types
 2using xbe.sdk.Models; // Required models such as User below
 3using xbe.sdk.Services; // Required for Services such as SessionService below
 4using System.Linq; // Not required, but used below for Linq where clause as an example
 5using UnityEngine; // Required for MonoBehaviour
 6
 7public class XBEExample : MonoBehaviour
 8{
 9    // Assign in the inspector
10    public XBECoreSDK config;
11
12    async void Start()
13    {
14        // Validate config is set
15        if (config == null)
16        {
17            // Warn if no configuration is set
18            Debug.LogWarning($"WARNING: XBECoreSDK config not set!");
19            return;
20        }
21
22        // Get core SDK instance from configuration
23        CoreSDK sdk = config.Instance;
24
25        // Print DeviceId (set) and logged in user UID (null)
26        Debug.Log($"Device: {sdk.DeviceId} | User: {sdk.LoggedInUser?.Uid}");
27
28        // Login using Device method
29        await sdk.LoginDevice();
30
31        // Print DeviceId (set) and logged in user UID (now set!)
32        Debug.Log($"Device: {sdk.DeviceId} | User: {sdk.LoggedInUser?.Uid}");
33
34        // Logged in user now non-null, let's inspect..
35        User localUser = sdk.LoggedInUser;
36
37        // Walk each property on the logged in user's object and print the value
38        foreach (var prop in localUser.Properties.Keys)
39            Debug.Log($"\t{prop}: {localUser.GetProperty(prop)}");
40
41        // Get the session service
42        var sessionService = sdk.GetService<SessionService>();
43
44        // Find all sessions
45        var sessions = await sessionService.FindAll();
46
47        // Filter results locally to non-empty sessions with Linq
48        var sessionsNonEmpty = sessions.Where(s => s.Users.Count() > 0).ToList();
49
50        // Print sessions found
51        Debug.Log($"Sessions found: {sessions.Count} ({sessionsNonEmpty.Count} non-empty)");
52
53        // Print info from each session
54        sessionsNonEmpty.ForEach(s =>
55            Debug.Log($"\t{s.Type}\t{s.Status}\t({s.Users.Count})\th:{s.HostUid}\ts:{s.ServerUrl ?? "NONE"}"));
56    }
57}

Enabling and Running Tests#

The SDK includes a suite of unit tests that can be run from within Unity. To enable the tests you must first add the com.unity.test-framework package at version 1.4.1 or greater to your project. To add or upgrade the package from the package manager:

  1. Open the Package Manager window (Windows > Package Manager) and clicking the + button in the top left corner.

  2. Select Add package by name...

  3. Set the Name field to com.unity.test-framework.

  4. Set the Version field to 1.4.1 or greater.

  5. Click Add.

Open your project’s Packages/manifest.json:

  1. verify that the com.unity.test-framework package is listed in the dependencies section (with an appropriate version)

  2. Find the testables array -> Add the com.xbe.sdk package name, as shown below:

1{
2	"dependencies": {
3		"com.xbe.sdk": "...",
4		"com.unity.test-framework": "1.4.1",
5	},
6	"testables": [
7		"com.xbe.sdk"
8	]
9}

Warning

The com.unity.test-framework package may be installed by default at a lower version; please make sure you verify the version number and upgrade, if necessary, or the tests will not run properly.

Once the com.xbe.sdk package has been added to the testables list, you can open the Test Runner window (Windows > General > Test Runner) and run the tests from the package by clicking the Run All button at the bottom right of the window, or by double-clicking on a particular test or group.

You can right-click any test and select Open Source Code to load the test code in your IDE, where you can sample from various use cases or debug any integration issues you might be experiencing.