Creating a Custom UI From Scratch#

Overview#

This guide will help get you started with creating your own UI from scratch to replace the Tokkio reference UI.

Warning#

This approach is not recommended at this time for the following reasons:

  • The interface between the UI and the rest of the app is subject to change without warning for most releases. A UI built from scratch requires one to keep up with these interface changes when you update your version of Tokkio. Building from a custom layout within the reference UI will shield you from these interface changes.

  • A UI built from scratch will not be able to take advantage of pre-built features available in the reference UI out of the box. Each of these features will need to be re-implemented in the new UI.

  • You may run into unexpected bugs related to an incorrect use of the interfaces with Ingress, the Tokkio UI Server, or VST.

In short, the reference UI gives you a quick way to set up a custom design and maintain it across releases. When creating a UI from scratch, additional effort will be required to both create and maintain the UI.

Prerequisites#

Before going through this section, ensure that you have done the following:

  • Deployed your Tokkio application.

  • Deployed the reference UI to make sure that everything is working end to end. You should be able to see and hear the avatar. Ensure that you are able to have a conversation with the avatar before starting.

  • Familiarized yourself with the reference UI codebase. Even if you will not use this code, some of it will likely be duplicated in your custom UI. Read the Customize the Tokkio Reference UI before following these steps.

This section is for advanced users only. To follow this section, you must be familiar with the VST, Ingress, and ACE Controller microservices, and have a working understanding of their interfaces. You must also be an experienced web developer.

Minimal Components for a UI to Work#

For a UI to connect to Tokkio and access all the features, it must implement the following:

  • Recurring call to Ingress to fetch session cookie

  • Create an instance of the VST Streaming Library for the avatar video connection

  • Connect to the ACE Controller over WebSocket for bi-directional communication with the ACE Controller pipeline (used to get all of the UI features, not required to see avatar video)

To get the session cookie from Ingress, make the following API call: GET http(s)://<ingress endpoint>/token. This API will return a response that looks like this: {"token_ttl":"30","token":"77234b6a-89e0-4b37-8bb7-c33e0d2a7183"}. Take the token and add it as a cookie to all subsequent requests to the Tokkio deployment. The cookie should be of the following format: Session=77234b6a-89e0-4b37-8bb7-c33e0d2a7183. To keep your session alive, call this endpoint every 15 seconds, and ensure that the session cookie is present in these subsequent API calls.

Once you have your session cookie, initialize the VST connection via the VST Streaming Library. See the code in the reference UI (src/features/avatar-window directory) for an example of how this is done. The vstWebsocketEndpoint parameter should be set to ws(s)://<ingress endpoint>/vms/ws.

Next, make a WebSocket connection to the ACE Controller through Ingress. The connection endpoint is ws(s)://<ingress endpoint>/ace/ws.

Now that you have made the necessary connections, you should be able to see the avatar video and communicate with the ACE Controller. For any additional features, please refer to the reference UI for how these should work.

On this page