Customizing and branding the Connect apps

The branding and styling of the Connect web apps and Connect desktop app can be customized. This changes the look and feel of the Connect app regardless of which service is being accessed. (However, the theme-based elements of each individual service may also have been customized — a theme changes the look and feel of the actual conference you have joined, or are trying to join.)

Connect app customization can be used to control:

  • default settings such as bandwidth, screen sharing frame rate and so on
  • the ability to display an image/logo and accompanying welcome text on a landing page, and to use a custom favicon
  • language translations and the default language
  • the color scheme for buttons, icons and other graphic indicators; elements can be customized individually or a general color scheme can be applied to all similar items.

To customize the Connect web apps you typically create a branding package and then upload it to the Management Node. Separate branding packages are required for each of the web apps in use in your deployment. The relevant branding package is then automatically applied to all users of that Connect web app. To apply the same customized branding to the Connect desktop app you need to use Pexip Infinity's provisioning features to instruct those clients to override their built-in branding and use the customized branding instead.

Branding customizations that are applied to each Connect web app via the Management Node will apply to all revisions of that web app, and 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).

The instructions in this topic describe how to create and upload, edit and remove a branding package, and how to apply the branding to the desktop clients.

Note that the procedures described here apply a generic customization for all users of each Connect app. If you have specific customization requirements, such as hosting multiple different branding customizations for web app users under different URLs on external web servers or reverse proxies, see Advanced Connect app branding and customization.

Creating and uploading a branding package

You must create a branding package before you can upload it to the Management Node or use it to brand the desktop client. Our recommended method for creating a branding package for the previous web app ("Webapp2") is to use the Pexip branding portal (https://brandingportal.pexip.com), although you can also create the required files manually. For the latest web app, Pexip Connect for Web ("Webapp3"), you must currently create the required files manually; a branding portal for this version will be available soon.

Creating a branding package via the Pexip branding portal

This option is not currently available for the latest web app, Pexip Connect for Web ("Webapp3").

You can use the Pexip branding portal to customize the Connect web app and Connect desktop app. This web-based tool guides you through the selection of your image files and colors without having to edit individual CSS files etc, and then generates the customized branding package for you.

To use the Pexip branding portal to generate your branding package for the Connect apps:

  1. Go to the Pexip branding portal (https://brandingportal.pexip.com) and sign in.

    First time users need to register before they can use the portal.

    You can also use the portal to create customizations for the legacy web app if required.

  2. Select which version of Pexip Infinity you have installed, so that the relevant branding and customization features can be offered.
  3. From here you can choose to create new customizations, or edit an existing customization that you have previously created. Configure your customization as required, selecting the relevant image files, colors and settings:

    • The App Editor changes the look and feel of the Connect apps, including enabling an image/logo on the landing page.
    • The Customizations section controls the client's configuration settings, including default options, languages and plugins.
    • The Splash Screens section doesn't directly affect the Connect apps. It is used to customize the Pexip Infinity themes (which are used when you join a VMR or other service either via a Connect app or other endpoint) and generates a separate ZIP package when built.
    • The Languages section allows you to set up additional languages for the Connect app, or to create a modified version of the default English text strings. When creating a new set of language strings the Name is the name you will see within the portal, and the Label is the name users will see within the app; the Locale enables that language to be used automatically if it matches the browser's default language. If you set up new language option then you must use the Customizations section to select the new/modified languages you want to include in your branding package (and deselect the original English language strings if required).
  4. When you have finished configuring your branding, go to the Dashboard, select the relevant App Edits and Customizations and then Build your customization package. If you have added new languages they are automatically included in your build depending upon which languages are selected in the Customization.

    This creates and downloads a branding.zip file containing your client customizations.

  5. Upload the branding package to your Management Node:

    1. Go to Services > Web App customization.
    2. In the Upload Web App branding section, select Choose File and select the ZIP file containing your customizations.
    3. Select Upload branding.

      The branding package will be uploaded. The upload process automatically detects which type of app branding is contained in the ZIP file and processes it accordingly.

    Wait for the new branding to be replicated out to all Conferencing Nodes (typically after approximately one minute).

This branding package is used to customize the Connect web app by default, but you can also automatically apply the same branding to the Connect desktop app.

Manually configuring the branding files

Manual configuration is currently required for the latest web app, Pexip Connect for Web ("Webapp3"). It is also useful if you have plugins or very specific modifications that you want to apply to the branding files. Note that manual configuration requires knowledge of core web-design technologies such as HTML, JavaScript and CSS.

To manually configure the branding files:

  1. Download the default web app branding files from the Management Node:

    1. Go to Services > Web App customization.
    2. In the Download web app branding section, next to the Download default branding label, select Download.

      This downloads a branding_combined_default.zip file to your local file system.

    Note that if you have existing branding files uploaded for any of the three web apps, the Download web app branding section will also offer you the option to Download the custom branding files for that specific web app, which you can use instead of the default files as the basis on which to apply your modifications. You can also use files that were originally created by the Pexip branding portal — both methods use the same set of configuration files. You could use the branding portal to apply your basic customization requirements and then make further manual amendments to the configuration files if necessary.

  2. Unpack the downloaded file and apply your modifications to the relevant files.

    The contents of the branding files and how to modify them is fully described in Advanced Connect app branding and customization.

  3. Repackage your branding files into a single ZIP file (<name>.zip).

    The ZIP file does not have to contain the complete set of branding files. You can upload a subset of the branding files, but you must retain the original file/folder structure in the rebuilt ZIP file. For example, if you have no need to customize the legacy web app files you only need to zip up the webapp2 folder.

    You must include the manifest.json file in the webapp2 folder.

    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.

  4. Upload the branding package to your Management Node:

    1. Go to Services > Web App customization.
    2. In the Upload Web App branding section, select Choose File and select the ZIP file containing your customizations.
    3. Select Upload branding.

      The branding package will be uploaded. The upload process automatically detects which type of app branding is contained in the ZIP file and processes it accordingly.

    Wait for the new branding to be replicated out to all Conferencing Nodes (typically after approximately one minute).

You can now test the branding by dialing in to one of your Pexip Infinity services via the relevant Connect web app.

Editing an existing branding package

You can modify an existing branding package by either returning to the Pexip branding portal, or manually editing the branding files that were uploaded previously to the Management Node.

Note that when you upload a new branding package to the Management Node all of the previous branding files for that app are deleted and replaced with the new set of files.

Using the branding portal

If you initially created your branding package via the Pexip branding portal, you can return to the portal and change those files:

  1. Go to the Pexip branding portal (https://brandingportal.pexip.com) and sign in.
  2. Make your changes, previewing them if necessary, and then download a new ZIP file.
  3. On the Management Node, go to Services > Web App customization and upload your new branding ZIP file.

Wait for the new branding to be replicated out to all Conferencing Nodes (typically after approximately one minute).

Manually changing your existing web app branding on the Management Node

You can manually edit the existing branding files that have been uploaded to the Management Node (even if those files were originally created via the Pexip branding portal):

  1. On the Management Node, go to Services > Web App customization.
  2. Download the existing branding files:

    • To download the system default branding files, in the Download web app branding section, next to the Download default branding label, select Download.
    • If customized branding has been uploaded for any of the three web apps, the Download web app branding section will also offer you the option to Download the custom branding files for that specific web app.
  3. Unpack the downloaded file and apply your modifications to the relevant files.

    The contents of the branding files and how to modify them is fully described in Advanced Connect app branding and customization.

  4. Repackage your modified branding files into a new ZIP file.

    If you are also modifying the legacy web app files, you can package the legacy and Webapp2 files as two separate ZIP files i.e. one ZIP containing legacy branding and one ZIP containing Webapp2 branding, thus matching the ZIP packages you downloaded. You can also combine them into one ZIP package, but it must match the file structure that is produced when downloading the default branding files.

  5. Upload the new ZIP file back onto the Management Node (Services > Web App customization then Choose File followed by Upload branding).

    The upload process automatically detects which type of app branding is contained in the ZIP file and processes it accordingly.

Wait for the new branding to be replicated out to all Conferencing Nodes (typically after approximately one minute).

Removing a web app branding package (revert to default branding)

If you want to revert to the default branding for any version of the web app, you need to remove your customized branding from the Management Node. To do this:

  1. On the Management Node, go to Services > Web App customization.
  2. From the bottom-right corner of the page, select the appropriate button (e.g. Remove Webapp2 branding to remove the branding for Webapp2 users).

Wait for the customized branding to be removed from all Conferencing Nodes and for the web app to revert to the default branding (typically after approximately one minute).

Applying branding to the desktop clients

Any branding package that is uploaded to the Management Node is only applied to the Connect web app.

To apply the same customized branding to the Connect desktop app you need to use Pexip Infinity's provisioning features to instruct those clients to override their built-in branding and use the customized branding instead. This is achieved by specifying the brandingURL provisioning parameter when you construct each individual desktop client user's provisioning URI.

  • The brandingURL parameter must refer to a directory on an accessible server that contains the branding package.
  • The branding package must be signed, and the client must upload a trusted (public) key before the branding can be applied.
  • The branding package must be presented as a branding.zip file and an associated branding.zip.sig file.

For example, if brandingURL = pexample.com/foo, then you need to provide pexample.com/foo/branding.zip and pexample.com/foo/branding.zip.sig.

After a Connect app has been provisioned with a brandingURL provisioning parameter, every time it launches it checks the contents of the branding files at the brandingURL location to see if the branding has changed (it checks to see if the brandingID in the manifest.json file has changed). If the branding has been updated, the client fetches and caches the relevant files.

Note that the desktop client's favicon, taskbar/tray icons and app name cannot be updated via branding as these elements are fixed during the installation of the client software.

See Registering and provisioning the Connect desktop app for full instructions about how to set up provisioning URIs. Note that the client does not need to be registered in order to use the branding provisioning feature.

Note that as of version 1.8 you cannot apply branding to the mobile clients, and the desktop client branding can no longer be hosted on Conferencing Nodes.

Creating and signing a branding package for the desktop clients

The branding package in the brandingURL location must be presented as a branding.zip file plus an associated branding.zip.sig file that contains the package's signature.

Contents of branding.zip

Typically we recommend that you use a branding.zip file produced by the Pexip branding portal as this is a suitable zip file/format and contains all of the relevant content (although you must still sign it yourself).

The manifest.json is automatically generated by the Pexip branding portal and includes the brandingID timestamp and also indicates which parts of the app are customized.

If you want to create your own branding.zip file then it must contain a webapp2 folder as its root folder and that must then have the following structure/contents:

  • manifest.json (mandatory)
  • settings.json (optional)
  • watermark_icon.png (optional)
  • favicon files (optional, applies only to the web app)
  • site.webmanifest (optional)
  • themes directory containing styles.css (both optional)

as shown below:

Full details of the structure of the manifest.json file and the other application files are contained in Advanced Connect app branding and customization.

Signing the branding package

You must use JSON Web Token (JWT) to sign the package. (JWT is an open standard that defines a way for securely transmitting information between parties as a JSON object.)

As part of the process to sign the branding package you need a public/private keypair. You may already have a keypair that you can use for this process, or you can use a third-party tool such as PuTTYgen to generate a keypair. The key must be in RSA format and at least 2048 bits. Alternatively you can log in to your Management Node over SSH and run the following commands to generate a private and public key pair:

openssl genrsa -out /dev/shm/privatekey.pem 2048
openssl rsa -in /dev/shm/privatekey.pem -pubout -out /tmp/publickey.pem

To sign the branding package and create your .sig file:

  1. Create your branding.zip file.
  2. Using a plain text editor, create a shell script file called mkjwt.sh containing the following code:

    Copy to clipboard
    #!/bin/sh

    set -e

    if [ $# -ne 2 ]; then
      echo "Usage: $0 <privatekey.pem> <branding.zip>" >&2
      exit 1
    fi

    HEADER="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9"
    HASH=$(openssl dgst -sha256 $2 | sed -e 's/^[^ ]* //')
    PAYLOAD=$(echo -n "{\"sha256\":\"${HASH}\"}" | base64 -w0 | sed -e 's/\+/-/g' -e 's/\//_/g' -e 's/=//g')
    SIG=$(echo -n "${HEADER}.${PAYLOAD}" | openssl dgst -sha256 -sign $1 | base64 -w0 | sed -e 's/\+/-/g' -e 's/\//_/g' -e 's/=//g')

    echo "${HEADER}.${PAYLOAD}.${SIG}"
  3. Copy your private key file (named privatekey.pem), the branding.zip file and the mkjwt.sh file into the /dev/shm directory on the Management Node using an SCP (Secure Copy) client, for example WinSCP.
  4. Connect over ssh into the Management Node as user admin with the appropriate password.
  5. Run the following commands:

    cd /dev/shm

    chmod 0755 mkjwt.sh

  6. Run the following command to generate the .sig file:

    ./mkjwt.sh privatekey.pem branding.zip >branding.zip.sig

  7. Run the following command to remove the private key file:

    rm ./privatekey.pem

  8. Use the SCP client to copy the generated branding.zip.sig file to your local machine.

Using the branding package on the desktop client

The client will not automatically use the customized branding package (as referred to at the provisioned brandingURL location).

Each client user must first import a trusted key via Settings > Advanced settings > Import trusted key and confirm that they want to apply the branding. The trusted key file they need to import (i.e. that you need to distribute) is the public key file used as part of the key pair used to create the JWT signature.

Only distribute the public key. Do not distribute the private key.