Seamless web-to-game integration

How it works

Seamless web-to-game integration allows you to configure sending data from your website to the game in the URL parameters. You can transmit a user’s authorization token, marketing campaign data, or other information.

User flows

There are the following user scenarios when implementing seamless web-to-game integration:

• Clicking a link to download the launcher installer from the website.
• Clicking a link to the launcher from the website.
• Launching the game from the launcher.

When a user clicks a link to download the launcher installer from the website:

1. The user opens the website.
2. The user follows the link to the launcher installer.
3. The user downloads the launcher installer with the link containing a one-time password.
4. The user installs the launcher.
5. The launcher receives the value of the common_payload parameter through the one-time password.
6. The user clicks Play in the launcher.
7. The launcher checks the presence and expiration of the common_payload parameter:
   • If the check is successful, the launcher starts the game with the arguments obtained from the common_payload parameter.
   • If the check is unsuccessful:
     • If the website URL is configured in the Publisher Account within the executable file name, the launcher redirects the user to that address.
     • If the website URL is not configured in the Publisher Account within the executable file name — the launcher starts the game without the common_payload argument.

When a user clicks a link to the launcher from the website and the launcher has already been installed, the following flow occurs:

1. The user opens the website.
2. The user clicks a link to the launcher.
3. The launcher saves the value of the payload, common_payload and expires_jn parameters from the URL.
4. The user clicks Play in the launcher.
5. The launcher checks the presence and expiration of the payload and common_payload parameter:
   • If the check is successful, the launcher starts the game with the arguments obtained from the payload and common_payload parameters.
   • If the check is unsuccessful:
     • If the website URL is configured in Publisher Account within the executable file name, the launcher redirects the user to that address.
     • If the website URL is not configured in Publisher Account within the executable file name — the launcher starts the game without the payload and common_payload arguments.

When a user launches the game from the launcher, the following flow occurs:

1. The user opens the launcher.
2. The user clicks Play in the launcher.
3. The launcher checks the presence and expiration of the payload and common_payload parameter:
   • If the check is successful, the launcher starts the game with the arguments obtained from the payload and common_payload parameters.
   • If the check is unsuccessful:
     • If the website URL is configured in Publisher Account within the executable file name, the launcher redirects the user to that address.
     • If the website URL is not configured in Publisher Account within the executable file name, the launcher redirects the user to that address — the launcher starts the game without the payload and common_payload arguments.

How to get it

To set up seamless web-to-game integration:

1. Configure settings in Publisher Account.
2. Add a link to your website.
3. Implement processing of the data received in the payload parameter on the game side.

Configuration of settings in Publisher Account

1. Open your project in Publisher Account.
2. Click Launcher in the side menu.
3. Find the launcher on the dashboard, and click Edit launcher.
4. In the Games section, click Set up to the right of your game.
5. Go to the Builds section.
6. Go to the Executable files tab.
7. Add the --x_payload_url argument to the Executable file name field for each operating system. In the argument value, pass the website URL where the link or button is located. The value should be encoded using Base64.

For example, if the executable file name is game.exe and the game website URL is http://example.com/start_play, then enter game.exe –x_payload_url aHR0cDovL2V4YW1wbGUuY29tL3N0YXJ0X3BsYXk= in the Executable file name field.

Adding a link to the website

Add a link or button to your website that will open the URL in the xl-<launcher-id>://game/<game-id>?payload=<payload>&common_payload=<common_payload>&expires_in=<expires_in> format, where:

• <launcher-id> and <game-id> — identifiers of the launcher and game that you can find in the URL of your Publisher Account: https://publisher.xsolla.com/<merchant-id>/projects/<project-id>/new-launcher/<launcher-id>/game/<game-id>.
• <payload> — the data that needs to be passed to the game.
• <common_payload> — the user data that needs to be passed to the launcher, which is common for all games.
• <expires_in> — the expiration time of the data passed in the payload and common_payload parameters in Unix time format in milliseconds.

function getAuthToken() {
    return 'YOUR DATA HERE';
}

function getDeeplink(launcherID, gameID) {
    const encodedPayload = btoa(getAuthToken());
    const expiresIn = new Date();
    expiresIn.setHours(expiresIn.getHours() + 1); // Payload data will be fresh for 1 hour
 return `xl-${launcherID}://game/${gameID}?payload=${encodedPayload}&expires_in=${expiresIn.getTime()}`;
}

// Put that `href` to button or link address
const href = getDeeplink(123, 4567);

Integration on the game side

The launcher passes the data received in the payload parameter as the value of the –xsolla-payload command line argument, as shown in the example below. It also checks for the presence and lifespan of data passed in the common_payload parameter and passes it as the value of the –xsolla-common-payload command-line argument, as shown in the example below.

Example of starting a game when data is encrypted using Base64:

game.exe ---xsolla-payload <payload> --xsolla-common-payload <common_payload> WU9VUiBEQVRBIEhFUkU=