Edit

Custom Clients (Pro Plan)

This guide walks you through the steps of setting up and removing a custom client on your Hub for Professional plan subscribers.

Table of Contents
      Introduction
      Prerequisites
      Part A: Set Up the Hubs Client
      Part B: Prepare Your Custom Client Tarball
      Part C: Locate Your turkeyauthtoken
      Part D: Deploy Your Custom Client
      Removing Your Custom Client

Introduction

Deploying a custom client to your Hub allows you to fully control the appearance and functionality of the Hubs 3D engine and frontend code. This feature is intended for subscribers with at least a beginner level of javascript development experience. Please be advised that deploying a custom client disables the automatic updates that the Hubs Team regularly deploys to subscription instances. You can follow our regular updates here.

If you need more assistance, we recommend following along with our Custom Client Tutorial Video.

Prerequisites

  1. You must have a Custom Domain deployed on your Hub before you can upload a custom client.

  2. Make sure you have docker installed on your device. Testing for this feature utilized docker version 20.10.21.

Part A: Set Up the Hubs Client

  1. Clone the Hubs github repository onto your device. Users deploying custom clients to subscriptions should use the master branch of the repository.

  2. Install the project's node dependencies by running npm ci. Make sure you are using node version 16.16. This process may take up to 30 minutes.

  3. Change directory into the folder of your project and run npm run dev to start a development server. Once the code has compiled, you will be able to access this development server at localhost:8080 on your web browser.

  4. Add your customizations to the Hubs code. See the For Developers section of these docs for information about how to get started with your customizations.

   Troubleshooting

  • The backend dev server is configured with CORS to only accept connections from "hubs.local:8080", so you will need to access it from that host. To do this, you likely want to add "hubs.local" and "hubs-proxy.local" to the local "hosts" file on your computer:
127.0.0.1       hubs.local
127.0.0.1       hubs-proxy.local

Part B: Prepare Your Custom Client Tarball

  1. Change directory to the main folder of your project, make sure you have docker opened, and run bash retpack.sh

  2. The code may take up to an hour to complete depending on the size of your customizations and processing power of your computer. Once complete, it will return the following message and your tarball will be located at ./.retpack/retpack.tar.gz.

### done ###
-rw-r--r--@ 1 mozilla staff {timestamp} ./.retpack/retpack.tar.gz

   Troubleshooting

  • If npm ci fails during the build process, there are a couple of options to fix this. First, verify that you are using node version 16.16.0. Second, if you are using a Mac computer with M1 silicon, run export DOCKER_DEFAULT_PLATFORM=linux/amd64 before running bash retpack.sh.

Part C: Locate Your turkeyauthtoken

  1. Open the developer tools in the subscription dashboard and navigate to the “Console” tab.

  2. Run the following code in the console to get your token: console.log(RegExp("_turkeyauthtoken"+"=[^;]+").exec(document.cookie)[0].slice(17))

  3. Copy the long string of characters to be used in Part D. Please note that turkeyauthtokens are only valid for 12 hours.

Part D: Deploy Your Custom Client

Deploying a custom client will disable the automatic updates that the Hubs Team regularly deploys to subscription instances. If you choose to use a custom client, you are responsible for keeping up with these regular updates to ensure your code is functional.

  1. Open your terminal, and run the following command with the 3 parameters surrounded by < > populated with your specific information from previous steps:
    curl -X POST -F file='@<path-to-client-tarball-on-your-device>' -H "turkeyauthtoken:<token-value-from-part-c>" 'https://<native-hub-domain>/api/ita/deploy?app=hubs'

  2. The terminal command may take several minutes to complete depending on the quantity and nature of your customization. Do not exit the terminal until the upload process has completed. Once successfully complete, it will return done, reqId: <unique-ID-string>. After a few minutes, you should see your customization on your Hub.

  3. After deploying, try to create a room to verify your customizations have taken place. If you are unable to see your customizations, email hubs-feedback@mozilla.com with the subject line Hubs Custom Client Deployment Troubleshooting and a description of your problem.

Removing Your Custom Client

Removing a custom client will re-enable the automatic updates that the Hubs Team regularly deploys to subscription instances.

  1. Open your terminal, and run the following command with the 2 parameters surrounded by < > populated with your specific information from previous steps:
    curl -X PATCH -H "turkeyauthtoken:<token-value-from-part-c>" 'https://<native-hub-domain>/api/ita/undeploy?app=hubs'

  2. The terminal command should execute quickly and return the value done. After a few minutes, you should be able to access your Hub and should no longer see your customizations.