Advanced Connect app branding and customization

This section describes how to manually customize the latest web app, Connect 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

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 required:

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

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

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 Connect for Web",
  "backgroundColor": "#181818",
  "colorPalette": [
    "#E9F2FB",
    "#A3C8EE",
    "#5C9FE1",
    "#2475C5",
    "#174B7F",
    "#0A2138",
    "#0A2035",
    "#091E33",
    "#091D30",
    "#081B2E",
    "#08192B"
    ],
  "overlay": "light",
  "overlayOpacity": 0.9,
  "images": {
    "background": "./background.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": ["./branding/bg_light.png", "./branding/bg_dark.jpg"],
    "showLiveCaptionsFeature": false,
    "bandwidths": [
      "576",
      "1264",
      "2464",
      "6144"
      ],
    "termsAndConditions": {
      "en": "https://www.pexample.com/terms"
      }
    },
  "appTitle": "Pexip",
  "plugins": [
    {"src": "./<path-to-your-plugin>/index.html"}
    ]
  }

Overriding the default user-configurable settings

The defaultUserConfig section of the manifest file specifies the defaults to be used 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:

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

Images

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" value within the "images" property.

This file must meet the following requirements:

• resolution: 1920x1080
• size: 500-600 kB
• format: .JPG, .JPEG, .PNG or .WEBP

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

Participant background replacement images

The background replacement feature allows a video participant to replace their background with one or more selected images — either from a set of default images that you specify, 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 their paths using the "bgImageAssets" value within the applicationConfig section.

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

Earlier versions of Pexip Infinity supported a single default background replacement image specified using the "bgImageUrl" value within the defaultUserConfig section of the manifest file. To ensure backwards compatibility this option is still supported, but we recommend for new customizations that you use the "bgImageAssets" option instead. If both "bgImageAssets" and "bgImageUrl" are specified, the former will be used and the latter ignored.

Languages/text used in labels and messages

Connect Webapp3 supports over 20 of the most popular languages. If the user's browser is set to use any one of these supported languages, Connect Webapp3 will use that automatically instead of the default English. Alternatively, users can view Connect Webapp3 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 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/v33/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 Connect 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/v33/<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 Connect 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 will be 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 Connect app, 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 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}}"
		}
	},

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.

This section describes the Connect app files for the previous web app, "Connect Webapp2", that can be manually customized.

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.

The customizations you make here must be applied manually to the Connect web app. You can use Pexip Infinity's provisioning features to apply the same branding to the Connect desktop app.

If you have downloaded the default branding from the Management Node, your ZIP file when unpacked will contain the following files within a webapp2/branding folder, as shown below:

Note that if you have downloaded a branding package from the Webapp2 branding portal, or from a Pexip Infinity deployment running v30 or earlier, you will need to edit the structure of the unzipped files and folders to match that shown above. For more information, see Using the Webapp2 branding portal

Manually creating a client branding package for upload via the Management Node

In addition to the files/subfolders included in the default client branding as shown above, there are some extra files/subfolders that can be included for other customization purposes — some of which may be generated when using the Pexip branding portal.

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 custom_configuration directory when hosting the app on a different server, are summarized below, and are then explained in more detail in the subsequent sections:

When creating your branding package ZIP file, ensure that all of your files/subfolders are contained in a webapp2/branding folder.

• The manifest.json file controls which customized settings take effect.

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

• The settings.json file* This file/folder does not initially exist in the default branding download. contains the application and default user settings.
• A set of favicon files* This file/folder does not initially exist in the default branding download. to associate with the app.
• A site.webmanifest file* This file/folder does not initially exist in the default branding download. for websites installed on the homescreen of a device.
• The watermark_icon.png file is a transparent image used for applying a watermark to the self-view image displayed on the Home page. By default, this image is the same as the base theme's watermark that is applied to the main speaker video in a conference, and is a white Pexip logo with 40% transparency.
• The background.jpg file* This file/folder does not initially exist in the default branding download. is an optional image/logo file that can be displayed on a landing page. It can also include some customizable text.
• A languages subfolder* This file/folder does not initially exist in the default branding download. containing the text customizations for each language. Currently, English is the only language that is available by default, but you can add more languages if required.
• A plugins subfolder* This file/folder does not initially exist in the default branding download. which in turn contains subfolders for each plugin that has been deployed.
• A themes subfolder* This file/folder does not initially exist in the default branding download. containing a styles.css file that specifies style overrides, such as different colors for selected elements.

* This file/folder does not initially exist in the default branding download.

Application manifest (manifest.json)

The manifest.json file controls which customized settings take effect. You must include the manifest.json file in the webapp2/branding folder. The manifest.json file should look like this, with a brandingID value and the other settings set to true/false as appropriate:

{
  "brandingID": "1521829718679",
  "isSettingsBranded": true,
  "isWatermarkBranded": false,
  "isStylesBranded": false,
  "isCustomBackgroundBranded": false
}

• The brandingID value has to be different from the previously uploaded value for the new settings to take effect (this means, for example, that you can easily revert to a branding you created earlier just by re-uploading that ZIP file). In the manifest.json file generated by the Pexip branding portal, the brandingID is set to a timestamp, but any type of numerical value is valid. You can open your browser console and type Date.now() to get a current timestamp value.
• Set isSettingsBranded to true if you include a settings.json file.
• Set isWatermarkBranded to true if you are supplying a new watermark_icon.png file.
• Set isStylesBranded to true if you have provided CSS overrides in a themes folder with a styles.css file.
• Set isCustomBackgroundBranded to true if you are supplying a background.jpg file.

Application and default user settings (settings.json)

The settings.json file is a JSON dictionary that contains the application and default user settings.

Note that this file is not included in the default branding ZIP file that you can download from the Management Node, but it is included in ZIP files generated by the Pexip branding portal when the relevant settings have been customized. When used, the settings.json file must be placed in the webapp2/branding folder.

The following items in the applicationSettings block can be configured:

The defaultUserSettings block in the settings.json file contains the default user settings that are applied to first-time users, or whenever a new customization package is applied to the client. The application subsequently remembers the user's last-used settings. The configurable options are:

The plugins block controls which plugins are available. For more information on implementing plugins, see Creating and deploying Connect app plugins and the Pexip Developer Portal.

Here is an example settings.json file that shows the required structure:

{
 "applicationSettings": {
  "dialOutProtocol": "sip",
  "languages": [],
  "bandwidths": [
   "576",
   "1264",
   "2464"
  ],
  "registrationEnabled": true,
  "defaultToMuted": true
 },
 "defaultUserSettings": {
  "bandwidth": "1264",
  "playRingTone": false
 },
 "plugins": []
}

Custom favicon files

When you use customized branding in your web app, you must specify the favicon files you want to use, even if you want to continue using the default Pexip favicon ().

If you do not include the favicon files in your branding package then the web app will not use any favicons at all.

The complete set of expected favicon files is shown below. You can use the Pexip branding portal to automatically generate these files (with the default Pexip favicon image).

Many favicon generator utilities are available on the internet.

A site.webmanifest file

The site.webmanifest file is an optional file. A web app manifest provides information about an application (such as its name, author, icon, and description) in a JSON text file for websites installed on the homescreen of a device. See https://developer.mozilla.org/en-US/docs/Web/Manifest for more information about the contents of the file.

You can use the Pexip branding portal to automatically generate a site.webmanifest with some suggested settings.

Custom background image/logo (background.jpg) and welcome text

You can optionally include a background.jpg file and some accompanying welcome text to display to the user on a landing page whenever they use the app. (By default, Pexip Infinity does not supply a background file and the landing page is not displayed.)

To enable the landing page:

1. Include a file called background.jpg in the webapp2/branding folder (at the same level as the watermark_icon.png file). The background image covers the whole browser window and scales if the browser window resizes. We recommend a JPEG image that is approximately 2000x1400 pixels.
2. Set isCustomBackgroundBranded to true in the manifest.json file.
3. Customize the accompanying welcome text as required in the language file. The text strings used on the landing page are in the "ONBOARDING_SCREEN" group of tokens. You can use HTML markup (UTF-8 characters only).

Languages/text used in labels and messages (en.json) and additional languages

All of the text that is displayed in the application can be changed, and additional languages can be added. Note that you can also use the Pexip branding portal (https://webapp2-branding.pexip.io/) to set up new languages.

Any files containing customized text strings must be placed in the webapp2/branding/languages subfolder. The en.json (English) file is supplied by default when you download the default branding from the Management Node.

Editing a language file

Each language file contains a list of token and text string pairs. The token remains the same in each language file and the associated string contains the text that is displayed in the app when that language file is used.

Text customizations are simply a matter of changing the text assigned to each token in your language file. To find the string to change, search in the language file for the text that needs to be changed, edit the text, and save your changes back to the same file. Do not change the token names.

For example, the "Enter your name" string is located in the "HOME" block and is associated with the "DISPLAYNAME_PLACEHOLDER" token:

"DISPLAYNAME_PLACEHOLDER": "Enter your name"

The strings are grouped together according to where or when they are displayed. For example, all tokens in the "SEARCH" block refer to strings that appear when you are entering or selecting the address to call.

The language file does not have to contain the complete set of tokens / text strings. If required, you can only include the token and text string pairs that you want to be different from the default English strings.

Variable substitutions

Some strings contain variable substitutions, for example:

"TITLE": "Are you sure you want to disconnect {{name}}?"

This message appears when a user disconnects a participant. In this case, the application automatically substitutes {{name}} 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 Connect app, or to conference activities.

The token name is in the format PEX###, which is used as a common reference for the message regardless of the language used in the message string, for example:

"PEX120": "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 PEX### token name part.

Changing the default English (en.json) strings

You can use your own alternative English strings instead of those supplied in the default (en.json) file. To modify the English strings:

1. Edit the text strings as required in the en.json file in the webapp2/branding/languages folder (it is supplied by default when you download the default branding from the Management Node).
2. As with all customizations, remember to update (or create if necessary) a manifest.json file. Set a new value for brandingID and set isSettingsBranded to true.

3. Ensure that the settings.json file (which you may need to create) contains a languages section within the applicationSettings block and that it references the en locale:

   {
       "applicationSettings": {
           "languages": [
               {
                   "locale": "en",
                   "label": "English"
               }
           ]
       }
   }

4. Zip up your customizations in the webapp2 folder and upload the package to the Management Node.

Adding more languages

The Connect Webapp2 and Connect desktop app are in English by default, but you can add extra languages. To add a new language:

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

   1. Copy the existing en.json file as a basis for the new language.

   2. Rename the new file as appropriate for your new language, for example es.json for Spanish.

      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. Edit the settings.json file and add a reference to the new language by updating the languages setting in the applicationSettings block to include the new language file, for example:

   "languages": [
       {
           "locale": "en",
           "label": "English"
       },
       {
           "locale": "es",
           "label": "Español"
       }
   ]

   would mean there are two language files available: en.json and es.json. The locale acts as the reference to the name of the json language file, and to the user's language preferences in their browser when deciding which language to use by default.

3. As with all customizations, remember to update (or create if necessary) a manifest.json file. Set a new value for brandingID and set isSettingsBranded to true.
4. Zip up your customizations in the webapp2 folder and upload the package to the Management Node.

When languages are configured, Connect app users get an additional option on the settings page that allows them to choose their preferred language.

Changing the default language

When additional languages have been configured, you can set one of those new languages to be the default language for first-time users. To set the default language for first-time users:

1. Edit the settings.json file.

2. Edit the language item in the defaultUserSettings block to refer to the preferred default language locale, for example:

   "language": "es"

   The nominated locale must be in the list of languages in the applicationSettings block, and have an associated language json file.

3. As with all customizations, remember to update (or create if necessary) a manifest.json file. Set a new value for brandingID and set isSettingsBranded to true.
4. Zip up your customizations in the webapp2 folder and upload the package to the Management Node.

Plugins

Plugins offer extensions to the core client functionality. Each plugin has its own subfolder of files, and must also be referenced in the plugins block of the settings.json file. For more information on implementing plugins, see Creating and deploying Connect app plugins and the Pexip Developer Portal.

Styles (CSS) overrides

You can include a themes subfolder containing a styles.css file that specifies style overrides, such as different colors for selected elements.

Note that this folder and file is not included in the default branding ZIP file that you can download from the Management Node, but it is included in ZIP files generated by the Pexip branding portal when the relevant settings have been customized. When used, the themes folder must be placed in the webapp2/branding folder.