Cross-platform Inventory

How It Works

Cross-platform Inventory allows game developers to synchronize a user inventory within a game on different platforms (Steam, EGS, PlayStation, XBox, etc.), manage user inventory and balance, and collect data about them.

The following steps ensure the synchronization:

  1. The player links their platform accounts to the main account that is used to identify the player on different platforms.
  2. Xsolla provides the mechanism for linking platform accounts to the main account and managing the cross-platform inventory synchronization.

The solution includes the following components:

  • game client
  • game server
  • web application with an account linking UI
  • Xsolla Login for providing the main account and a linking mechanism
  • Xsolla Player Inventory for storing the user inventory

User Flow

To link a platform account (Steam or EGS) to the main account, you need to implement user identification in the game by using the Xsolla Login account or the algorithm for linking accounts on game console platforms.

The algorithm for linking the game console account to the main account is the following:

  1. The player enters the game on the game console platform for the first time.
  2. The game shows the message that offers to link the platform account to the main account.
  3. If the player confirms the action:
    1. They are redirected to the side application (e.g. the game website or mobile app), where they can authenticate or create the main account.
    2. After successful authentication in the app, the player receives an alphanumeric code for linking the accounts.
  4. The player returns to the console version of the game and enters the code.
  5. The main and platform accounts link and the game console shows the confirmation message.
  6. The player inventory on the platform synchronizes with the inventory linked to the main account.

Note: The premium currency (currency purchased for real money) does not synchronize in the inventories. According to the console platforms regulations, premium currency purchased via PlayStation, Xbox, and Nintendo Switch game consoles does not stack and is stored separately.
Notice: You cannot unlink the accounts once they are linked. Also, if the user refuses to link the account when entering the game for the first time, they will not be able to link them in the future.

Who Can Use It

Game developers who plan a multi-platform release of their game and want to establish a loyal player base by giving players access to their purchases and rewards on any platform.

Note: The solution can be connected only before the game is released on a second publishing platform. For example, if the game has released on a PC platform and is going to release on PlayStation, you need to connect the cross-platform inventory before it releases on PlayStation.

How to Get It

To connect a cross-platform inventory:

  1. Connect the Player Inventory. Implement basic access authentication for working with the server methods, and Xsolla Login authentication based on the OAuth 2.0 protocol for working with the client methods. OAuth 2.0 protocol based authentication is also required for accessing the Login API methods and implementing the account linking methods.
  2. Implement the account linking UI including:
    1. game server-based authentication and inventory management
    2. game client-based authentication and inventory management
    3. account linking methods

Note: If you have already implemented the account synchronization on the game server side, setting up the Player Inventory will be enough for the user inventory synchronization.

Account Linking UI

The account linking UI should provide the following abilities:

  • ability to show a message offering to link a platform account to the main account
  • ability to agree or refuse to link the accounts
  • ability to submit the code for linking the accounts if the user agrees to link them
  • ability to display the URL to the mobile or web application that is used to link the accounts

The mechanism for authenticating users in the main account is the following:

  1. Integrate the Login widget with the app.
  2. A JWT is passed to the app when the user authenticates via the widget. Implement the ability to pass a JWT from the app to the method for getting the linking code and displaying the code in the app UI.
  3. Implement authentication via the JWT on the game server side.
  4. Implement passing a token, user_id on the console platform, and the platform ID to the method for linking to the main account when the user enters the console version of the game and submits the code for linking the accounts.

Note: If you want to export the existing accounts to the Xsolla storage, address the Account Manager of your project or contact us at am@xsolla.com.

Authentication on the Game Server

In order to access the Login API methods for managing the player inventory on the game server, you need to set up OAuth2.0 authentication and get a server access token.

Note: To get client_id and client_secret, address the Account Manager of your project or contact us at am@xsolla.com.

Request

Copy
Full screen
Small screen
<?php
$uri = 'https://login.xsolla.com/api/oauth2/token';
$body = [
    'grant_type' => 'client_credentials',
    'client_id' => 1,
    'client_secret' => 'client_secret'
];

$headers = [
    'Content-type: application/x-www-form-urlencoded'
];

$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, http_build_query($body));

curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);
print_r($response);

Response

Copy
Full screen
Small screen
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",           
    "token_type":"bearer",
    "expires_in":3600,
    "scope": ""
}

Managing the Player Inventory on the Game Server

Inventory management methods include the following server methods:

It is necessary to pass the user_id of the user on the platform and the platform ID to these methods.

Authentication on the Game Client

Implement the Auth by Custom ID API method to manage the player inventory in the game client. Pass the following parameters in the request:

  • server_custom_id — unique user identifier in the game
  • social_profile->user_id — unique user identifier on the platform

Request

Copy
Full screen
Small screen
<?php
$uri = 'https://login.xsolla.com/api/users/login/server_custom_id';
$queryParams = [
    'publisher_project_id' => 44056
];
$queryParamsString = '?' . http_build_query($queryParams);

$body = '
    {
        "server_custom_id": "1234567890asdfghjkl",
        "social_profile": {
          "platform": "xbox_live",
          "user_id": "4352354"
        }
    }
';

$headers = [
    'Content-type: application/json',
    'x-server-authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
];

$request = curl_init($uri . $queryParamsString);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);

Response

Copy
Full screen
Small screen
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Note: You can also use the User tokenization method to get a JWT.

Managing the Player Inventory in the Game Client

Inventory management methods include the following client methods:

To manage the player inventory on console platforms:

  1. Implement passing of the platform ID to client methods in order to store premium currency balance on the console publishing platforms according to the console platforms regulations.
  2. Implement the following steps on the game server to manage the user’s inventory in the console client:
    1. The game receives a server access token for user tokenization.
    2. The game receives JWT by user_id of the user on the platform and platform ID.
    3. The game passes JWT to the specified client methods.

Account Linking Methods

Getting the Linking Code

Implement the Create Code for Linking Accounts API method to get the linking code and pass it to the user.

Request

Copy
Full screen
Small screen
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
    if (this.readyState === this.DONE) {
        console.log(this.responseText);
    }
});
xhr.open("GET", "https://login.xsolla.com/api/users/account/code");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);

Response

Copy
Full screen
Small screen
{
  "code": "123456"
}

Linking to the Main Account

Implement the Link Accounts by Code API method, where:

  • code — linking code
  • publisher_project_id — project ID from Publisher Account
  • user_id — user identifier on the platform

Make sure that you completed the following steps before calling the method:

  1. Implemented the UI for displaying the account linking code and the form for entering the received code.
  2. Implemented the method for getting a server access token.
  3. Implemented the method for getting the linking code.

Note: You can also use the Connect game account to Xsolla API method to link the platform account to the main account.

Request

Copy
Full screen
Small screen
<?php
$uri = 'https://login.xsolla.com/api/users/account/link';
$body = '
    {
        "code": "234155",
        "platform": "xbox_live",
        "publisher_project_id": "12423354",
        "user_id": "4352354"
    }
';

$headers = [
    'Content-type: application/x-www-form-urlencoded',
    'x-server-authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
];

$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($request);

Response

Copy
Full screen
Small screen
204 OK

Platform List

PlatformPlatform IDComment
PlayStation Networkplaystation_network-
XBox Livexbox_live-
PC Standalonepc_standalone-
Nintendo eShopnintendo_shop-
Google Playgoogle_play-
Apple Storeapp_store_ios-
Android Standaloneandroid_standaloneThe game is published individually outside the stores.
IOS Standaloneios_standaloneThe game is published individually outside the stores.
Android Otherandroid_otherThe game is published in an alternative store on PlayMarket.
IOS Otherios_otherThe game is published in an alternative store on AppStore.
PC Otherpc_other-
Xsollaxsolla-