Set up user authentication

User flow

1. The user goes to Web Shop with user ID authentication configured.
2. The user authorizes in the Web Shop in one of the following ways:
   • The user enters their ID in the Fast Login block and clicks the login button.
   • The user clicks the buy button for the selected item or the login button on the top bar:
     1. A modal window for entering the user ID or logging in through a social network opens.
     2. User enters their ID and clicks Continue or clicks on the social networks icon to choose a social network and completes authentication on the social network page.

3. The system checks if a user exists in the game. If a user with this ID or social account exists in the game, the user is authorized in the Web Shop. Otherwise an error message is displayed.

How to get it

1. On your application’s side, implement handling of the user validation webhook. When receiving a webhook, the application should do the following:
   • Search for a user by their ID passed in the webhook.
   • Depending on the result, send one of the following status codes:
     • 200 HTTP-code with an answer from webhook if a user is found
     • 404 HTTP-code if the user ID is not found
   • Send user attributes for personalization.

4. If your site includes multiple pages, select the one you need:
   1. Click the current page title at the top of the builder.
   2. Select the necessary page from the drop-down list.
5. Go to the Login settings block.

6. Select the User ID option.

7. In the drop-down list, select New Login.

1. 4. To set up a social network, go to the social network card, click the ⚙ icon to the right of the title, and select Connect.

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

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
    participant U as User
    participant WS as Web Shop
    participant B as Browser
    participant MOS as Mobile OS
    participant G as Game
    participant LA as Login API
    U->>WS: Clicks button to log in via mobile game
    activate WS
    WS->>B: Redirects user via deeplink
    activate B
    B->>MOS: Makes system call to open mobile game
    activate MOS
    MOS->>G: Opens mobile game
    activate G
    G->>LA: Generates authorization token
    activate LA
    LA-->>G: Returns authorization token
    deactivate LA
    G->>MOS: Makes system call to open browser with token in URL
    deactivate G
    MOS-->>B: Opens browser with token in URL
    deactivate MOS
    B-->>WS: Opens Web Shop page for authorized user
    deactivate B
    WS-->>U: Displays username in header
    deactivate WS

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 link to open the game via a registered URL scheme:

scheme://authorize?operationPayload=<VALUE>, where:
• scheme — a unique identifier of your game used in a custom URL scheme to launch the app and navigate to the required action.
• authorize — an example of an action name that should be performed after the game opens. Use the action name that matches the actions in your application’s operating system.
• operationPayload=<VALUE> — a parameter that contains information for token generation during authentication. The value is a Base64-encoded data generated by Xsolla.

Examples:

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

Copy

Full screen

Small screen

• xml

 1<key>CFBundleURLTypes</key>
 2  <array>
 3    <dict>
 4      <key>CFBundleTypeRole</key>
 5      <string>Editor</string>
 6      <key>CFBundleURLSchemes</key>
 7      <array>
 8        <string>scheme</string>
 9      </array>
10    </dict>
11  </array>

Copy

Full screen

Small screen

• xml

1<intent-filter>
2    <action android:name="android.intent.action.VIEW" />
3    <category android:name="android.intent.category.DEFAULT" />
4    <category android:name="android.intent.category.BROWSABLE" />
5    <data android:scheme="scheme" android:host="authorize" />
6</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:

 1curl -X 'POST' \
 2'https://sb-user-id-service.xsolla.com/api/v1/user-id/token' \
 3-H 'accept: /' \
 4-H 'Content-Type: application/json' \
 5-d '{
 6 "loginId": "000001aa-001a-0ab0-00001-01a01a01a01a",
 7 "settings": {
 8   "projectId": 123456,
 9   "merchantId": 123456
10 },
11 "user": {
12   "id": "123",
13   "country": "US"
14 }
15 "operationPayload": "kosarb2NyrtIWaegJAH1f6P7XrBYPXYDya5coc_ZzcfiS_5o4QTUAL-CcGRC_Kv4CAtg"
16}'

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

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

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
    participant U as User
    participant WS as Web Shop
    participant B as Browser
    participant MOS as Mobile OS
    participant G as Game
    participant LA as Login API
    U->>WS: Clicks button to log in via mobile game
    activate WS
    WS->>B: Redirects user via deeplink
    activate B
    B->>MOS: Makes system call to open mobile game
    activate MOS
    MOS->>G: Opens mobile game
    activate G
    G->>LA: Generates authorization token
    activate LA
    LA-->>G: Returns authorization token
    deactivate LA
    G->>MOS: Makes system call to open browser with token in URL
    deactivate G
    MOS-->>B: Opens browser with token in URL
    deactivate MOS
    B-->>WS: Opens Web Shop page for authorized user
    deactivate B
    WS-->>U: Displays username in header
    deactivate WS

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 link to open the game via a registered URL scheme:

scheme://authorize?operationPayload=<VALUE>, where:
• scheme — a unique identifier of your game used in a custom URL scheme to launch the app and navigate to the required action.
• authorize — an example of an action name that should be performed after the game opens. Use the action name that matches the actions in your application’s operating system.
• operationPayload=<VALUE> — a parameter that contains information for token generation during authentication. The value is a Base64-encoded data generated by Xsolla.

Examples:

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

Copy

Full screen

Small screen

• xml

 1<key>CFBundleURLTypes</key>
 2  <array>
 3    <dict>
 4      <key>CFBundleTypeRole</key>
 5      <string>Editor</string>
 6      <key>CFBundleURLSchemes</key>
 7      <array>
 8        <string>scheme</string>
 9      </array>
10    </dict>
11  </array>

Copy

Full screen

Small screen

• xml

1<intent-filter>
2    <action android:name="android.intent.action.VIEW" />
3    <category android:name="android.intent.category.DEFAULT" />
4    <category android:name="android.intent.category.BROWSABLE" />
5    <data android:scheme="scheme" android:host="authorize" />
6</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:

 1curl -X 'POST' \
 2'https://sb-user-id-service.xsolla.com/api/v1/user-id/token' \
 3-H 'Accept: /' \
 4-H 'Content-Type: application/json' \
 5-d '{
 6 "loginId": "string",
 7 "settings": {
 8   "projectId": 0,
 9   "merchantId": 0
10 },
11 "user": {
12   "id": "string",
13   "country": "string",
14   "name": "string",
15   "picture": "string"
16 },
17 "operationPayload": "eyJ4c29sbGF1aWQiOiIzNzE5Nzc5NjU1MDE2Nzc2MzcifQ%3D%3D"
18}'

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

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.
4. The user proceeds to authorization and enters additional data if necessary.
5. The system checks if the user exists in the game. If so, the user is authorized in Web Shop. Otherwise an error message is displayed.

How to get it

2. Click the ••• icon on the card of your Web Shop site with Xsolla Login authentication and select Configure.
3. Click Go to Builder and scroll to the Login settings block.

4. Select the Xsolla Login authorization method.

5. In the Xsolla Login option, select an authentication option from the drop-down list:
   • an existing one, if Xsolla Login is already configured in your project
   • New Login, if there is no authentication option for Web Shop yet

When you preview or publish the site for the first time, the Web Shop preview URL and domain are automatically added to the Callback URL field in the authentication option settings. The user is redirected to these URLs in the following cases:

• after successful authentication
• after email confirmation
• after password reset
• in case of authentication failure

When you change the Web Shop domain, these URLs are updated automatically.

6. Set up the social networks that users can use to sign in to Web Shop (optional). For more information, see the Social login documentation.

7. If you do not want to store user data on Xsolla’s side, connect another storage (optional). For more information, see the Connect user data storage documentation.

The available functionality depends on the selected storage. For more information, see the Comparison of user data storage options documentation.

User flow

1. The user goes for the first time to Web Shop with configured authentication with linked user ID.
2. The user clicks the purchase 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. After successful authorization via Xsolla Login, the modal window for linking user ID from the game opens.

6. The system checks if the user exists. If the user with the specified ID exists in the game, the user is authorized in Web Shop. Otherwise an error message is displayed.

How to get it

1. On your application’s side, implement handling of the user validation webhook.

   When receiving a webhook, the application should do the following:

   • Search for a user by their ID passed in the webhook.
   • Depending on the result, send one of the following status codes:
     • 200 HTTP-code with an answer from webhook if a user is found
     • 404 HTTP-code if the user ID is not found
   • Send user attributes for personalization.

4. If your site includes multiple pages, select the one you need:
   1. Click the current page title at the top of the builder.
   2. Select the necessary page from the drop-down list.
5. Go to the Login settings block.

6. Select the Login with linked user ID option.
7. In the drop-down list, select New Login or one of the created projects.
8. Enter the URL to receive webhooks.