WebHID API | Jabra JS SDK

Overview#

The WebHID API is a new Web standard available in Chromium-based browsers version 89 and newer.

The Jabra library can work with WebHID, eliminating the need for the Jabra Native Console App and Chrome Extension. This comes with some limitations, which are described in section Known limitations.

See code sample

How to use#

By default, the library will attempt to use the Chrome Extension along with the Native Console App when communicating with headsets. In order to begin using WebHID, an additional configuration parameter must be provided to the initialization function. Setting the optional transport startup parameter on the IConfig interface allows the user to determine if the default behaviour should be overridden.

Setting the transport parameter to RequestedBrowserTransport.WEB_HID will tell the Jabra library to use WebHID if available or throw an error if the browser does not support it. Alternatively, setting the transport parameter to RequestedBrowserTransport.CHROME_EXTENSION_WITH_WEB_HID_FALLBACK means that the Jabra library will first try the default setup (Chrome Extension with Native Console App) but will use WebHID as a fallback if any of these are not installed.

The process of initializing the library to use WebHID is similar to that described in the Getting started with Jabra SDK. The only difference is the need to specify the optional transport startup parameter:

// Make sure to import the RequestedBrowserTransport enum
import { init, RequestedBrowserTransport } from '@gnaudio/jabra-js';

async function app() {
  const config = {
      transport: RequestedBrowserTransport.WEB_HID // or CHROME_EXTENSION_WITH_WEB_HID_FALLBACK
  };

  // Initialize Jabra library using the optional config object
  const jabra = await init(config);

  // Proceed as before
}

app();

You will need to modify the rest of your solution to account for the limitations and differences that come with using WebHID, e.g. asking for user consent in order to get access to a device.

This also means you will require knowledge of which of the two solutions was used during initialization. For this, the IApi object that is returned has an additional property, transportContext, which provides that information:

if (jabra.transportContext === TransportContext.WEB_HID) {
    // Execute WebHID-specific logic
} else {
    // Execute Chrome-Extension-specific logic
}

Known limitations#

Using WebHID comes with some limitations. In this section, we provide context and possible solutions to these limitations.

Browser support#

The WebHID API can be used with Chromium based browsers, starting with Chromium version 89.

For more details on version support and release dates, check here.

User consent#

Security protocols require user consent before your app can access a device. This is required on a per-device level, and the user can remove that consent at any point. When the user connects a new device, the device will only show up if consent was previously given to said device.

This consent has to be granted via a user action on a visible UI element (e.g. clicking on a button). Trying to grant consent programmatically will result in an exception. The Jabra library provides an access point for the necessary consent logic via the webHidPairing function. Your solution must use it only as a response to user interaction with your solution (e.g. clicking on a "start call" button):

import { webHidPairing } from '@gnaudio/jabra-js';

// Make sure to call the webHidPairing function upon user interaction
document.getElementById('your-consent-button').addEventListener('click', async () => {
  await webHidPairing();
});

// Do not try to get consent without user interaction
await webHidPairing(); // Will result in an Exception thrown

As noted above, this requirement is limited to WebHID only. Therefore, your solution should only show the button when using WebHID. The following example shows how you can show/hide the button in case your solution supports both WebHID and the Chrome Extension:

import { webHidPairing } from '@gnaudio/jabra-js';

if (jabra.transportContext === TransportContext.WEB_HID) {
  // Show the consent button
  document.getElementById('your-consent-button').classList.remove('hidden');

  // Call the webHidPairing function upon user click
  document.getElementById('your-consent-button').addEventListener('click', async () => {
    await webHidPairing();
  });
}

Once the user gives consent, the device will show up thanks to a new ISdkDevice being emitted to the deviceAdded observable as well as a new set of connected devices being emitted on the deviceList observable.

Refreshing the tab will keep the device pairing, and consent will not be required for it again (unless the user deletes their cache or manually revokes consent).

Call Locks#

Call locks in WebHID are not compatible with existing call locks. This means that a call lock can be acquired by a standard solution and a separate WebHID solution at the same time, granting both access to the device.

Furthermore, due to limitations in the Web Locks standard used in WebHID, call locks in WebHID are also domain-exclusive and browser-exclusive. One softphone acquiring a lock will not interfere with another softphone trying to acquire a lock. The same softphone acquiring a lock in Google Chrome will not interfere with the same softphone trying to acquire a lock in Microsoft Edge.

Softphone co-existence#

The feature is not supported. Currently, the "preferred softphone" feature is controlled by Jabra Direct, and a WebHID-based solution has no way of communicating with it.

Initiate a call from a device#

The feature is not supported.

Device ID#

For security reasons, the ID of a device will differ across different tabs.