Initializing the Jabra library

Installing the library package

A prerequisite to importing and initializing the Jabra library modules is to install the Jabra npm package in your development environment.

• Using a terminal or command prompt, install the npm package as follows:

npm install @gnaudio/jabra-js

Enabling your web application to use Jabra Devices

Web browsers offer limited access to the underlying operating system, and by consequence, limited access to Jabra devices.

For your web application to use Jabra device functionality, Jabra supports the following three options for communicating with your devices.

• Option 1 -- Download and install runtime components
• Option 2 -- Using WebHID
• Contingency Installation -- WebHID fallback

On the one hand, in option 1, if you download and install runtime components you can bypass browser limitations to use Jabra device functionalities, but it comes at the expense of downloading and installing extensions.

On the other hand, in option 2, if you choose to use WebHID additional installations are not needed. However there are limitations in accessing advanced Jabra device functionality.

In Contingency Installation, you are combining options 1 and 2, where WebHID acts as a fallback whenever runtime components are not available or possible. Unavailability of runtime components may occur in various circumstances, such as end-users avoiding the installation, geo-blocking that restricts access to downloads, or IT policies within an organization prohibiting the download and installation of third-party applications.

In these circumstances, by using the contingency installation, your web application automatically falls back to WebHID to communicate with your Jabra devices.

Option 1 -- Download and install runtime components

You can communicate with Jabra devices via the following runtime components installed by end-users:

• Jabra Device Connector: a Jabra application that runs on the computer and communicates with Jabra devices

• Jabra Browser Extension: a browser extension enabling the Jabra JavaScript library to communicate with the abra Device Connector.

To do this, on the Jabra SDK for JavaScript page, in the Resources section, download the relevant runtime components.

After downloading and installing the runtime components, the following code sample shows how to enable your web application to communicate with and use Jabra devices:

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

async function app() {
  const config = {
    transport: RequestedBrowserTransport.CHROME_EXTENSION

  };

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

  // Proceed as before
}

app();

Option 2 -- Using WebHID

On the other hand, you can communicate through the WebHID API in Chromium-based browsers. Using WebHID allows you to develop call-control capable applications without installing runtime components on every computer that runs your web application.

However, WebHID comes with inherent technical limitations preventing the use of advanced features, such as telemetry data, configurable device settings, and programing headset buttons.

By using WebHID, the following code sample shows how to enable your web application to communicate with and use Jabra devices:

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

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

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

  // Proceed as before
}

app();

Due to security protocols, WebHID requires consent from end-users before your application can use Jabra devices.

The following code sample shows how to request consent from the end-user on a visible User Interface (UI) element:

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

Contingency installation -- WebHID fallback

In contingency installation, (effectively a combination of options 1 and 2) your web application has two options to use Jabra device functionality.

This installation approach can help end-users who do not or cannot have runtime components downloaded and installed on their computers to automatically fallback to using WebHID.

See the following code sample for contingency installation:

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

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

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

  // Proceed as before
}

app();

There are intricacies with option 1 (unsupported on ChromeOS) and option 2 (require user consent and additional limitations) to use Jabra devices. This means you must recognize the option used during initialization.

See the following code sample to determine the transport option used:

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

Similar to option 2, WebHID as a fallback also requires end-user consent (for example, presenting a confirmation button) prior to your web application accessing Jabra devices.

The following code sample shows how you can show/hide the consent button, in the case of your web application supporting both WebHID and the runtime components:

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

if (jabraCore.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();
  });
}