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 any other information.

User flows

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

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

When a user clicks on a link to the launcher from the website, 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 parameter from the URL.
  4. The user clicks Play in the launcher.
  5. The launcher checks the presence and expiration of the payload parameter:
    • If the check is successful, the launcher starts the game with the arguments obtained from the payload parameter.
    • If the check is unsuccessful:
      • If a URL is specified in the settings of the Publisher account, the launcher redirects the user to that URL.
      • If the URL is not specified in the settings of the Publisher account, the launcher starts the game.

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 parameter:
    • If the check is successful, the launcher launches the game with the arguments obtained from the payload parameter, obtained during the last launcher launch from the website link.
    • If the check is unsuccessful:
      • If a URL is specified in the settings of the Publisher account, the launcher redirects the user to that URL.
      • If the URL is not specified in the settings of the Publisher account, the launcher starts the game.

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. For each operating system, add the --x_payload_url argument to the Executable file name field. In the argument value, pass the URL of the website where the link or button will be 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.

Note
After completing this setting, users won’t be able to launch the game without receiving data from the game website. If the data is absent, the user is redirected to the game website to obtain it.

Add a link or button to your website that will open the URL in the xl-<launcher-id>://game/<game-id>?payload=<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.

Note
We recommend that you encrypt the data using Base64 or urlencoder.org for secure transfer as URL parameters.

  • <expires_in> — the expiration time of the data passed in the payload parameter in Unix time format.

Copy
Full screen
Small screen

    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 game receives data in the --xsolla-payload argument. Implement decryption of data by the game depending on the encryption method you have chosen.

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

    Copy
    Full screen
    Small screen

      game.exe --xsolla-payload WU9VUiBEQVRBIEhFUkU=

      Was this article helpful?
      Thank you!
      Is there anything we can improve? Message
      We’re sorry to hear that
      Please explain why this article wasn’t helpful to you. Message
      Thank you for your feedback!
      We’ll review your message and use it to help us improve your experience.
      Rate this page
      Rate this page
      Is there anything we can improve?

      Don’t want to answer

      Thank you for your feedback!
      Last updated: April 5, 2023

      Found a typo or other text error? Select the text and press Ctrl+Enter.

      Report a problem
      We always review our content. Your feedback helps us improve it.
      Provide an email so we can follow up
      Thank you for your feedback!