Autenticación
OAuth 2.0 uses short-lived tokens with long-term authorization (refresh tokens) instead of long-lived tokens. A refresh token allows users to stay in your application for an extended period of time without needing to re-enter their username and password. This eliminates the risk of compromising user authentication data.
Set up OAuth 2.0 for authorization:
- via username or email and password
- via social networks
- via Steam
If the option is enabled, user registration and authentication is carried out by calling the Awake
method is called. The method checks the expiration of the current refresh token.
To configure OAuth 2.0 authorization:
- Set up OAuth 2.0 authentication for Login project in your Publisher Account.
- Set up asset in your Unity project.
Configure la autenticación OAuth 2.0 para el proyecto de Inicio de sesión (Login) en su Cuenta del editor
- Go to your Publisher Account.
- Click Login in the side menu.
- Click Configure in the Login project pane.
- Go to the Security block and select the OAuth 2.0 section.
- Click Add OAuth 2.0.
- Specify OAuth 2.0 redirect URIs and click Connect.
- Copy and save the Client ID.
Establecer recurso en su proyecto de Unity
- Go to your Unity project.
- Click
Window > Xsolla > Edit Settings in the main menu. - In
Inspector panel:- In the
Authorization method field, selectOAuth2.0 . - In the
OAuth2.0 client ID field, specify Client ID received when setting up OAuth 2.0 in Publisher Account.
- In the
The following methods are implemented in Login & Account System asset to work with refresh tokens:
IsOAuthTokenRefreshInProgress
— returnstrue
during refresh token process, false otherwise.ExchangeCodeToToken
— exchanges the user’s authentication code for a valid JWT.
The oauthState
argument found in the GetSocialNetworkAuthUrl
method is used for additional user verification during OAuth 2.0 authentication. This argument is used to mitigate possible CSRF attacks.
Use this how-to when working only with the following assets:
- Game Commerce
- Cross-Buy
Cross-Buy asset will be deprecated in April 2022. You can continue to use it, but it will not be updated and supplemented with new features. It is recommended to switch to the Game Commerce asset. It contains all the classes and methods needed to work with Xsolla products.
You can integrate Game Commerce and Cross-Buy assets with your own login system. To do this, implement user authentication in your application via Pay Station access token.
The flow of interaction with Xsolla servers when using your own authorization system:
- Your client sends an authentication request to your server.
- Your server authorizes the user and sends a request to the Xsolla server to receive the Pay Station access token.
- Xsolla server returns the Pay Station access token.
- Your server passes the Pay Station access token to the client.
- SDK methods use the received Pay Station access token as an authorization token to open an in-game store, make a payment, and manage inventory.
Obtener un token de acceso a Pay Station
On the back end of your application, implement a method to obtain a Pay Station access token using an HTTP POST request.
Xsolla API uses basic HTTP authentication. The request must contain the Authorization: Basic <your_authorization_basic_key>
header, where <your_authorization_basic_key>
is the merchant_id:api_key
encoded according to the Base64 standard. You can find the parameter values in Publisher Account:
- for
merchant_id
, go to the Project settings > Webhooks > Merchant ID section. - for
api_key
, go to the Company settings > API key section.
HTTP request:
http
- http
- curl
- php
- C#
- python
- ruby
- java
- javascript
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token
Headers:
Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json
Body:
{
"purchase": {
"virtual_currency": {
"quantity": 100
},
"virtual_items": {
"items": [
{
"amount": 1,
"sku": "SKU01"
}
]
}
},
"settings": {
"currency": "USD",
"language": "en",
"project_id": 16184,
"ui": {
"components": {
"virtual_currency": {
"custom_amount": true
}
},
"desktop": {
"virtual_item_list": {
"button_with_price": true,
"layout": "list"
}
},
"size": "medium"
}
},
"user": {
"country": {
"allow_modify": true,
"value": "US"
},
"age": 19,
"email": {
"value": "john.smith@mail.com"
},
"id": {
"value": "user_2"
},
"name": {
"value": "John Smith"
}
}
}
curl --request POST \
--url https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
--header 'authorization: Basic <your_authorization_basic_key>' \
--header 'content-type: application/json' \
--data '{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"age":19,"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}'
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"age":19,"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}');
$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Basic <your_authorization_basic_key>',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import http.client
conn = http.client.HTTPSConnection("api.xsolla.com")
payload = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"
headers = {
'content-type': "application/json",
'authorization': "Basic <your_authorization_basic_key>"
}
conn.request("POST", "/merchant/v2/merchants/{merchant_id}/token", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic <your_authorization_basic_key>'
request.body = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"age\":19,\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}");
Request request = new Request.Builder()
.url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")
.post(body)
.addHeader("content-type", "application/json")
.addHeader("authorization", "Basic <your_authorization_basic_key>")
.build();
Response response = client.newCall(request).execute();
var data = JSON.stringify({
"user": {
"id": {
"value": "user_2"
},
"name": {
"value": "John Smith"
},
"age": 19,
"email": {
"value": "john.smith@mail.com"
},
"country": {
"value": "US",
"allow_modify": true
}
},
"settings": {
"project_id": 16184,
"currency": "USD",
"language": "en",
"ui": {
"size": "medium",
"desktop": {
"virtual_item_list": {
"layout": "list",
"button_with_price": true
}
},
"components": {
"virtual_currency": {
"custom_amount": true
}
}
}
},
"purchase": {
"virtual_currency": {
"quantity": 100
},
"virtual_items": {
"items": [
{
"sku": "SKU01",
"amount": 1
}
]
}
}
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");
xhr.send(data);
To get the token, pass the following parameters in the request body:
Parameter | Type | Description |
---|---|---|
settings | object | Custom project settings (object). |
settings.project_id | integer | Game’s Xsolla ID. Can be found in Publisher Account beside the name of your project. Required. |
user | object | User details (object). |
user.id | object | User ID in your authorization system (object). |
user.id.value | string | User ID. Required. |
user.email | object | User email (object). |
user.email.value | string | User email. Must be valid according to the RFC 822 protocol. Required. |
user.name | object | User screen name (object).Required. |
user.name.value | string | User screen name |
user.steam_id | object | User Steam ID (object). |
user.steam_id.value | string | User Steam ID. Required if the application is published on Steam. |
user.playfab_id | object | User PlayFab ID (object) |
user.playfab_id.value | string | User PlayFab ID. Required if the application uses PlayFab services to grant items. |
See examples of requests and responses in the API reference.
custom_parameters
, purchase
, etc.), they are not intended to receive an authorization token.Utilizar el JWT de usuario
To use the Pay Station access token to open an in-game store, make a payment, and manage inventory, pass it to the XsollaLogin.Instance.Token
and XsollaStore.Instance.Token
properties in the SDK methods.
See examples of using the authorization token in the tutorials:
- Sell virtual items for real currency
- Sell virtual items for virtual currency
- Display of virtual currency balance
- Display of items in inventory
Implement the logic of receiving a new Pay Station access token after its expiration. It is recommended that you get a new token in the background mode, so the user doesn’t have to log in to the application again.
Native authentication lets users log in to your application via a social network account configured on a mobile device.
The first time a user logs in, the social networking application is launched and asks for permission to authenticate the user. After that, authentication is performed automatically without requiring the user to do anything.
Currently, SDK has implemented native authentication via the following social networks:
To configure native authentication:
- Create your Unity project build for Android.
- Configure the application in the developer account for the social network:
- For authentication via Facebook:
- Register and create a new application.
- Set up the application page in your Facebook developer account.
- For authentication via Google, set up the project in Google API Console.
- For authentication via WeChat:
- Register and create a new application.
- Submit the application for review.
- For authentication via QQ:
- Register and create a new application.
- Submit the application for review.
- For authentication via Facebook:
- Set up authentication via social networks on the Xsolla side:
- For Facebook and Google, set up social connections in Publisher Account.
- For WeChat and QQ, contact your Account Manager.
- Set up the asset for your Unity project.
Crear compilación de un proyecto de Unity para Android
- Go to your Unity project.
- Click
File > Build settings in the main menu. - Click
Android in thePlatform panel. - Click
Build . - Make sure that the hash key is formed:
- Click
Window > Xsolla > Edit Settings in the main menu. - Make sure that the hash key appears in the
Android debug hash key field.
- Click
For further native authentication configuration you will need:
Package Name found in theInspector panel after selecting the Android platform inFile > Build settings .Android class name found inWindow > Xsolla > Edit Settings > Inspector > Android class name .Android debug hash key found inWindow > Xsolla > Edit Settings > Inspector > Android debug hash key .
Establezca la página de la aplicación en su cuenta de desarrollador de Facebook
- Go to project settings in the Facebook developer account.
- Go to Settings > Basic.
- Click Add Platform and select Android.
- Specify
Package Name from your Unity project in the Google Play Package Name field. - Specify
Android class name from your Unity project in the Class Name field. - Specify
Android debug hash key from your Unity project in the Key Hashes filed. - Click Save Changes.
For further native authentication configuration, you will need App ID and App Secret found in project settings in Settings > Basic section.
Configurar un proyecto en Google API Console
- Go to Google API Console.
- Click New Project.
- Specify Project name and Location and click Save.
- Go to the created project and click OAuth consent screen in the side menu.
- Select External option and click Create.
- Specify the necessary parameters and click Save.
- Click Credentials in the side menu.
- Create an OAuth 2.0 client for your Unity application:
- Click Create credentials and select OAuth client ID.
- Specify Android in the Application type field.
- Specify Name.
- Specify
Package Name from your Unity project in the Package name field. - Specify
Android debug hash key from your Unity project in the SHA-1 certificate fingerprint field. - Click Create.
- Click OK.
- Create an OAuth 2.0 client for the web application:
- Click Create credentials and select OAuth client ID.
- Specify Web application in the Application type field.
- Specify Name.
- Click Add URI in the Authorized redirect URIs section and specify
https://login.xsolla.com/api/social/oauth2/callback
URI. - Click Create.
- Click OK.
For further native authentication configuration, you will need Client ID and Client Secret found in settings of the Client ID for the web application.
Establecer las conexiones de redes sociales para el proyecto de Login en Cuenta del editor de Xsolla
- Open your project in Publisher Account.
- Click Login in the side menu and go to Login projects > your Login project > Social connections.
- To set up authentication via Facebook:
- Click Edit in the Facebook panel and change status to Disconnected.
- Specify the App ID from the Facebook developer account in the Application ID field.
- Specify App Secret from the Facebook developer account in the Application Secret field.
- Click Connect.
- To set up authentication via Google:
- Click Edit in the Google panel and change status to Disconnected.
- Specify the Client ID for a web application from the Google API Console in the Application ID field.
- Specify the Client Secret for a web application from the Google API Console in the Application Secret field.
- Click Connect.
Establecer activo para su proyecto de Unity
- Go to your Unity project.
- Click
Window > Xsolla > Edit Settings in the main menu. - Specify the application ID:
- Specify App ID from the Facebook developer account in the
Facebook App ID field. - Specify Client ID for a web application from the Google API Console in the
Google server ID field. - Specify AppID from the WeChat application settings in the
WeChat App ID . - Specify AppID from the QQ application settings in the
QQ App ID .
- Specify App ID from the Facebook developer account in the
Native authentication allows players to enter your application via the installed Steam application.
To set up native authentication:
- Set up silent authentication via Steam in Publisher Account.
- Configure your Unity project.
- Configure processing of events.
- Ensure authentication via Steam.
Configurar su proyecto de Unity
- Manually create a
steam_appid.txt
file and type your application ID in Steam there. Then, place this file to theAssets
catalog of your project.
steam_appid.txt
file in the Assets
catalog. This file includes the application ID in Steam for a demo project.- Open your Unity project.
- In the main menu, go to
Window > Xsolla > Edit Settings . - In the
Inspector panel:- Check the
Use Steam authorization box. - In the
Steam App ID field, specify your application ID in Steam. The value should be the same as the value in thesteam_appid.txt
file.
- Check the
Configurar el procesamiento de los eventos
To authenticate users via Steam, you should get a session ticket
via the SteamAuth
method. Pass the received value when calling the RequestTokenBy
method. As a result, you get the token that is used when calling the API.
Garantizar la autenticación a través de Steam
- Create the build of your Unity project for a stand-alone platform.
- Launch Steam and log in.
- Launch your application. If everything is correct, the Steam pop-up window appears.
Token invalidation allows for improved security of user authentication data in your application. If the option is enabled, a new token replaces the old one that becomes invalid every time the user authenticates.
When using SDK, invalidation of the existing token and generation of a new one is made by calling with_logout
parameter has the 1
value.
To enable token invalidation in your Unity project:
- In the main menu, go to
Window > Xsolla > Edit Settings . - In the
Inspector panel, check theEnable JWT invalidation box.
You can use Xsolla Launcher to deliver your application to users and update it. The Launcher contains a built-in authorization tool. To avoid the need to re-enter username and password, set up authorization in your application via the Launcher.
Configurar el SDK y Launcher para que funcionen juntos
- Set up Launcher in your Publisher Account.
config.json
file, it is enough to change the values for the following objects:launcher_project_id
— specify Launcher ID found in Publisher Account > Launcher > General settings > General infologin_project_id
— specify Login ID found in Publisher Account > Launcher > General settings > Authentication
- Implement the Launcher authorization logic in your application.
- Generate a launcher installation file and a build archive.
- Create an application build.
- Upload the application build to the Xsolla update server.
Implementar la lógica para la autenticación mediante Launcher
The flow for authorization in the application via Launcher is as follows:
- The user is authorized in Launcher.
- The user installs and runs the application.
- Launcher runs the application and passes user parameters via the command line. The authorization token is passed in the
xsolla-login-token
parameter. - The application processes command line parameters and obtains a token. An example of a token processing script can be viewed in the demo project.
- The application validates the received token. An example of a token validation script can be viewed in the demo project.
- The application automatically authorizes the user without displaying an authorization page. An example of a user authorization script can be viewed in the demo project.
XsollaLogin.Instance.Token
and XsollaStore.Instance.Token
properties.Crear una compilación de la aplicación
- Go to your Unity project.
- Click
Window > Xsolla > Edit Settings in the main menu. In theInspector panel:- In the
Project ID field, specify the Project ID found in Publisher Account > Project settings > Project ID. - In the
Login ID field, specify the Login ID found in Publisher Account > Launcher > General settings > Authentication.
- In the
- Run the user authorization scene, where the token is processed.
- Click
File > Build settings in the main menu and then clickAdd Open Scenes . Make sure the authorization scene is added first in the list. - Click
Build . - In the pop-up window, specify the path to the directory where the finished build will be placed.
Device ID authentication lets users start using the application on a mobile device without entering registration data. The first time a user logs in to the application using the device ID, a new account is created automatically, and the user doesn’t need to enter a username, email address, or other data.
With the device ID, you can implement user authentication on one or more mobile devices in the background mode. To use this function, the user should link the device ID to an existing account.
The SDK supports authentication via ID of mobile devices on Android and iOS.
Obtener ID de dispositivo
The device ID is generated by the platform and is available to applications installed on the mobile device. The SDK gets the ID value using the platform API and uses this value to perform various functions using the Xsolla API.
The iOS device ID is passed in the UIDevice.identifierForVendor property. The standard Unity method SystemInfo.deviceUniqueIdentifier is used to determine the ID.
The Android device ID is passed in the android.provider.Settings.Secure.ANDROID_ID constant. The SDK uses its own logic to determine the ID because the standard Unity method returns the Android device ID as an MD5 hash, which is inappropriate for Xsolla API calls.
Métodos del SDK
The SDK implements methods for the following functions:
Autenticación
SDK method name | Description |
---|---|
AuthViaDeviceID | Authenticates the user to the application using the current device ID. |
Actualización de cuenta
SDK method name | Description |
---|---|
AddUsernameEmailAuthToAccount | Adds a username, email address, and password, that can be used for authentication, to the current account. |
LinkSocialProvider | Links a social network, that can be used for authentication, to the current account. |
Administración de dispositivos
SDK method name | Description |
---|---|
GetUserDevices | Returns a list of devices linked to the current user account. |
LinkDeviceToAccount | Links the specified device to the current user account. |
UnlinkDeviceFromAccount | Unlinks the specified device from the current user account. |
¿Has encontrado una errata u otro error de texto? Selecciona el texto y pulsa Ctrl+Intro.