How to set up 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:
- The player links their platform accounts to the main account that is used to identify the player on different platforms.
- 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:
- The player enters the game on the game console platform for the first time.
- The game shows the message that offers to link the platform account to the main account.
- If the player confirms the action:
- They are redirected to the side application (e.g. the game website or mobile app), where they can authenticate or create the main account.
- After successful authentication in the app, the player receives an alphanumeric code for linking the accounts.
- The player returns to the console version of the game and enters the code.
- The main and platform accounts link and the game console shows the confirmation message.
- The player inventory on the platform synchronizes with the inventory linked to the main account.
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.
How to get it
To connect a cross-platform inventory:
- 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.
- Implement the account linking UI including:
- game server-based authentication and inventory management
- game client-based authentication and inventory management
- account linking methods
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:
- Integrate the Login widget with the app.
- 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.
- Implement authentication via the JWT on the game server side.
- 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.
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 OAuth 2.0 authentication and get a server access token.
client_id
and client_secret
, address the Account Manager of your project or contact us at am@xsolla.com.Request:
- php
<?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:
- php
{
"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 gamesocial_profile.user_id
— unique user identifier on the platform
Request:
- php
<?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:
- php
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Managing the player inventory in the game client
Inventory management methods include the following client methods:
To manage the player inventory on console platforms:
- 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.
- Implement the following steps on the game server to manage the user’s inventory in the console client:
- The game receives a server access token for user tokenization.
- The game receives JWT by
user_id
of the user on the platform and platform ID. - 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:
- js
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:
- js
{
"code": "123456"
}
Linking to the main account
Implement the Link accounts by code API method, where:
code
— linking codepublisher_project_id
— project ID from Publisher Accountuser_id
— user identifier on the platform
Make sure that you completed the following steps before calling the method:
- Implemented the UI for displaying the account linking code and the form for entering the received code.
- Implemented the method for getting a server access token.
- Implemented the method for getting the linking code.
Request:
- php
<?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:
- php
204 OK
Platform list
Platform | Platform ID | Comment |
---|---|---|
PlayStation Network | playstation_network | - |
XBox Live | xbox_live | - |
PC Standalone | pc_standalone | - |
Nintendo eShop | nintendo_shop | - |
Google Play | google_play | - |
Apple Store | app_store_ios | - |
Android Standalone | android_standalone | The game is published individually outside the stores. |
IOS Standalone | ios_standalone | The game is published individually outside the stores. |
Android Other | android_other | The game is published in an alternative store on PlayMarket. |
IOS Other | ios_other | The game is published in an alternative store on AppStore. |
PC Other | pc_other | - |
Xsolla | xsolla | - |
Was this article helpful?
Rate this page
Don’t want to answer
Thank you for your feedback!
Found a typo or other text error? Select the text and press Ctrl+Enter.