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

Player Portal

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 [project]/portal/dist/<build>.

Pragma automatically handles updates for managed customers who customize Portal.

Commands #

These should be executed within the platform directory.

commanddescription
./pragma portal initinitialize a Portal overlay for custom development
./pragma portal setupset up dependencies for Portal development
./pragma portal packagebuild the Portal for production
./pragma portal startstart a local development HTTP server
./pragma portal testrun unit tests

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.

social:
  serviceConfigs:
    UnsafeIdentityDaoConfig:
      databaseConfig:
        username: "username"
        password: "password"
        hostPortSchema: "host-port-schema"
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Unsafe:
          class: "pragma.account.UnsafeIdentityProviderPlugin"
          config:
            playerLoginEnabled: true
            operatorLoginEnabled: true
            showPortalLoginButton: true
            accountLinkingEnabled: true
            visibleToOtherPlayers: true

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.

Example: Portal assets configuration
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 ./pragma portal package is run.

builddescription
operator-socialthe portal that runs on the social shard and contains portlets needed to manage accounts and game titles from a studio level
operator-gameruns on a game shard and has portlets needed to manage content and players for that specific game
player-sociala public facing portal, accessed by players to manage their identity providers and personal data

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 ./pragma portal init call is made. The overlay is created by default in [project]/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.

Example: Default config
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 #

termdescription
overlayA collection of files that extend, update, and configure the Portal. The overlay has a predefined folder structure which is created on init.
portletThe internal term used for a Portal service. Portlets can be found under the Services menu in the browser.
Builder Functions for portlet and pageThe definition of a portlet or a page, which is a simple JavaScript function that applies a dedicated API on the one parameter it receives–the portlet or the page object.
extensionA JavaScript file that exports a configuration object that defines a set of updates to existing Portal functionality and existing portlets.
UI componentsPlain Vue.js components defined with the Vue Composition API. The page builder allows inserting any number of components to a page and each component can import and use other components.
swappable componentsUI components that are marked as swappable and can be replaced by their respective ID using an extension.
the pragma libraryA global JavaScript library made available to all the .js scripts in the overlay, which exports functionality and components of the base Portal engine.
Development ToolsAn administrative section of the Portal, accessed by clicking the question mark icon in the top right of the screen or manually navigating to /#/development-tools.
portal buildA standalone runnable webapp, intended for either production or development.

Overview
Operator Portal