Customizing and branding the Pexip apps

The branding and styling of the web apps and Connect desktop app can be customized. This changes the look and feel of the Pexip 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.)

Pexip app customization can be used to control:

default app settings such as bandwidth, default background image, screen sharing frame rate
default user settings such as whether microphone and camera are muted on join
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 Pexip web apps you typically create a branding package and then upload it to the Management Node. You can use Pexip's branding portal to quickly and easily create branding packages, or you can create them manually for more advanced customizations.

To customize the Connect desktop app, you use the same customized branding files as for Webapp2. You then use either Pexip Infinity's provisioning features or a locally-installed branding file to instruct those clients to override their built-in branding and use the customized branding instead.

This topic explains the two main steps in applying branding to web apps in your deployment:

Creating a branding package:
- using the Webapp3 branding portal
- by downloading an existing package for editing (including any of the branding packages that are provided by default).
Uploading the branding package to the Management Node so that it is available to all users.

It also includes information on:

Updating an existing package
Removing a package (reverting to default branding)
Applying branding to the Connect desktop app

Creating a branding package using the portals

You must create a branding package before you can upload it to the Management Node or use it to brand the Connect desktop app. Our recommended method for creating a branding package is to use the branding portal for Webapp3 (although you can also create the required files manually). These web-based portals guide you through the selection of your image files and colors (without having to edit individual CSS files etc.), and then generate the customized branding package for you.

Using the Webapp3 branding portal

Go to the Pexip branding portal for Webapp3 (https://branding.pexip.io/).
Select one of the options:
- to create a completely new package, select New brand
- to use an existing package as the basis of your new package, select Load existing brand.

From the panel on the left, select each option and edit it to suit your brand's requirements.

The image below shows what elements of the web app can be customized. The table that follows describes each option in more detail. If you are intending to edit the resulting branding package manually, it also gives the section within the manifest.json file where that element is defined.

Option	Description	Definition in manifest.json
Welcome to	Specifies the text that appears under the card image on the landing page.	"brandName"
Logo	An optional image/logo file that can be displayed at the bottom of the area on the left side of the landing page. This file must meet the following requirements: transparent maximum displayed width: 168px maximum displayed height: 80px format: we recommend .SVG	"logo"
Brand color	Specifies a color that the branding portal will use as a base to automatically generate the range of colors used for interactive elements of the user interface, such as buttons and text. You can use the color picker tool to select a color from any of the images you have already uploaded.	"baseColor" "colorPalette"
Background color	Specifies the landing page's background color if no background image is specified. You can use the color picker tool to select a color from any of the images you have already uploaded.	"backgroundColor"
Card image	An optional image/logo file that can be displayed at the top of the area on the left side of the landing page. This file must meet the following requirements: resolution: 640x360 size: 70-140 kB format: .JPG, .JPEG, .PNG or .WEBP	"jumbotron"
Background image	An optional image to display behind all other elements on the landing page. Supported file formats are: .JPG .JPEG .PNG .WEBP Background image files must meet the following requirements: resolution: 1920x1080 size: 500-600 kB	"background"
Overlay	Determines the contrast between the background and overlay text..	"overlay"
Overlay opacity	Determines the degree to which the background image is darkened or lightened.	"overlayOpacity"
Application title	Specifies the text that appears on the browser tab when using the Pexip web app.	"appTitle"
Terms of service	Specifies the URL to which the "terms and services" text on the user name step of the join flow is directed.	"termsAndConditions"
Disconnect destination	Specifies the URL to which users are directed when a call is completed (instead of returning to the app home page).	"disconnectDestination"
Handle OAuth 2.0 Redirects	(Supported in Pexip Infinity v34 and later) Enables support for features (such as plugins) that require authentication to a third party using an OAuth 2.0 / OpenID Connect flow, with a redirect destination of webapp3/oauth-redirect.	"handleOauthRedirects"

When you have finished configuring your branding, from the top right of the page select Download.
This creates and downloads a brand.zip file containing your client customizations.
If you wish to make further customizations you can unpack the file, edit it, and then re-zip it. See Manually customizing Webapp3 for full information.
Upload the branding package to your Management Node.

Downloading an existing package

As an alternative to using the branding portals to create new branding packages, you can download, edit, and upload an existing branding package. This might be a default branding package downloaded from the Management Node, a package previously created using the branding portals, or a package downloaded from previous versions of Pexip Infinity.

Manually editing an existing package is useful if you have very specific modifications that you want to apply to the branding files, or if you are including plugins. Note that manual configuration requires knowledge of core web-design technologies such as HTML, JavaScript and CSS.

This section covers how to obtain branding packages.For full information on manually editing these packages, see Advanced Pexip app branding and customization.

Downloading branding packages from the Management Node

Pexip Infinity includes a number of default branding packages that you can download and edit to create your own customized branding. For full details, see Default branding packages. In addition, if you have existing custom branding files uploaded for any of the three web apps, you can also download and use these as the basis on which to apply your modifications.

You may also wish to download an existing branding package in order to upload it to an external server if you are hosting the web app externally.

To download an existing branding package from the Management Node:

Go to Web App > Web App Branding.
Select the Pexip branding package for the relevant web app version and then from the bottom of the detail page select Download.
A ZIP file containing the selected branding files is downloaded to your local file system.
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 Pexip app branding and customization.
Repackage your branding files into a single ZIP file. This file must have a different name to any packages already uploaded. If you are editing an existing branding package, after uploading simply redirect the current path to point to this new package.
The ZIP file must contain the complete set of branding files. You must retain the original file/folder structure in the rebuilt ZIP file.
You must include the manifest.json file in the webapp3/branding folder.
Upload the branding package to your Management Node.

Editing an existing package

You can also use as the basis of your new branding packages any other existing branding packages. These might be downloaded from previous versions of Pexip Infinity, from either of the branding portals, or be packages that you created entirely manually. Simply ensure that these packages meet the current branding requirements outlined in Advanced Pexip app branding and customization, before zipping and uploading the new package.

Uploading the branding package

Branding packages are uploaded as .ZIP files. The files must contain the required branding files in a webapp3/branding subfolder.

To upload a branding package to your Management Node:

Go to Web App > Web App Branding.
From the bottom of the page, select Add Webapp branding package.

On the Add Webapp branding package page, enter the following information about the package you wish to upload:

Name	The name for this branding package.
Description	An optional description of this branding package, to help you identify it easily.
Web app version	Select the web app version to which this branding package will apply.
Branding package to upload	Select Choose File and select the ZIP file containing your customizations.

Select Save.
The branding package is verified and uploaded.
After the branding package is uploaded, to use it you must select it for use with one or more web app paths, creating a new path if necessary.

Any changes you make to branding packages and paths must be replicated out to all Conferencing Nodes before being available (typically after approximately one minute).

Updating an existing package

To make changes to a branding package already in use in your deployment:

Download the old branding package and edit it with your updates.
Save the updated branding package as a ZIP file.
Upload the updated branding package (Web App > Web App branding), giving it a different name to the existing version.
Edit all paths that use the old version of the branding package so that they use the new version instead.
Delete the old branding package.

Don't delete the old branding package before uploading the new package and redirecting to it. If you do, all the paths that used the deleted package will revert to using the default branding, meaning that participants will experience the default branding until you have redirected the relevant paths to use the new package.

Removing a package (reverting to default branding)

Default branding packages cannot be deleted. You can remove customized branding in one of two ways:

If you wish to keep the branding for possible later use, simply edit the paths that currently use that package, so that the paths either use a different branding package, or use the default branding.
If you no longer wish to keep the branding package, delete it. Any paths that point to deleted branding packages will revert to using the default branding.

To delete a branding package:

On the Management Node, go to to Web App > Web App Branding.
Select the tick boxes next to the branding packages you wish to remove.
From the Action drop-down, select Delete selected Web app branding packages.

Wait for the customized branding to be removed from all Conferencing Nodes (typically after approximately one minute). After this time, all new participants accessing the path will see the default branding. Note however that any participants currently using the deleted package will continue to see the deleted branding until they refresh their browser.

Applying branding to the Connect desktop app

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

Applying branding using provisioning

To apply branding using provisioning, you specify the brandingURL provisioning parameter when you construct each individual Connect desktop app 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 Pexip 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 Connect desktop app'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 Connect mobile apps, and the Connect desktop app branding can no longer be hosted on Conferencing Nodes.

Creating and signing a branding package for the Connect desktop app

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

Create your branding.zip file.

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}"

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.
Connect over ssh into the Management Node as user admin with the appropriate password.
Run the following commands:
cd /dev/shm
chmod 0755 mkjwt.sh
Run the following command to generate the .sig file:
./mkjwt.sh privatekey.pem branding.zip >branding.zip.sig
Run the following command to remove the private key file:
rm ./privatekey.pem
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 Connect desktop app will not automatically use the customized branding package (as referred to at the provisioned brandingURL location).

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