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.

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>&common_payload=<common_payload>&expires_in=<expires_in> format, where:

Note
We recommend that you encrypt the data using Base64 or urlencoder.org for secure transfer as URL parameters.
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 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:

    Copy
    Full screen
    Small screen
      game.exe ---xsolla-payload <payload> --xsolla-common-payload <common_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: January 22, 2024

      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!