Launcher

Launcher is a customizable delivery tool for partners who develop video games. The product optimizes content delivery costs while centralizing modules for everything from virtual currency to video streaming. Features:

  • Multigame support
  • Several game distribution ways
  • Selling virtual items and physical goods in Store
  • Built-in Login with customizable UI and authentication methods
  • Customizable Launcher UI
  • Runs on Windows and macOS
  • UI localized into 20 languages
  • Automatic delivery of Launcher updates to users
  • P2P/CDN game delivery and updates
  • Configurable from Xsolla Publisher Account
  • News and banner management
  • Users can select game region
  • Channeling Partner Bridge: seamless integration of games into pre-integrated game platforms

To learn more about Launcher technical implementation, see White Paper.

Note: If you already have any of the Xsolla modules installed and want to integrate Launcher, please contact your Account Manager.

Integration Flow

  1. Register an Xsolla Publisher Account.
  2. Create a project.
  3. Set up Launcher.
  4. Customize Launcher UI.
  5. Generate a Launcher installation file and build archive.
  6. Upload the game build to the Xsolla update server.
  7. Send the Launcher installation file to new users.

Creating a Project

  1. Go to Projects and click Create new project.
  2. In setup mode:
    1. Add Project Name.
    2. Set a link to the game’s Website.

Note: Each project in Publisher Account corresponds to one game.

Setting up Launcher

Create a Launcher instance in your Publisher Account:

  1. Set Launcher name.
  2. Choose the UI languages.
  3. Pick one of the predefined Login configurations or create your own by sending its name.
  4. Add one or more projects that you have set up in Publisher Account.

After finalizing Launcher settings in Publisher Account, do the following:

  1. Clone the Launcher from its GitHub repository.
  2. Select the folder of the cloned repository that contains the required launcher version. Go to launcher/win for Windows version and /launcher.app/Contents/MacOS for macOS version. Specify values for the objects in the config.json file.

Example

Copy
Full screen
Small screen
  • php
{
   "launcher_project_id": "8c91ecf3-e7b0-46a8-aaf7-4c419ef8ef4b",
   "login_project_id": "bd2e1104-5494-48f9-ac50-98f230062df1",
   "callback_url": "https://callback_url.com",
   "product_name": "Launcher",
   "link_support": "https://support_example.com",
   "link_community": "https://community_example.com",
   "game_autoupdate": false,
   "hide_peer_seed_info": false,
   "hide_email": false,
   "build_number": 1
}

Customizing Launcher UI

The way to customize the Launcher UI depends on the version of the product you integrate. Description of the customization parameters for different versions is available at the link.

Generating an Archive and Installer

The deploy.bat script from the scripts/win directory generates a Launcher build archive for automatic update delivery to the users.

You can launch deploy.bat by:

  • double-clicking the script file — this will place the build in the cloned project folder > target subfolder;
  • from the command line prompt, using an additional --out <directory> key, where <directory> is your desired build installation path.

Example

Copy
Full screen
Small screen
  • php
deploy.bat --out C:/Target

To generate a Launcher installer and get a link to deliver it to users:

  1. In Publisher Account go to Launcher > General settings and click Generate link to installer for Windows.
  2. In the window that appears, upload a ZIP Launcher build archive and an ICO installer icon. Click Generate.
  3. Wait for the installer to be generated, signed with an Xsolla certificate, and uploaded to the Xsolla CDN.
  4. Copy the link to the web installer to distribute it to your users. To get a link to the stand-alone installer, select Get link to stand-alone installer from the drop-down menu.

Note: A web installer takes less disk space than a stand-alone one but requires an internet connection. A stand-alone installer can be used offline.
Notice: We recommend you deliver Launcher to your users only via the Xsolla CDN. To use other CDNs for delivering Launcher, contact your Account Manager.

The deploy.sh script from the scripts/macOS/ directory generates:

  • A Launcher installer that you can send to new users.
  • A Launcher build archive for automatic update delivery to the users.
  • An APP file.

For the security system of macOS to identify your Launcher build as a safe one, you need to:

  1. Sign the build with the developer certificate.
  2. Notarize your build by Apple.
Signing and notarizing are done automatically after running the deploy.sh script. Follow the instructions below to prepare for signing the build and run the script.

Preparation Steps

To sign and verify the app, you must have:

Generating an App-Specific Password

  1. Go to Apple ID.
  2. Pass the two-factor authentication.
  3. Go to the Security section.
  4. Click Generate Password.

  1. Type a label for the password and click Create.

Getting the Certificate Signature

  1. Open the Keychain Access app.
    1. Go to Keychain Access > Certificate Assistant and select Request a Certificate From a Certificate Authority.

    1. Enter your data in the window that appears, select Save to disk, and click Continue.
  1. Specify the path to the folder where you want to save the certificate and click Save.
  2. Go to Apple Developer and log in.
    1. Go to Certificates, Identifiers & Profiles, open the Certificates tab, and add a new certificate.

    1. Set the certificate type to Developer ID Application and click Continue.
    2. Select the file with the generated certificate and click Continue.
    3. Click Download to download the developer certificate.
  1. Open the downloaded file and install the certificate.
  2. Open the terminal and run the security find-identity -p basic -v command.

Registering a Bundle ID

  1. Go to Apple Developer.
    1. Go to Certificates, Identifiers & Profiles, open the Identifiers tab, and add a new identifier.

    1. Select the App IDs type and click Continue.
    2. Set the app type to App and click Continue.

    1. Insert the Bundle ID. Example: com.template.launcher. Click Continue.
  1. Make the following edits in the Info.plist config-file:
    1. Set the CFBundleIdentifier parameter value to your Bundle ID.
    2. Set values of the CFBundleVersion and CFBundleShortVersionString parameters to the app version number.

Example

Copy
Full screen
Small screen
  • php
<key>CFBundleIdentifier</key>
<string>com.template.launcher</string>
<key>CFBundleVersion</key>
<string>102</string>
<key>CFBundleShortVersionString</key>
<string>1.0.102</string>

Running a Script

When you have completed all the preparation steps, run the following commands:

Copy
Full screen
Small screen
  • php
chmod +x deploy.sh
./deploy.sh --username <username> --password <password> --signature <signature> --teamid <teamid> --apppath <apppath> --appname <appname> --outpath <outpath>

Command-line arguments:
  • apppath — a path to the Launcher build you want to sign. Required. Default is ../../launcher/macos.
  • username — a name of the Apple developer account user. Required. Example: j.smith@email.com.
  • password — an app-specific password. Required.
  • appname — a Launcher build name. Optional. Default is launcher.
  • signature — a certificate signature. Required. Example: Developer ID Application: John Smith (JWZ3331234).
  • teamid — an ID of the team. Required. To get it, run the xcrun altool --list-providers -u "AC_USERNAME" -p "AC_PASSWORD" command.
  • bundleid — an application ID, or a Bundle ID. Optional. Default is com.template.launcher.
  • outpath — a path to the directory to place the signed APP file, archive, and the DMG Launcher installation file. Optional. Default is $apppath/../../target/macos.
If the signing and notarization processes went without errors, the terminal will display this message:

If you get the altool cannot be found error, run the xcrun altool command. In case it returns another error, run the xcode-select -r command.

Uploading Game Build

To load a game build to the update server, use the Build Loader command-line utility. Build Loader system requirements:
  • Windows 7/8/10 64-bit OS or macOS 10.14.0 and higher
  • 1.6 GHz CPU
  • 100 MB free RAM
  • Free disk space: 1.5 × build size
Build Loader accepts the following options:
  • --init — initialization of the utility.
  • --update — sending the game build to the server.
  • --builds-list — a list of game builds.
  • --descr <build-description> — the build’s description.
  • --api-key <API-key> — an API key.
  • --game-path <path-to-game> — a path to the game build.
  • --chunk-size <chunk-size> — the size of chunks - parts into which the game archive is divided. Can be in MB or GB. Accepts values from 10mb to 5120mb or from 1gb to 5gb, default is 5gb.
  • --retry-timeout <timeout> — the timeout between attempts to upload files in seconds. Accepts values from 10 to 60, default is 20.
  • --retry-count <retry-count> — a number of attempts to upload files. Accepts values from 1 to 10, default is 3.
To upload a game build:
  1. Go to Publisher Account > Build settings.
  2. Copy the API key.
  3. Download and install Build Loader.
  4. Initialize the utility.
  5. Upload the game build(s) to the server.
  6. Place the game build to the stage.
  7. Set up the game files.

Initializing Build Loader

To initialize the utility, you need to pass the previously copied API key and the path to the game build:
Copy
Full screen
Small screen
  • php
> build_loader.exe --init --api-key <api-key> --game-path <path-to-game>

Example

Copy
Full screen
Small screen
  • php
> build_loader.exe --init --api-key E51DPZ486S9IUGVF43AH4T48QB7246OQ --game-path C:\Games\LastGameBuild

Copy
Full screen
Small screen
  • php
> build_loader --init --api-key <api-key> --game-path <path-to-game>

Example

Copy
Full screen
Small screen
  • php
> build_loader --init --api-key E51DPZ486S9IUGVF43AH4T48QB7246OQ --game-path /Games/Yourgame

Note:
  • You only need to initialize the utility once, unless you want to change said parameters.
  • The path to the game build may contain only Latin letters.

Uploading Game Build to the Server

To upload a game build to the server, indicate the build path:
Copy
Full screen
Small screen
  • php
> build_loader.exe --update --game-path <path-to-game>

Example

Copy
Full screen
Small screen
    > build_loader.exe --update --game-path C:\Games\LastGameBuild

    Copy
    Full screen
    Small screen
    • php
    > build_loader --update --game-path <path-to-game>

    Example

    Copy
    Full screen
    Small screen
      > build_loader --update --game-path /Games/Yourgame

      You can omit the --game-path parameter if you have already used it when initializing the utility or uploading the previous build. During the first upload, the update server receives the whole game build. Afterwards it will receive game patches generated by Build Loader.

      Placing the Game Build on the Stage

      When uploaded to the server, game builds are displayed in Publisher Account in Project setup > Build Settings > Build list. Select one of the two stages to place the game build to:
      • master: the game will be available for the end users,
      • test: the game will be available only for testing.
      Note: To test your game, start Launcher with the -game_stage test parameter passed in the console. For example: launcher.exe -game_stage test.

      Setting up Game Files

      To let Launcher send the correct files to users, first set up and initialize the installation files:
      1. In Publisher Account, go to Build settings and then Game file settings.
      2. Enter the name and the extension of the file that launches the game (for example, coolgame.exe).
      3. Specify the game installation path.
      4. Add any redistributable packages necessary to launch the game (for example, Microsoft Visual C++ 2017 Redistributable).
      The launcher forwards the following parameters to the game:
      • --xsolla-locale <locale>: interface language;
      • --xsolla-login-token <token>: Xsolla Login JWT (JSON Web Token).
      Example
      Copy
      Full screen
      Small screen
      • php
      game.exe --xsolla-login-token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InAudHVnb2x1a292QHhzb2xsYS5jb20iLCJleHAiOjE1ODU1MDYxMTMsImdyb3VwcyI6W10sImlhdCI6MTU4NDY0MjExMywiaXNzIjoiaHR0cHM6Ly9sb2dpbi54c29sbGEuY29tIiwicGFydG5lcl9kYXRhIjp7ImFkbWluIjp0cnVlfSwicGF5bG9hZCI6IiIsInByb21vX2VtYWlsX2FncmVlbWVudCI6dHJ1ZSwicHJvdmlkZXIiOiJ4c29sbGEiLCJyZWRpcmVjdF91cmwiOiIiLCJzdWIiOiIyNmYxNzI5Ni00Nzk5LTExZTgtOTBkMC00MjAxMGE4YTAwMTkiLCJ0eXBlIjoic29jaWFsIiwidXNlcm5hbWUiOiJzb21lX3VzZXJAbWFpbC5jb20iLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6Ikk2QTJrTEZPQ2JkcnUzamIxMjNyT3JmWnNkTnFpdVcxMjNpWTdKcW85OHI5b0hPbyIsInhzb2xsYV9sb2dpbl9wcm9qZWN0X2lkIjoiNDBkYjJlYTQtNWQ0Mi0xMWU2LWEzZmYtMDA1NDU2YTBlMTRhIn0.ZsTNiwY2iPp7HKqHs5g6JXzL2kv_RVuMNBlF-Tn2ccE --xsolla-locale en

      Copy
      Full screen
      Small screen
      • php
      game --xsolla-login-token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InAudHVnb2x1a292QHhzb2xsYS5jb20iLCJleHAiOjE1ODU1MDYxMTMsImdyb3VwcyI6W10sImlhdCI6MTU4NDY0MjExMywiaXNzIjoiaHR0cHM6Ly9sb2dpbi54c29sbGEuY29tIiwicGFydG5lcl9kYXRhIjp7ImFkbWluIjp0cnVlfSwicGF5bG9hZCI6IiIsInByb21vX2VtYWlsX2FncmVlbWVudCI6dHJ1ZSwicHJvdmlkZXIiOiJ4c29sbGEiLCJyZWRpcmVjdF91cmwiOiIiLCJzdWIiOiIyNmYxNzI5Ni00Nzk5LTExZTgtOTBkMC00MjAxMGE4YTAwMTkiLCJ0eXBlIjoic29jaWFsIiwidXNlcm5hbWUiOiJzb21lX3VzZXJAbWFpbC5jb20iLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6Ikk2QTJrTEZPQ2JkcnUzamIxMjNyT3JmWnNkTnFpdVcxMjNpWTdKcW85OHI5b0hPbyIsInhzb2xsYV9sb2dpbl9wcm9qZWN0X2lkIjoiNDBkYjJlYTQtNWQ0Mi0xMWU2LWEzZmYtMDA1NDU2YTBlMTRhIn0.ZsTNiwY2iPp7HKqHs5g6JXzL2kv_RVuMNBlF-Tn2ccE --xsolla-locale en

      Tutorials

      Launcher System Requirements

      Recommended configuration for optimal Launcher operation:
      • Windows 7/8/10 64-bit OS or macOS 10.14.0 and higher
      • 1.6 GHz CPU
      • 300 MB free RAM
      • Free disk space: 180 MB
      • Up-to-date DirectX version

      Recipes

      Our Recipes will help you try out some of the advanced features of Launcher:

      FAQs

      Q. Why would I use Xsolla Launcher when I can create my own?

      A. You don’t want to spend the resources creating your own launcher during the final stage of development or once the game is complete.

      Q. How much is Xsolla Launcher going to cost me?

      A. Launcher is a value-added product, meaning access to Launcher is already included in the standard Xsolla fee. Additional costs may appear if you decide to deliver games and updates via Xsolla CDN ($0.01 per GB). However, by using the P2P balancing system, you can cut the costs by 80% on average.

      Q. Does the game require Launcher to be running in order to work?

      A. By default, Launcher is always running. When it launches your game, it hides in the system tray so it’s not using up resources. A gamer can shut down Launcher process and the game will still be running as there is no connection during the actual gameplay session.

      Q. How does Xsolla Launcher differ from Steam? How is it similar?

      A. Xsolla Launcher acts like a bridge between Steam and a game.

      Q. When released on Steam, will everything be downloaded from Launcher? Or will the upload to Steam be the full game + Launcher, and then additional updates fetched from Launcher?

      A. Launcher can do any of the above. You can wrap the latest version of your game into Launcher and then distribute it on Steam, so there are no additional downloads needed (game delivery costs will be on Steam). If you want to quickly deliver an update, you can use Launcher as a fast delivery solution without the need to wrap the game into Launcher, and upload it into Steam again. So it’s up to you.

      Q. Do I need to maintain two separate builds for Steam and for a stand-alone? Or is it the same build that gets uploaded to Steam?

      A. No, you won’t need two separate builds. Moreover, if you have both stand-alone and Steam methods of delivery, then Xsolla Launcher will serve you well by collecting your users from both platforms into one database. There is a seamless registration feature, which allows new users who run the game for the first time in Steam to seamlessly pass the registration process as we don’t ask them anything, but at the same time they can go to your official website outside of Steam ecosystem, log in there using Steam OpenID, and become a part of an official/centralized community (e.g. communicate on the forums, discover new games, read news, etc).

      Q. I’m using Steam’s tools, including their launcher, and I have no CDN costs to worry about. Why should I take that risk?

      A. You can use Xsolla Launcher while Steam will be paying for CDN and you can distribute your game wrapped into Launcher through Steam. There is no risk, but plenty of benefit, because via Launcher you can communicate with your active community the way you want as it’s fully customizable. You can also collect a users storage, so you can reach this audience outside of the Steam ecosystem and communicate with your fans there.

      Q. Do you have a list of CDNs which are pre-integrated with your Launcher? Do I need to contact the companies that provide CDN for further integration? Can I use a CDN which is not on your list?

      A. Yes, Xsolla has a list of the pre-integrated CDNs: G-Core Labs, Akamai. You don’t need to contact any companies providing CDNs pre-integrated with Xsolla Launcher. If you want to use a different CDN, please contact your Account Manager.

      Q. Why shouldn’t I just use Solid State Networks?

      A. Solid State Network’s main business is CDN, so their launcher solution isn’t designed to optimize CDN expenses.

      Q. Is there some kind of IPC solution in Launcher?

      A. There is no IPC for now, as Launcher doesn’t have features that require IPC communication. We will be adding more features in the future, such as live streaming, and the Store in the overlay that will require IPC (via SDK), so we do have plans to add it.

      Q. How can Xsolla Launcher users get access to games? Can games be distributed via subscriptions, coupons or promo codes?

      A. For now, users can only access games by redeeming game keys.

      Q. Can Xsolla Launcher users download game updates if they don’t have any game keys purchased?

      A. No. Games and game updates are not available without purchasing game keys.

      Q. Is there a solution to connect PCs on the same LAN via P2P connection, so that data would only be transferred within this LAN?

      A. No, there’s no such solution for now.

      Q. Does Xsolla Launcher support access levels? For example, "alpha" for testing and "beta" for end users.

      A. Yes, Xsolla Launcher supports access levels. When uploading your game build, you can select one of the two stages: test for testing or master for end users. To start Launcher with the games published on stage=test, pass the -game_stage test parameter in the console. For example: launcher.exe -game_stage test.

      Q. What games are displayed in the game list in Xsolla Launcher? All added games or only the ones purchased by a user?

      A. The list contains all the games that have been added to Launcher. The games purchased by a user have the Play button and the rest of the games have the Buy button.

      Q. Can particular users get free game keys? How can they use them?

      A. Yes, you can download game keys from Publisher Account and send them to your users for free in any way you wish. The users will be able to activate their keys in Launcher.

      Q. Can users be authenticated in games automatically after they authenticate in Launcher?

      A. Yes, there is a solution for automatic in-game authentication. The --xsolla-login-token parameter is used to send user data from Xsolla Launcher to the game. To get user data, decode the value of the parameter (see the recipe).

      Q. Can I send the Launcher download link to users, for example, in the game key activation instruction?

      A. The link to downloading Launcher is not included into the game key activation instruction. To send the link independently:

      1. Generate the installation file.
      2. In game keys settings in Publisher Account, upload the installation file as a distribution package for DRM Free.
      After purchasing the game, users will get a link to download the distribution package.