Key Concepts #

This section covers all the basics needed to understand Operator and Player Portal, including information about the web app, configurations, and the build system.

The web app #

The Operator and Player Portal web apps are single page applications created with Vue.js with UI built using the ant.d component library. In development, all the pages and styles are loaded directly and individually by the browser for faster builds and ease of debugging. For production, all the scripts and styles are bundled and minified.

Portal can be found at the following locations when the Pragma Engine is built and running:

Operator Portal

• Game: http://localhost:10200
• Social: http://localhost:11200

Player Portal

• Social: http://localhost:11000

Location #

The default Operator Portal packaged builds are located in web/portal/dist/operator-game and web/portal/dist/operator-social. The Operator Portal location is configured with portalSource:

game:
  pluginConfigs:
    GameOperatorGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist/operator-game"

social:
  pluginConfigs:
    SocialOperatorGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist/operator-social"

The default Player Portal packaged build is located in web/portal/dist/player-social. Likewise the Player Portal location is configured with portalSource:

social:
  pluginConfigs:
    SocialOperatorGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist/player-social"

Both the Operator and Player Portals are pre-configured with default settings which can be built on and customized. For details on customizing your web portals, see Customization.

Non-managed customers will need to add configurations per shard that determine where the Portal should be served from. If the default Portal is being used, that location is web/portal/dist/<build>. If custom work has been added to the Portal, the correct location will need to be configured, such as 5-ext/portal/dist/<build>.

Pragma automatically handles updates for managed customers who customize Portal.

Commands #

Authentication and identity providers #

Operators can log into the Operator Portal using the Unsafe Provider. This login is intended as a test-only authentication source, and should not be used in production settings. Once other authentication methods have been configured, the Unsafe Provider method should be disabled by setting the canAuthenticate config value on the Unsafe Identity Provider to false.

social:
  serviceConfigs:
    UnsafeIdentityDaoConfig:
      canAuthenticate: false
      ...

Authenticated identity providers can be enabled for both Operator and Player Portal login. For a full example of a valid configuration, look at the dropdown under Engine Configuration.

social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Discord:
          class: "pragma.account.DiscordIdentityProviderPlugin"
          config:
            operatorLoginEnabled: true
            playerLoginEnabled: true
            accountLinkingEnabled: true
            showPortalLoginButton: true

Additional authentication providers can be added by configuring them to work with Pragma Engine and then setting the operatorLoginEnabled, playerLoginEnabled, accountLinkingEnabled, and showPortalLoginButton config properties to true on the provider’s config. For more information on configuring identity providers, visit the Identity Providers page.

Styles and assets #

The .css and .less files that are found under /src/lib and /src/portlets are automatically loaded and served to the browser. Style declarations are global, so we recommend limiting the scope by using class wrappers or specific selectors.

Support for Less.js is enabled by default, and all .less files are automatically parsed and converted to CSS.

CSS and Less.js files that start with an underscore are considered partials and are ignored.

The src/assets folder contains static scripts and styles that need to be loaded by the browser before the app is started. This is usually used for JavaScript libraries or CSS frameworks that need to be globally available.

Assets should be manually added to the config using the assets.js and assets.css options. The file paths are relative to the src/assets folder and files are loaded in the specified order.

module.exports = {
  common: {
    "assets.js": [
      "js/lodash.js",
      "bootstrap/bootstrap.min.js"
    ],
    "assets.css": [
      "bootstrap/bootstrap.min.css"
    ],
  },
};

Hosting #

To host an Operator or Player Portal on an external custom domain (example.com), we recommend configuring your CORS access control settings. For more information, see CORS.

serviceConfigs:
  SocialPlayerGatewayConfig:
    corsAllowedHosts:
      1: "example.com"

If this setting is not configured, the gateway will allow any host. Access-Control-Allow-Origin: *

The build system #

The Portal web app consists of multiple builds which are all packaged under portal/dist when make portal-package is run.

Each build is created by combining a base layer with an overlay.

The base layer consists of the core pragma library, the Portal web app code, and default portlets for each build.

• pragma library: a globally available library, accessible in the javascript code as pragma
• default portlets: services–full list found in /web/portal/src/portlets

The overlay layer is built on initialization when the make portal-init call is made. The overlay is created by default in 5-ext/portal/src, and contains everything needed to customize the Portal. Learn more about customizing the portal by visiting the Customization section.

Configurations #

Engine configuration #

The dropdown below contains the full list of possible configuration options for the Portal. These should be registered in the relevant YAML file as needed.

game:
  pluginConfigs:
    GameOperatorGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist/operator-game"
            redirectSignInToSocial: false
social:
  pluginConfigs:
    SocialOperatorGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist/operator-social"
            redirectSignInToSocial: false
    SocialPlayerGatewayNodeService.routePlugins:
      plugins:
        Portal:
          class: "pragma.gateway.FilePortalModulePlugin"
          config:
            portalSource: "web/portal/dist/player-social"
            redirectSignInToSocial: false
    AccountService.identityProviderPlugins:
      plugins:
        Google:
          class: "pragma.account.GoogleIdentityProviderPlugin"
          config:
            operatorLoginEnabled: true
            showPortalLoginButton: true
            ...
        Discord:
          class: "pragma.account.DiscordIdentityProviderPlugin"
          config:
            operatorLoginEnabled: true
            showPortalLoginButton: true
            ...

Portal configuration #

The Portal build system relies on the default base.js configuration file unless an override is found. This file contains detailed descriptions of all possible Portal configurations and the default configurations of all the Portal builds.

Users can override these settings by adding content to src/config/default.js in their overlay. This file is created once the Portal initialize command is called. Implementing default.js will cause the Portal to override the default configuration and instead use the configurations found in this file.

The local-dev.js can be used as an overwrite for local development only.

Glossary #