Advanced Infinity Connect customization

This section describes the Infinity Connect files 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 are applied automatically to the Infinity Connect web app. You can use Pexip Infinity's provisioning features to instruct the Infinity Connect desktop and mobile clients to override their built-in branding with the web app branding package installed on Pexip Infinity.

If you have downloaded the default branding from the Management Node, your ZIP file when unpacked will contain the following files:

The webapp2 folder contains all of the files for the web app client. All of the other folders and files shown above (including the languages and themes folders that are at the same level as the webapp2 folder) can be ignored as they only apply to the legacy web app.

The webapp2 folder looks like this (note that it contains its own languages subfolder):

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 folder.

• The manifest.json file*This file/folder does not initially exist in the default branding download. 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 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. 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.

For your customization changes to take effect, you must include the manifest.json file in the webapp2 folder (creating it, if necessary, in the first instance). 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 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 Infinity Connect plugins.

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 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://brandingportal.pexip.com) to set up new languages.

Any files containing customized text strings must be placed in the webapp2/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 Infinity Connect, 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/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 Infinity Connect clients 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/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.

   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, Infinity Connect 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 Infinity Connect plugins.

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 folder.

This section describes the legacy Infinity Connect web app files 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.

If you have downloaded the default branding from the Management Node, your zip file when unpacked will contain the following files:

Note that the webapp2 folder contains the files for the current web app and can be ignored when customizing the legacy web app.

If you are customizing the files on a legacy web app that you are hosting on an external server or reverse proxy, these files are stored in the /opt/pexip/share/web/static/app/configuration directory.

The files that can be customized are summarized below, and are then explained in more detail in the subsequent sections:

• The settings.js file contains the application and default user settings.
• The favicon.png file contains the icon used to represent the application within the browser's address bar and bookmarks (for the web app) and the application title bar and the Window's system tray (for the desktop client).
• The languages subfolder contains the text strings for each language. By default, English is the only available language and the text strings are contained in the en-us.json file. You can add more languages if required.
• The green.svg and red.svg files apply only to the Infinity Connect desktop client. They are applied to the application icon in the Windows system tray to indicate respectively if the application is registered successfully, or cannot register due to an error. No image is displayed if the Infinity Connect desktop client is not configured to register.

• The themes/default subfolder contains the files used to control the colors, styles and images used within the application. The folder contains:

  • brand.css: the application's stylesheet.
  • background.jpg: referenced from brand.css and contains the home page background image.
  • conference-avatar.jpg: referenced from settings.js (although commented out by default), this is the image used to represent the conference at the top of the participant list. By default, the avatar shown is served from the Conferencing Node and is part of the conference theme (presence_avatar_image.jpg). If enabled in settings.js, this will override what is shown. Note that participant avatars cannot be branded here, but they can be controlled by using external policy (see More information).
  • logo.png: referenced from brand.css and contains the image shown on the home page.

  The following screenshots show the default branding and indicate which elements of the application are controlled by the various image and CSS elements.

  

  

  

If you change the file type of any of the image files, for example, you use a conference-avatar.png file instead of a conference-avatar.jpg file, you must change the reference to that filename in the appropriate settings.js or brand.css file.

If you refer to any additional custom images as part of your customization, those image files should also be stored within this directory structure.

The default settings for the appearance of Infinity Connect are hard-coded within the application itself, and are used automatically where no customization overrides are specified. Therefore, you can modify a subset of the branding files in the configuration directory (for example, only changing some of the images or aspects of the CSS), and then remove the other unmodified files to ensure that the default branding for those elements is always applied in the future. If you are customizing the legacy web app and want to change the background.jpg or logo.png graphics files, you must also include a brand.css file that at least includes the references (brand-logo and brand-background classes) to those customized images.

Application and default user settings (settings.js)

The settings.js file contains the application and default user settings. The following items in the applicationSettings block can be configured:

The defaultUserSettings block in the settings.js file contains the default user settings that are applied to first-time users. The application subsequently remembers the user's last-used settings. The configurable options are:

sideBarHiddenInGW: true,
defaultDomain: "example.com",
registrationHost: "conferencingnode1.example.com",
serverAddress: "conferencingnode1.example.com",
};

"IDS_SETTINGS_TITLE": "Settings",

"IDS_PARTICIPANT_MUTE": "Mute {{displayName}}",

"Call Failed: Invalid role": "Invalid pin",

bandwidths: [{
    name: 'IDS_BANDWIDTH_LOW',
    value: 192 + 64
  }, {
    name: 'IDS_BANDWIDTH_MEDIUM',
    value: 512 + 64
  }, {
    name: 'IDS_BANDWIDTH_HIGH',
    value: 1200 + 64
  }, {
    name: 'IDS_BANDWIDTH_MAXIMUM',
    value: 1800 + 64
  }],
        

Application styles, colors and images

The themes/default subfolder contains the files used to control the colors, styles and images used within the application:

Changing the application styles and colors (brand.css)

The themes/default/brand.css file is the application's stylesheet. It contains the following styles:

Background image for the home page and conference stage (background.jpg)

The themes/default/background.jpg file is referenced from brand.css and contains the background image shown on the home page and on the conference stage. By default, the background image covers the whole browser window and scales if the browser window resizes. This behavior can be customized in the brand.css file. The default background image is a picture of clouds.

By default the image is obscured from view on the conference stage due to the settings of the stage-background style.

To change the background image, replace the existing background.jpg file with a new file of the same name. We recommend using a JPEG image (for smallest file size) that is approximately 2000x1400 pixels.

Conference avatar (conference-avatar.jpg)

The themes/default/conference-avatar.jpg file is referenced from settings.js and is used to represent the conference at the top of the participant list.

By default, the reference to conference-avatar.jpg in settings.js is commented out. This means that the default conference avatar — which is the presence_avatar_image.jpg file in the conference theme — is always used. (If the default conference theme is in use, then the avatar image is the Pexip logo.)

To change the conference avatar:

1. Replace the existing conference-avatar.jpg file with a new JPG file of the same name.

   The image is automatically scaled to 40x40 pixels and rounded by the application.

2. Remove the '//' comment markers from the overrideConferenceAvatar entry in the settings.js file.

Home page logo (logo.png)

The logo.png file is referenced from brand.css and contains the image shown on the home page. The default logo is the Pexip logo.

To change the logo, you should replace the existing logo.png file with a new PNG file of the same name. The logo image is used "as is", so we recommend using a PNG image (for best quality) and that the logo is approximately 200x100 pixels and has a transparent background.