A deep link is a special URL that directs the user not just to the main page of an application or website but directly to a specific section, page, or action.

Deep links can be used as an additional authentication method when logging in via user ID. If the game is installed on the user’s mobile device, they will be redirected to the game via deep link to get an authorization token.

User flow

In the mobile app

1. An unauthorized user in the Web Shop clicks the login button or the buy button. A modal window for entering the user ID or logging in through the mobile game opens.

2. The user clicks the Log in via Mobile Game button.
3. The user is redirected to the game and then automatically back to the Web Shop as an authorized user.

In the desktop version

1. An unauthorized user in the Web Shop clicks the login button or the buy button. A modal window for entering the user ID or logging into the mobile version of the game using a QR code opens.

2. The user scans the QR code using their mobile device.
3. The Web Shop opens on the user's mobile device.
4. The user is automatically redirected to the game and then back to the Web Shop as an authenticated user.

Services interaction flow

How to set up

On the game side

1. In your game’s mobile app settings, register a URL scheme to open the game via deep link:
   • in Android applications — in the AndroidManifest.xml file
   • in iOS applications — in the Info.plist file

After registering the scheme, when the user authenticates in the Web Shop via the game, the game should open at the specified address.

Example of a URL scheme to register a game:
gamename://authorize?operationPayload=<VALUE>, where:
• gamename — the name of your game that should open on a mobile device for user authentication.
• authorize — an example of an action name that should be performed after the gamename game opens. Use the action name that matches the actions in your application\’s operating system.
• operationPayload=<VALUE> — an additional parameter containing information for token generation during authentication.

Examples:

• Registering a URL scheme in iOS applications
• Registering a URL scheme in Android applications

Copy

Full screen

Small screen

• xml

<key>CFBundleURLTypes</key>
  <array>
    <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>gamename</string>
      </array>
    </dict>
  </array>

Copy

Full screen

Small screen

• xml

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="gamename" android:host="authorize" />
</intent-filter>

2. Implement the generation of an authorization token in JWT format using the user ID from the game.

Example of calling the user token generation API method using curl:

curl -X 'POST' \
'https://sb-user-id-service.xsolla.com/api/v1/user-id/token' \
-H 'accept: /' \
-H 'Content-Type: application/json' \
-d '{
 "loginId": "000001aa-001a-0ab0-00001-01a01a01a01a",
 "settings": {
   "projectId": 123456,
   "merchantId": 123456
 },
 "user": {
   "id": "123",
   "country": "US"
 }
 "operationPayload": "kosarb2NyrtIWaegJAH1f6P7XrBYPXYDya5coc_ZzcfiS_5o4QTUAL-CcGRC_Kv4CAtg"
}'

You will get a response like {token="JWT_TOKEN"}.

3. Add a pop-up window with a notification of successful authorization (optional).
4. Implement the opening of the Web Shop in the browser using the obtained user token.

Example of creating a URL for opening the Web Shop in the browser for an authorized user:
• https:​//example.com/?token={token}, if you are using a custom domain
• https:​//example.xsolla.site/?token={token}, if you are using an Xsolla domain

Where {token} is the user’s authorization token.

Within Site Builder

1. Open your project in Publisher Account and go to Site Builder.
2. Click Configure on the card of your Web Shop site with authentication via User ID.
3. Go to the Login Settings and select the User ID section.
4. Enable Deeplink authorization toggle.

5. In the Deeplink URL field enter the link for user authentication.

6. If you are using the Fast Login block on the site:
   1. Go to the Fast Login block.
   2. In the Layout section, enable the QR code toggle.

7. To check the authentication, click on Preview.
8. To publish the website, click on Publish.

A deep link is a special URL that directs the user not just to the main page of an application or website but directly to a specific section, page, or action.

Deep links allow the user to authenticate in the Web Shop through the game in one click, instead of going through the authentication process via user ID or Xsolla Login.

If the game is installed on the user’s mobile device, they will be redirected to the game via deep link to get an authorization token.

When a deep link is used as the primary authentication method, it allows saving payment details, which is not possible with authentication via user ID and deeplink. In this case, the deep link only speeds up authentication but does not add any new features.

User flow

In the mobile app

1. An unauthorized user in the Web Shop clicks the login button or the buy button. A modal window for logging in through the mobile game opens.

2. The user clicks the Log in via Mobile Game button.
3. The user is redirected to the game and then automatically back to the Web Shop as an authorized user.

In the desktop version

1. An unauthorized user in the Web Shop clicks the login button or the buy button. A modal window for logging into the mobile version of the game using a QR code opens.

2. The user scans the QR code using their mobile device.
3. The Web Shop opens on the user's mobile device.
4. The user is automatically redirected to the game and then back to the Web Shop as an authenticated user.

Services interaction flow

How to set up

On the game side

1. In your game’s mobile app settings, register a URL scheme to open the game via deep link:
   • in Android applications — in the AndroidManifest.xml file
   • in iOS applications — in the Info.plist file

After registering the scheme, when the user authenticates in the Web Shop via the game, the game should open at the specified address.

Example of a URL scheme to register a game:
gamename://authorize?operationPayload=<VALUE>, where:
• gamename — the name of your game that should open on a mobile device for user authentication.
• authorize — an example of an action name that should be performed after the gamename game opens. Use the action name that matches the actions in your application\’s operating system.
• operationPayload=<VALUE> — an additional parameter containing information for token generation during authentication.

Examples:

• Registering a URL scheme in iOS applications
• Registering a URL scheme in Android applications

Copy

Full screen

Small screen

• xml

<key>CFBundleURLTypes</key>
  <array>
    <dict>
      <key>CFBundleTypeRole</key>
      <string>Editor</string>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>gamename</string>
      </array>
    </dict>
  </array>

Copy

Full screen

Small screen

• xml

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="gamename" android:host="authorize" />
</intent-filter>

2. Implement the generation of an authorization token in JWT format using the user ID from the game.

Xsolla API uses Basic Authentication. All API requests must include the following header Authorization: Basic , where your_authorization_basic_key is a client_id:client_secret pair encoded in Base64 standard.

Setting up an OAuth 2.0 client for server authentication is done through the Publisher Account. For detailed steps, refer to the documentation.

Example of calling the user token generation API method using curl:

curl -X 'POST' \
'https://sb-user-id-service.xsolla.com/api/v1/user-id/token' \
-H 'Accept: /' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <Base64Encoded(client_id:client_secret)>' \
-d '{
 "loginId": "000001aa-001a-0ab0-00001-01a01a01a01a",
 "settings": {
   "projectId": 123456,
   "merchantId": 123456
 },
 "user": {
   "id": "123",
   "country": "US"
 }
 "operationPayload": "kosarb2NyrtIWaegJAH1f6P7XrBYPXYDya5coc_ZzcfiS_5o4QTUAL-CcGRC_Kv4CAtg"
}'

You will get a response like {token="JWT_TOKEN"}.

3. Add a pop-up window with a notification of successful authorization (optional).
4. Implement the opening of the Web Shop in the browser using the obtained user token.

Example of creating a URL for opening the Web Shop in the browser for an authorized user:
• https:​//example.com/?token={token}, if you are using a custom domain
• https:​//example.xsolla.site/?token={token}, if you are using an Xsolla domain

Where {token} is the user’s authorization token.

Within Site Builder

1. Open your project in Publisher Account and go to Site Builder.
2. Click Configure on your Web Shop site card.
3. Go to the Login Settings and select the Deep link section.

4. In the Deeplink URL field enter the link for user authentication.

5. If you are using the Fast Login block on the site:
   1. Go to the Fast Login block.
   2. In the Block Settings, adjust the display style for the QR code login button.

6. To check the authentication, click on Preview.
7. To publish the website, click on Publish.

User flow

1. The user goes to Web Shop with Xsolla Login authentication configured.
2. The user clicks the buy button for the selected item, the login button on the top bar, or the login button in the Fast Login block.
3. A modal window opens with authorization methods set up in Xsolla Login.

4. The user proceeds to authorization and enters additional data if necessary.
5. The system checks if the user exists in the game. If the user exists in the game, the user is authorized in Web Shop. Otherwise an error message is displayed.

How to get it

1. In the Builder for your site, go to the Login settings block.

2. Select the Xsolla Login authorization option.
3. In the drop-down list, select New Login.

4. Go to the Login project settings from the modal window or click Set up authentication method in the Xsolla Login block.

5. Connect user data storage.

Depending on the method of storing user data, different product functionality is available to you (see Comparison of user data storage options).

Xsolla storage

If you want the Login product to process all authentication logic, connect to Xsolla storage. More flexible settings will be available to you.

When you create a Login project, Xsolla storage is connected by default, no additional steps are required to configure it. If you have changed the default storage type and need to reconnect to Xsolla storage, follow these steps:

1. Go to the User database block and select the Storage section.
2. Select Xsolla storage and click Save changes.

PlayFab storage

If you want to use PlayFab functionality to work with users, connect to PlayFab storage. The storage saves the following user data:

• username
• user email address
• user password
• fields from an extended registration form if the form is set up

PlayFab storage gives you access to the following features:

• user registration
• authentication by email address or username and password
• authentication via Twitch
• user password reset
• user blocking

To connect the storage:

1. Go to the User database block and select the Storage section.
2. Select PlayFab.
3. In the Title ID field, enter the value of the same field from your PlayFab account.
4. Click Save changes.

Firebase storage

If you want to use Firebase functionality to work with users, connect to Firebase storage. This storage saves the following user data:

• username
• user email address
• user password
• fields from an extended registration form if the form is set up

1. Go to the User database block and select the Storage section.
2. Select Firebase.
3. In the API key field, enter the value of the same field from your Firebase account.
4. Click Save changes.

Custom storage

If you use your own authorization system and store user data on your application side, connect to custom storage.

The custom storage gives you access to the following features:

• user registration
• authentication by email address or username and password
• passwordless authentication by phone number
• authentication via social networks
• user password reset

1. Connect the custom storage.
2. Set up the processing of requests from the Xsolla Login server.

Connect custom storage

1. Go to the User database block and select the Storage section.
2. Select Custom storage.
3. Enter URLs where to send API requests:
   • User verification URL
   • New user URL
   • Password reset URL
   • Passwordless login with phone URL
   • Social login URL
4. Click Save changes.
5. For the URLs you have set, implement an API that will respond as follows:
   • HTTP 200 / HTTP 204 for successful requests. If required, a JSON containing additional user data can be placed in the response body. The passed data is written to a JWT (the partner_data parameter).
   • Other HTTP status codes for unsuccessful requests.

Set up processing of requests from Xsolla Login server

Xsolla Login server requests are sent to URLs, you specified in Publisher Account, with the Authorization: Bearer <JWT> header. The JWT is signed with the secret key of your project.

To process a request:

1. Validate a received JWT.
2. If the validation is successful, decode the JWT and make sure it includes the claims from the table below. Find and use a library for decoding.

{
  "exp": 1573635020,
  "iat": 1573634600,
  "iss": "https://login.xsolla.com",
  "request_type": "gateway_request",
  "xsolla_login_project_id": "00000000-0000-0000-0000-000000000000"
}