Jabra for Developers

Appearance

Jabra JavaScript SDK ​

With the Jabra JavaScript SDK, you can easily integrate Jabra device functionality into your JavaScript applications. The SDK supports the following use cases:

  • Call control integration for softphones
  • Getting device information

Supported runtimes ​

  • Desktop versions of Google Chrome, Microsoft Edge and other Chromium based browsers.
  • Node.js on Windows, macOS and common Linux distributions.

Installing JavaScript SDK ​

Please install the @gnaudio/jabra-js package via NPM (get NPM by installing Node.js). You can do this by running the following command in your project directory:

sh
npm install @gnaudio/jabra-js

Once installed, you can import and use the SDK in your JavaScript code.

js
import { 
  init,
  webHidPairing,
  RequestedBrowserTransport,
  TransportContext,
  LogLevel,
  EasyCallControlFactory, 
} from './node_modules/@gnaudio/jabra-js/browser-esm/index.js';
js
import { 
  init,
  LogLevel,
  EasyCallControlFactory, 
} from '@gnaudio/jabra-js/node-esm/index.js';

Set type to "module"

html
<script src="index.js" type="module"></script>
json
{
  (...),
  "type": "module"
}

Import methods

While we recommend using the ECMAScript import-syntax for loading the jabra-js library for browser and Node.js apps, the library also supports:

  • CommonJS for Node.js apps.
  • UMD for browser apps.

Getting Started ​

The easiest way to get started is to try out one of our code samples.

Initializing the SDK ​

Before using the SDK you need to initialize it. For browser based apps, you should always use the "Chrome extension with WebHID fallback transport". For Node.js you can ignore the transport option.

js
// For browser apps, you should always use CHROME_EXTENSION_WITH_WEB_HID_FALLBACK for transport. 
  /** @type {import('@gnaudio/jabra-js').IConfig} */
  const config = {
    partnerKey: 'your-partner-key', // We recommend initializing with a proper Partner Key.
    transport: RequestedBrowserTransport.CHROME_EXTENSION_WITH_WEB_HID_FALLBACK,
    appId: 'my-app-id', // may contain a combination of letters (A-Z, a-z), numbers (123), underscores (_), and hyphens (-)
    appName: 'My app name', // end-user friendly name for your application
    logger: {
      write(logEvent) {
        console.log("Jabra SDK log event: " + logEvent.message, logEvent.layer);
      }
    }
  };

  // Initialize Jabra library using the config object
  const jabraSdk = await init(config);
  // (...) setup device added/removed events (see below)
js
// For Node.js apps, you don't need to specify transport. 
  /** @type {import('@gnaudio/jabra-js').IConfig} */
  const config = {
    partnerKey: 'your-partner-key', // We recommend initializing with a proper Partner Key.
    appId: 'my-app-id', // may contain a combination of letters (A-Z, a-z), numbers (123), underscores (_), and hyphens (-)
    appName: 'My app name', // end-user friendly name for your application
    logger: {
      write(logEvent) {
        console.log("Jabra SDK log event: " + logEvent.message, logEvent.layer);
      }
    }
  };

  // Initialize Jabra library using the config object
  const jabraSdk = await init(config);
  // (...) setup device added/removed events (see below)

Get your Partner Key by contacting us through the support form.

Device added/removed ​

You can choose to subscribe to deviceAdded/deviceRemoved events or to subscribe to changes to the entire Jabra deviceList.

js
// Subscribe to Jabra devices being attached/detected by the SDK
jabraSdk.deviceAdded.subscribe(async (/**@type {import('@gnaudio/jabra-js').IDevice} */ device) => {
  console.log(`Device attached/detected: ${device.name} (Product ID: ${device.productId}, Serial #: ${device.serialNumber})`);
  // (...) Your code working with the device here. 
  // Example: Set up Easy Call Control for the device, if you're building a softphone integration. 
});

// Subscribe to Jabra devices being detached
jabraSdk.deviceRemoved.subscribe(async (/**@type {import('@gnaudio/jabra-js').IDevice} */ device) => {
  console.log(`Device detached/removed: ${device.name} (Product ID: ${device.productId}, Serial #: ${device.serialNumber})`);
  // (...) Your code handling that the device was removed. 
  // Example: If you were using the device for call control, you might want to setup another device for call control. 
});

// Subscribe to changes in the entire list of Jabra devices
jabraSdk.deviceList.subscribe((/**@type {import('@gnaudio/jabra-js').IDevice[]} */ devices) => { 
  console.log('Device list changed. New device list:');
  devices.forEach(async (/**@type {import('@gnaudio/jabra-js').IDevice} */ device) => {
    console.log(`--Device: ${device.name} (Product ID: ${device.productId}, Serial #: ${device.serialNumber})`);
    // (...) Your code depending on whether this was the device you were looking for. 
    // Example: If device matches the audio device selected in a softphone, set up Easy Call Control for device. 
  });
});

Important note on WebHID transport

If your application is running in the browser, the transport mode most of your customers will use is "WebHID". In this case you will need to ensure you trigger the WebHID consent dialog. Example:
To trigger the WebHID consent dialog add for example a button to your HTML:

html
<button id="webHidButton">Add Jabra headset</button>

Then add an event listener from where you trigger the WebHID consent dialog:

js
const webHidButton = document.getElementById('webHidButton');
webHidButton.addEventListener('click', async () => {
  console.log('Adding Jabra device using WebHID');
  await webHidPairing();
  // If user added a device, the deviceAdded and deviceList subscriptions 
  // will trigger and you should handle the device interaction there.

Device connections ​

When an end-user connects a headset to their computer, some cases can lead to multiple connections.
Note: This only applies to Node.js apps and to web apps where the transport mode is to use Chrome Extension - please see Transport mode for web apps.

Example: For a BT headset you can simultaneously connect the headset using a wireless dongle connection for calls, in addition to a wired USB cable connection. A new wired connection does not report the headset as an additional device, but merely as an additional connection for the same device.

For a device, you can subscribe to ConnectionAdded/ConnectionRemoved events or subscribe to changes to the entire ConnectionList. You can also get a list of CurrentConnections.

js
// Connection added event
device.connectionAdded.subscribe(async (/**@type {import('@gnaudio/jabra-js').IConnection} */ connection) => {
  console.log(`Device connection added: ${connection.id}`);
});

// Connection removed event
device.connectionRemoved.subscribe(async (/**@type {import('@gnaudio/jabra-js').IConnection} */ connection) => {  
  console.log(`Device connection removed: ${connection.id}`);
});

// Connection list changed event
device.connectionList.subscribe(async (/**@type {import('@gnaudio/jabra-js').IConnection[]} */ connections) => {
  console.log(`Device connection list for ${device.name}:`);
  connections.forEach(/**@type {import('@gnaudio/jabra-js').IConnection} */ connection => {
    console.log(`Connection: ${connection.id}`);
  });
});

Easy Call Control ​

The recommended way for integrating call control with Jabra headsets into a softphone is to use our Easy Call Control (multi-call option) which is part of the JavaScript SDK.

Legacy CallControl and Easy Call Control (single-call option)

If you have an existing softphone integration using the legacy CallControl or Easy Call Control (single-call option), you can keep using that and it is fully supported. However, for all new integrations, we strongly recommend basing only on Easy Call Control (multi-call option).

Easy Call Control offers a high-level abstraction for call control integrations and is intended to be quick and easy to integrate with no need to understand the complexities of signals to and from headsets.

Once Easy Call Control is setup for a device, you can change the call state using high-level methods. Likewise, you can subscribe to events from Easy Call Control letting you know what state the device has requested.

Call control sample code

See code samples for a complete demo implementation of Easy Call Control.

Setup Easy Call Control ​

To set up Easy Call Control for a device, you should first check that the device supports call control and then create an instance of Easy Call Control.

js
// Create an Easy Call Control Factory from your 
// instance of the IApi you got when initializing SDK. 
var easyCallControlFactory = new EasyCallControlFactory(jabraSdk);
// If the device supports Easy Call Control, enable it.
if (easyCallControlFactory.supportsEasyCallControl(device)) {
  /**@type {import('@gnaudio/jabra-js').IMultiCallControl} */  
  var easyCallControl = await easyCallControlFactory.createMultiCallControl(device);
};

Subscribe to events ​

By listening to these events your application can keep track of the call state of the device and update your application's state accordingly.

js
// OngoingCalls is the number of ongoing calls on the device. This includes active and held calls. 

easyCallControl.ongoingCalls.subscribe((ongoingCalls) =>
{
    // (...)
});

// MuteState is the microphone mute state of the device. 
easyCallControl.muteState.subscribe((muteState) =>
{
    // (...)
});

// HoldState indicates if call is on hold or not. 
easyCallControl.holdState.subscribe((holdState) =>
{
    // (...)
});

// SwapRequest is called when the user wants to swap between two calls. 
easyCallControl.swapRequest.subscribe(() =>
{
    // (...) 
});

Change call state ​

By using these methods you can update Easy Call Control with state changes from your application.

js
// New incoming call
// The async call to signalIncomingCall() will not resolve 
// until the call is either accepted or rejected.
console.log("signalIncomingCall()");
var callAcceptedResult = await easyCallControl.signalIncomingCall();
if (callAcceptedResult) {
  console.log("signalIncomingCall() - Call accepted");
} else {
  console.log("signalIncomingCall() - Call rejected");
};
js
// Accept incoming call. 
// Note there is an optional parameter in case of multiple calls to specify whether to 
// accept and hang up current call, or accept and put current call on hold.
await easyCallControl.acceptIncomingCall();
js
// Reject incoming call. 
await easyCallControl.rejectIncomingCall();
js
// New outgoing call
await easyCallControl.startCall();
js
// End active call
await easyCallControl.endCall();
js
// Put active call on hold
await easyCallControl.hold();
js
// Resume call from held state
await easyCallControl.resume();
js
// Mute headset microphone
await easyCallControl.mute();
js
/// Unmute headset microphone
await easyCallControl.unmute();

Transport mode for web apps ​

Note: This section is not relevant for Node.js applications.

For web applications, running directly in Chrome, Edge or another Chromium based web browser, you need to consider the transport mode used to communicate with Jabra devices.

Important: As mentioned previously on initialization, we strongly recommend that you choose "Chrome extension with WebHID fallback transport" when initializing the SDK. This way, the SDK automatically selects the optimal transport based on whether End-user components are installed on the end user's PC or not.

The SDK can use either "WebHID" or "Chrome Extension" transport mode for web apps. To check which transport mode is currently used:

js
switch (jabraSdk.transportContext){
  case TransportContext.WEB_HID: console.log('Using WebHID transport'); break;
  case TransportContext.CHROME_EXTENSION: console.log('Using Chrome Extension transport'); break;
  default: break;

WebHID transport mode ​

This means that the Jabra SDK uses the browser's native WebHID API to communicate to/from the Jabra device. WebHID requires no installed software and therefore works across any desktop version of Chrome/Edge or other Chromium based browsers, including on ChromeOS. WebHID requires end user consent to access a headset device controls, similar to how access to microphone or camera requires consent. The WebHID consent dialog can only be triggered by an end user interaction, such as clicking a button. Consent is persisted in the browser, so end users only need to consent once per Jabra device in your web app. See Device added/removed for example on how to trigger WebHID consent dialog.

WebHID policies ​

If one of your customers prefer to avoid the WebHID consent dialog for their end users, they can use Chrome/Edge administrator policies to allow access to Jabra headsets from your URL. Please see:
Chrome WebHID policy
Edge WebHID policy
Example policy for Chrome on Windows, allowing all Jabra devices (vendor ID 2830) - replace www.example.org with your URL and save as a .reg file - then open .reg file to test policy:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Policies\Google\Chrome]
"WebHidAllowDevicesForUrls"="[ {  \"devices\": [   {    \"vendor_id\": 2830   }  ],  \"urls\": [   \"https://sdk.jabra.com\",  ] }]"

WebHID limitations ​

While the SDK generally ensures that multiple softphones can have Jabra call control integrations co-exist without conflicts, part of this protection against softphone conflicts cannot work only with WebHID.
Additionally, the features around device connections do not work with WebHID currently. *If a customer of your softphone run into conflicts with other softphones accessing the headset, please instruct your customer to install the End-user components.

Chrome Extension transport mode ​

If a customer has installed both End-user components, then your web app will automatically use the Chrome Extension transport mode. In this transport mode the SDK sends messages to/from the browser extension. The extension then uses native messaging to communicate with the Jabra Device Connector application. The Jabra Device Connector application has full access to all Jabra device features, ensuring against conflicts between multiple softphones using the Jabra headset at the same time.

Samples and documentation ​

Code samples ​

Easy Call Control
Please see the comprehensive demo project for Easy Call Control. The recommended transport to use for the demo is "Chrome Extension with WebHID fallback".

Please ignore other demos in the demo project

The downloadable for the Easy Call Control demo also contains other demo code. We recommend only basing off the Easy Call Control (multi-call option) sample code as that is the recommended way to integrate call controls for Jabra headsets.

API references ​

Coming soon. Meanwhile, please refer to code samples and code snippets above along with inline reference in your code editor based on the jabra-js NPM package.

End-user components ​

In certain scenarios the SDK requires installation of two Jabra software components on the end-users laptop. These components are available here:

Scenarios requiring end-user components:

  • End-users run multiple softphones simultaneously and experiences conflicts where calls to/from one softphone affects the state of the other.
FileDescriptionDownload
Browser Extension for Device ConnectorWorks across operating systems. Supports Microsoft Edge and Google Chrome.Chrome Web Store
Device Connector ApplicationInstalled application required by the Browser ExtensionWindows
macOS
Linux