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
• Reading and changing settings and other properties (properties module)
• Subscribing to telemetry events such as audio telemetry (properties module)
• Customizing buttons and LEDs on supported headsets (button customization module)

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:

npm install @gnaudio/jabra-js

Getting Started

The easiest way to get started is to try the live code samples

Try Live 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.

Browser

import {createApi, RequestedBrowserTransport} from '@gnaudio/jabra-js';

// For browser apps, you should always use CHROME_EXTENSION_WITH_WEB_HID_FALLBACK for transport.
/** @type {import('@gnaudio/jabra-js').IConfig} */
const sdkConfig = {
  partnerKey: 'your-partner-key', // For production use, please request and use a 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);
    }
  }
};

const jabraSdk = await createApi(sdkConfig);
// (...) setup device added/removed event subscriptions (see below)
// Finalize initialization using start() to start subscribing to device added events.
await jabraSdk.start();

Node.js

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

// For Node.js apps, you don't need to specify transport.
/** @type {import('@gnaudio/jabra-js').IConfig} */
const sdkConfig = {
  partnerKey: 'your-partner-key', // For production use, please request and use a 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);
    }
  }
};

const jabraSdk = await createApi(sdkConfig);
// (...) setup device added/removed event subscriptions (see below)
// Finalize initialization using start() to start subscribing to device added events.
await jabraSdk.start();

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

Use createApi() instead of init()

In SDK version 4.4.1 and later, we recommend using createApi() and .start() instead of init() to initialize the SDK. This is to ensure your app gets fully setup and subscribes to device events before the SDK starts emitting them.

Device added/removed

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

// 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 set up 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 used by most of your customers will be "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:

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

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

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

By browser security requirements, the WebHID consent dialog must be triggered from a user gesture such as a button click. Alternatively a browser policy can be set by IT administrators. Read more at Transport mode for web apps.

Device connections

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 for more.

When an end-user connects a headset to their computer, this may lead to multiple connections.

Example: For a Bluetooth 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.

// 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}`);
  });
});

From here you should be setup to integrate with basic information about connected Jabra devices. Or expand to use some of the other SDK functionality found in the left menu.