In-game purchases

Full Implementation

We have partnered with Xsolla to offer you the possibility to integrate in-game purchases more conveniently.

Warning

In-game purchases are an invite only feature. If you are interested in using them, please get in touch with us.

In-game purchases should be available only for the users that are signed in. Guest users should not be able to purchase items.

Getting started

When using the Xsolla SDK, and once you are invited to our Xsolla project dashboard, you will need one of the following ways of authentication:

• The token received from the GetXsollaUserToken() method from the SDK. This method generates a custom Xsolla token that you use with the Xsolla SDK. The purchases are linked to the CrazyGames user account (see Account integration requirements). (Please note that you should create a game on the developer portal so we can generate credentials for the token).
• Alternatively, you can generate the necessary Xsolla credentials on your own within our Xsolla project dashboard, and use the SDK with the generated credentials. Purchases will be linked to your in-game user accounts (see Account integration requirements). You can also skip the rest of this guide.

Get Xsolla token

HTML5Unity

To use Xsolla via our own custom-generated token, you can retrieve the Xsolla token like this:

try {
    const token = await window.CrazyGames.SDK.user.getXsollaUserToken();
    console.log("Get Xsolla token result", token);
} catch (e) {
    console.log("Error:", e);
}

To use Xsolla via our own custom-generated token, the only Xsolla SDK setup required is adding the Project ID, which will be provided by us.

Install the Xsolla Unity SDK can here.

You don't need any additional Xsolla setup, or to handle Xsolla login, since Xsolla will automatically handle the user account creation with the user ID included in token, which is the ID of the CrazyGames user. Thus, all the purchases made using the token will be also linked to the CrazyGames user account.

You can retrieve the Xsolla token like this:

CrazySDK.User.GetXsollaUserToken((error, token) =>
{
    if (error != null)
    {
        Debug.LogError("Get Xsolla user token error: " + error);
        return;
    }
    Debug.Log("Xsolla user token: " + token);
});

We recommend that you retrieve the token every time before using it, since the tokens are usually short-lived, for example only 1 hour. Our SDK handles the token refresh.

After retrieving the token, you can use it like this:

HTML5Unity

// obtain player's inventory example
// xsollaProjectId will be provided by us
const resp = await fetch(
    `https://store.xsolla.com/api/v2/project/${xsollaProjectId}/user/inventory/items`,
    {
        method: "GET",
        headers: {
            Authorization: `Bearer ${token}`,
        },
    }
);

XsollaToken.Create(token);

You don't need to handle any Xsolla login functionality, since Xsolla will automatically handle the user account creation with the user ID included in the token, which is the ID of the CrazyGames user. Thus, all the purchases made using the token will be also linked to the CrazyGames user account.

You can now call the methods from the Xsolla SDK, for example XsollaCatalog.Purchase(...).

Registering orders

For the typical use case, you will use the in-game-store API Xsolla offers. Have a look at

• In-game store Integration Handbook
• In-game store API documentation

Testing

The GetXsollaUserToken() method will work only on CrazyGames.com. Please notice that the QA Tool can be accessed by selecting your game in Developer Portal.

For the initial testing, we recommend testing with sandbox orders, which allow purchasing items with fake money. When you submit the game, please ensure the sandbox orders are disabled.

Order tracking

Order tracking through our SDK is optional.

When using Xsolla, you will mostly deal with 3 order statuses:

• new
• done
• canceled

Every time an order has been successfully completed (done), call our analytics module:

HTML5Unity

// order must be a JSON object
window.CrazyGames.SDK.analytics.trackOrder("xsolla", order);

XsollaCatalog.Purchase(skuField.text, orderStatus =>
    {
        CrazySDK.Analytics.TrackOrder(PaymentProvider.Xsolla, orderStatus);
    },
    error => { Debug.LogError($"Failed to buy, Error: {error.errorMessage}"); }
);

You can obtain the order for example from the Xsolla Order endpoint

We also encourage you to track the new and canceled orders, as these may be useful in the future.