Advanced Pexip app branding and customization

Most customization requirements for the Pexip apps can be implemented by using the Pexip branding portal to generate a package of branding files and then applying that branding by uploading the branding package to the Management Node (see Customizing and branding the Pexip apps). However, for advanced customization requirements you may need to make manual changes to the branding files.

You may also need to manually customize these files if you are hosting the web app on an external server or reverse proxy. For information about how to apply customized branding in this situation, see Hosting the Pexip web app externally.

Note that manual configuration requires knowledge of core web-design technologies such as HTML, JavaScript and CSS.

This topic covers how to manually customize the current Webapp3. For information about customizing Webapp2, and the legacy desktop client, refer to the v36 documentation.

Hosting on the Conferencing Nodes

The standard method for applying branding to the Pexip Infinity platform is to upload a branding package to the Management Node and associating the package with a unique web app path. The package is then pushed out to all Conferencing Nodes, from where those customizations are served to all web app users joining using that path.

Each web app version requires separate branding customizations. You can create multiple unique paths where each path is used to host different combinations of web app version, revision and branding.

Branding customizations that are applied to the web app via the Management Node will persist over upgrades to subsequent versions of Pexip Infinity software (although you may need to adapt the customization to cater for any new features when upgrading to a new major release).

Manually customizing Webapp3

This section describes how to manually customize the latest web app, Webapp3. You do this by manually creating a client branding package, uploading it to the Management Node, and then specifying the web app path used to access the branding.

The complete set of files that can be included in a branding ZIP package for upload via the Management Node, or manually copied into the branding directory when hosting the app on a different server, are summarized below, and are then explained in more detail in the subsequent sections.

• The manifest.json controls which customized settings take effect. It also contains the application and default user settings.

  The manifest.json file is the only mandatory file. Your customizations will not take effect if this file is not included.

• landing page background image
• jumbotron image
• logo
• participant background image
• any new or edited language files
• the content shown in the body of the custom step (if enabled)

When creating your branding package ZIP file, ensure that manifest.json and any of the optional files listed above that you are including are contained in a webapp3/branding folder inside the ZIP file for uploading to the Management Node.

When editing the configuration files, you must use a text editor that does not apply "smart quotes" or make any automatic text changes, as the files are sensitive to correct formatting. Use a code editor or simple file editor instead of word processing software.

Application manifest (manifest.json)

The manifest.json file controls which customized settings take effect, and which image files are used. When customizing Webapp3, you must include the manifest.json file in the webapp3/branding folder (creating it, if necessary, in the first instance).

This file must use correct JSON syntax, otherwise it will fail validation when uploaded to the Management Node. We recommend that you use a JSON validation tool (such as https://jsonlint.com) to check the syntax.
In particular, note that items listed inside braces { } or brackets [ ] must be separated by commas , but there must not be a comma after the last item in the list, before the closing brace/bracket.

The properties that can be included in the manifest.json are described below, starting with those that are mandatory:

"meta": {
    "name": "DEFAULT",
    "brandVersion": "n/a"
    }

"images": {
    "background": "./background.jpg",
    "logo": "./logo.svg",
    "jumbotron": "./jumbotron.jpg"
    }

"translations": {
    "en": "./en.json",
    "af": "./af.json"
    }

"favicon": {
    "href": "./favicon.webp"
    }

"customStepConfig": {
    "active": true,
    "subTitle": true,
    "width": "80%",
    "height": "80%",
    "mobileHeight":"100%",
    "mobileWidth": "100%",
    "source": {
        "default": "./index_default.html",
        "en": "./index_en.html",
        "de": "./index_de.html"
        },
    "confirmation": "checkbox",
    "mandatory": true
    }

Overriding the default user-configurable settings

The defaultUserConfig section of the manifest file specifies the defaults to use for the options that are configurable by the user. Options include:

Overriding the default application settings

The applicationConfig section of the manifest file specifies any overrides of the application's default settings. Options include:

"feedback": {
    "enable": true,
    "url": "https://www.pexip.com/feedback"
    }

"handleOauthRedirects": true

"termsAndConditions": {
    "en": "https://www.pexample.com/terms",
    "es": "https://www.pexample.es/terminos",
    "fr": "https://www.pexample.fr/termes"
    }

An example manifest.json file that you can copy and edit for your own use is given below:

{
    "version": 0,
    "meta": {
        "name": "DEFAULT",
        "brandVersion": "n/a"
        },
    "brandName": "Pexip Web App",
    "backgroundColor": "#181818",
    "colorPalette": [
        "#E9F2FB",
        "#A3C8EE",
        "#5C9FE1",
        "#2475C5",
        "#174B7F",
        "#0A2138",
        "#0A2035",
        "#091E33",
        "#091D30",
        "#081B2E",
        "#08192B"
        ],
    "overlay": "light",
    "overlayOpacity": 0.9,
    "images": {
        "background": {
            "xs": "./bg_xs.jpg",
            "sm": "./bg_sm.jpg",
            "md": "./bg_md.jpg",
            "lg": "./bg_lg.jpg",
            "xl": "./bg_xl.jpg"
            },
        "logo": "./logo.svg",
        "jumbotron": "./jumbotron.jpg"
        },
    "translations": {
        "en": "./en.json"
        },
    "defaultUserConfig": {
        "backgroundBlurAmount": 16,
        "isAudioInputMuted": true,
        "isVideoInputMuted": true,
        "showSelfView": true
        },
    "applicationConfig": {
        "disconnectDestination": "https://www.meet.pexample.com",
        "bgImageAssets": [
            "/webapp3/branding/bg_light.jpg",
            "/webapp3/branding/bg_dark.jpg",
            "/webapp3/branding/bg_mid.jpg"
            ],
        "showLiveCaptionsFeature": false,
        "bandwidths": [
            "576",
            "1264",
            "2464",
            "6144"
            ],
        "termsAndConditions": {
            "en": "https://www.pexample.com/terms",
            "es": "https://www.pexample.es/terminos",
            "fr": "https://www.pexample.fr/termes"
            }
        },
    "appTitle": "Pexip",
    "plugins": [
            {
                "src": "./<path-to-your-plugin>/index.html"
            }
        ]
    }

Images

Specifying image locations

When creating a branding package, you can save your images within the webapp3/branding folder or you can create a subfolder within it (e.g. webapp3/branding/images) and save your images there. Either way, when you then reference those images from within the manifest.json you must reference the image's location as follows:

• For all images apart from those referenced in "bgImageAssets", you must provide the path of the image relative to the webapp3/branding folder.

  For example, if image.jpg is located:

  • in the webapp3/branding folder, you should reference it as "./image.jpg"
  • in a webapp3/branding/images folder, you should reference it as "images/image.jpg"

• For any "bgImageAssets" images, you must include the path, including the / character, to which the branding package will be applied.

  For example, if image.jpg is located:

  • in the webapp3/branding folder and this package is used for the default ("webapp3") path, you should reference it as "/webapp3/branding/image.jpg"
  • in a webapp3/branding/images folder and this package is used for the default ("webapp3") path, you should reference it as "/webapp3/branding/images/image.jpg"
  • in the webapp3/branding folder and this package is applied to a new "sales" path, you should reference it as "/sales/branding/image.jpg"
  • in a webapp3/branding/images folder and this package is applied to a new "sales" path, you should reference it as "/sales/branding/images/image.jpg"

Landing page background image

You can optionally include a background image file to display behind all other elements on the landing page. To do this, save the file you wish to use in the webapp3/branding folder and then edit the manifest.json to specify its path using the "background" property within the "images" property.

You can specify a single image, or different images to be used for different screen sizes / breakpoints.

• To specify a single background image used for all screen sizes / breakpoints, use a string that contains the URL of the image, for example:

  "images": {
      "background": "images/background.jpg"
      }

• To specify different images used depending on the screen size / breakpoints, use an object with the properties xs, sm, md, lg, and xl. The properties represent breakpoints; each property value is a string that contains the URL of the image displayed at that specific breakpoint.

  The viewport width range that the breakpoints represent are as follows:

  • xs: 0px - 478px
  • sm: 479px - 743px
  • md: 744px - 1024px
  • lg: 1025px - 1999px
  • xl: 2000px and up

  At least 1 breakpoint property should be defined on the object, but not all need be set. If just the xs and md breakpoints are set, the breakpoint in between (sm) will use the larger (md) image. If the larger breakpoints above md are not set, they will fallback to using the md image.

  For example:

  "images": {
      "background": {
          "xs": "images/background_1.jpg",
          "sm": "images/background_2.jpg",
          "md": "images/background_3.jpg",
          "lg": "images/background_4.jpg",
          "xl": "images/background_5.jpg"
          }
      }

Supported file formats are:

• .JPG
• .JPEG
• .PNG
• .WEBP

Background image files for xl images must meet the following requirements:

• resolution: 1920x1080
• size: 500-600 kB

For other images, there are no specific requirements but for best results we recommend matching the image width to the highest value of the breakpoint to which it is applied. For example, for the md breakpoint you should use an image that is around 1024px wide.

We also recommend that images used for lower breakpoints are portrait rather than landscape.

Jumbotron image

The jumbotron image file is an optional image/logo that can be displayed at the top of the "jumbotron" — the area on the left side of the landing page. To include this image, save the file you wish to use in the webapp3/branding folder and then edit the manifest.json to specify its path using the "jumbotron" value within the "images" property.

This file must meet the following requirements:

• resolution: 640x360
• size: 70-140 kB
• format: .JPG, .JPEG, .PNG or .WEBP

Logo

The logo file is an optional image/logo that can be displayed at the bottom of the "jumbotron" — the area on the left side of the landing page. To include this image, save the file you wish to use in the webapp3/branding folder and then edit the manifest.json to specify its path using the "logo" value within the "images" property.

This file must meet the following requirements:

• transparent
• maximum displayed width: 168px
• maximum displayed height: 80px
• format: we recommend .SVG

Default participant background replacement images

The background replacement feature allows a video participant to replace their background with an image they select — either from a set of default images that you specify (as described below), or an image they upload themselves.

To include default background replacement images for all users in your deployment, save the files you wish to use in the webapp3/branding folder (or a subfolder that you create) and then edit the manifest.json to specify the path of each image using the "bgImageAssets" value within the applicationConfig section.

For example, if you have saved the images within the branding package in the webapp3/branding folder and this branding is to be applied to a sales path, then you should specify the images as follows:

"bgImageAssets": [
    "/sales/branding/bg_light.png",
    "/sales/branding/bg_mid.jpg",
    "/sales/branding/bg_dark.jpg"
    ]

If your branding includes default background images and you want to apply it to more than one path, you must create a separate branding package for each path, and edit the manifest.json for each.

These files must meet the following requirements:

• images must be at least 432 pixels high, and 768 pixels wide
• supported formats are .JPG, .JPEG, .PNG and .WEBP
• we recommend you use high-definition images

Note that the "bgImageUrl" value within the defaultUserConfig section of the manifest file can also be used to specify an alternative to the inbuilt default image that can also be selected by the user for background replacement:

Languages/text used in labels and messages

Webapp3 natively supports over 20 of the most popular languages. If the user's browser is set to use any one of these supported languages, it will use that automatically instead of the default English. Users can also change the language from within the Settings > Languages option in the web app itself. Alternatively, users can view the web app in any of the supported languages by appending the appropriate language code to the end of the URL.

See Language support for a complete list of the languages currently supported.

You can limit which languages are supported via the availableLanguages option in the manifest file.

You can change any of the text that is displayed in the application (either in the default English or any of the supported languages), and you can add additional languages. Each language references a .json dictionary file containing a list of token and text string pairs.

• To change the text of a supported language you create a new .json file for that language that contains the strings you wish to change.
• To add a new language you create a new .json file for that language.

All .json files must be placed in the webapp3/branding subfolder and referenced in the translations block of the manifest file.

"username": {
    ...
    "usage-purpose": "Please enter a display name so other people know who's in the meeting",
    ...
    }

Changing the default (English) strings

You can use your own alternative English strings instead of the default strings. To do this, download the default en.json file from https://docs.pexip.com/files/webapp3_languages/v37/en.json (you may need to right-click and select Save link as...), and edit the strings as required. You only need to include the token and text string pairs that you want to be different from the default strings. Do not change the token names.

Then save the en.json file in the webapp3/branding folder and reference it in the translations block of the manifest, in the same way as you would when Adding additional languages.

Changing translations for other supported languages

The Webapp3 is available in a selection of other languages. We've provided the translations for you, but you can use your own alternative strings for each language instead. To do this:

1. Download the relevant language file from https://docs.pexip.com/files/webapp3_languages/v37/<language>.json where <language> is the ISO standard code for the language, for example de for German.

2. Edit the strings as required. You only need to include the token and text string pairs that you want to be different from the default strings for that language. Do not change the token names.
3. Save the file with the appropriate file name (for example, de.json for any German changes) in the webapp3/branding folder and reference it in the translations block of the manifest, in the same way as you would when Adding additional languages.

Adding additional languages

The Webapp3 is available in English and a selection of other languages. You can add additional languages as follows:

1. Create a new <language>.json file in the webapp3/branding folder:

   1. Download the default en.json file as a basis for the new language.

   2. Rename the new file as appropriate for your new language, for example af.json for Afrikaans.

      We recommend using the ISO standard language codes/locales for the filename as this allows that language file to be used automatically if its name matches the browser's default language. Always use .json as the filename extension.

      The app also supports different language cultures via branding. For example, it can distinguish between French (fr-FR.json), French Canadian (fr-CA.json) and French Belgian (fr-BE.json).

   3. Edit the text strings as appropriate for the new language, leaving the token names unchanged.
2. Save the file in the webapp3/branding folder.

3. Edit the manifest.json file to add a reference to the new language by updating the translations block to include the new language file, for example:

   "translations": {
       "en": "./en.json",
       "af": "./af.json"
       }
   

   Now, if a user's browser is set to use Afrikaans, they will see the text strings from the af.json file. Any strings not specified in af.json are shown in the default English.

Tags

Some of the text strings contain tags, for example <0>…</0>, <1>…</1>, etc. These tags are used by the app for formatting purposes, for example by changing the text to bold, by adding a hyperlink to the text, or by inserting the text into a button. You must retain the tags, but you can translate any text within the tags into your chosen language.

You cannot create your own tags.

Variable substitutions

Some strings contain variable substitutions, for example:

"remove-user-confirmation": "Are you sure you want to forcibly eject {{userName}} from this meeting?"

This message appears when a user disconnects a participant. In this case, the application automatically substitutes {{userName}} with the participant's actual name as shown in the participant list. Variables always take the format {{<variable name>}}. You cannot create your own variables.

Error messages

There is a list of error message in the language file. These messages typically relate to connectivity issues between the Conferencing Node and Pexip apps, or to conference activities.

The token name is in the format "code[#pex###]", which is used as a common reference for the message regardless of the language used in the message string, for example:

"code[#pex121]": "A host ended the meeting"

You can change these messages in the same way as you can change the other messages — edit the display text part only; do not change the "code[#pex###]" token name part.

Text on the landing page "jumbotron"

The "infocard" block of the language file specifies the text that appears underneath the "jumbotron" image on the left side of the landing page. By default this uses the brandName variable configured in the manifest.json file. You can edit both the header and body text:

"infocard": {
    "meeting": {
        "body": "A secure video communications platform",
        "header": "Welcome to\n {{brandName}}"
        }
    }

Text of the custom step

The "custom-step" block of the language file specifies the text that appears in the fixed elements (e.g. title, button, checkbox label) of the card displayed when the optional additional customized joining step is enabled.

To use a custom joining step and to set its contents you must first include the optional customStepConfig block in the manifest.json file, and then include in the webapp3/branding folder the files that are referenced within the source: specifies the path of the content that appears within the card. The content can be an HTML file, text, an image, a video, or anything else that can be displayed inside an iframe. For more details and examples, see Body of the custom step. block, which supply the body of the custom step. You can also change the wording of the other elements of the custom step via the "custom-step" block of the language file (as described in this section).

The example below shows an edited "custom-step" block used to produce the example shown in Body of the custom step:

"custom-step": {
    "checkbox": {
        "aria-label": "Click to agree",
        "caption": "I agree"
        },
    "content-frame": {
        "title": "Content"
        },
    "next": "Proceed",
    "subtitle": "You must read and accept the conditions below in order to join the meeting.",
    "title": "Terms and conditions of use"
    }

Body of the custom step

To use a custom joining step and to set its contents you must first include the optional customStepConfig block in the manifest.json file, and then include in the webapp3/branding folder the files that are referenced within the source: specifies the path of the content that appears within the card. The content can be an HTML file, text, an image, a video, or anything else that can be displayed inside an iframe. For more details and examples, see Body of the custom step. block, which supply the body of the custom step (as described in this section). You can also change the wording of the other elements of the custom step via the "custom-step" block of the language file.

The content that is shown within the body of the custom step can be an HTML file, text, an image, a video, or anything else that can be displayed inside an iframe.

You can define different content files for different languages — for more information, see source: specifies the path of the content that appears within the card. The content can be an HTML file, text, an image, a video, or anything else that can be displayed inside an iframe. For more details and examples, see Body of the custom step..

The example below is an HTML file that displays pre-meeting terms and conditions as a set of numbered items. This can be used in conjunction with a checkbox to require that the user confirms they have read and agree to these conditions before they can proceed:

<!DOCTYPE html>

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-7">
    <style>
      ::-webkit-scrollbar {
        width: 8px;
        height: 8px;
        overflow: visible;
      }

      ::-webkit-scrollbar-thumb {
        min-height: 18px;
        border-width: 1px 1px 1px 8px;
        border-radius: 20px;
        background-color: #a5b8ca;
        background-clip: padding-box;
      }

      ::-webkit-scrollbar-button {
        width: 0;
        height: 0;
      }

      ::-webkit-slider-thumb element .b-w::-webkit-scrollbar-track {
        border: solid transparent;
        border-width: 0 0 0 6px;
        background-clip: padding-box;
      }

      ::-webkit-scrollbar-track {
        border: solid transparent;
        border-width: 0 0 0 6px;
        background-clip: padding-box;
      }

      ::-webkit-scrollbar-corner {
        background: 0 0;
      }

      ::-webkit-scrollbar-track-piece {
        background: transparent;
      }
      body {
        color: #1e3a54;
        font-size: 14px;
      }
    </style>
  </head>
  <body
    style="
      font-family: Inter, -apple-system, BlinkMacSystemFont, Segoe UI,
        Roboto, Oxygen, Ubuntu, Cantarell, Fira Sans, Droid Sans,
        Helvetica Neue, sans-serif;
    "
  >
    <ol>
      <li>
        This is the first condition.
      </li>
      <br />
      <li>
        This is the second condition.
      </li>
      <br />
      <li>
        This is the third condition.
      </li>
    </ol>
  </body>
</html>

When the example above is used in conjunction with the example "custom-step" block of the language file given in Text of the custom step, the result is the following:

Uploading the branding package

When you have prepared your files, ZIP the folder containing the webapp3/branding folder. It is this zipped folder that you then upload to the Management Node.

More information

Participant avatars cannot be branded via the web app, but they can be controlled by using external policy or by configuring user records. For full details about how to integrate Pexip Infinity with an external policy server, see Using external and local policy to control Pexip Infinity behavior.

In addition to customizing the appearance of the web app, you can also use themes to change the voice prompts and images provided to participants when they are accessing a Virtual Meeting Room, Virtual Auditorium or Virtual Reception.

If any further information on customizing Pexip Infinity is required, please contact your Pexip authorized support representative.