This software project from Jabra helps developers to make solutions, where basic headset call control can be used from within a browser app using JavaScript. Since it is not possible to access USB devices directly from JavaScript, this library provides a solution of getting a route from the JavaScript to the Jabra USB device. The API is a JavaScript library with a facade that hides implementation details. Basic call control is defined by off-hook/on-hook, ringer, mute/unmute and hold/resume. With these features, it is possible to implement a browser based softphone app. Combined with the WebRTC technology it is possible to create a softphone that only requires small software components installed locally on the computer, while the business logic is implemented in JavaScript.
- be able to control a headset from JS
- be a lightweight solution
- support the platforms: Windows and macOS
With current internal implementation of this software package, the following is supported:
All professional Jabra headsets and Jabra speakerphones are supported. I.e. the Jabra Evolve series, the Jabra Pro series, the Jabra Biz series, and the Jabra Speak series.
The following desktop operating systems are supported:
| Operating system | Version |
|---|---|
| Windows 64 bit | Windows 7 or newer |
| Windows 32 bit | Windows 7 or newer |
| macOS | El Capitan or newer |
Google Chrome web browser - stable channel - 32 bit and 64 bit.
The solution consists of a Javascript API that webpages can consume, a chrome web extension and a native chromehost that must be installed separately.
Developers must use the versioned JavaScript library file with the format jabra.browser.integration.<majorVersion>.<minorVersion>.js and the associated
typescript *.d.ts definition file which
documents the API in detail, including exactly what each API method expect for parameters and what each method returns.
These files adhere to semantic versioning so increases in majorVersion between releases indicate breaking changes so developers using the software may need to change their code when updating. Increases in minorVersion indicates that all changes are backwards compatible.
Tip: Use the supplied typescript file with a reference path comment on top of your javascript files to get code completion for the Jabra API in many development tools.
Latest API versions are:
| API file downloads | Description |
|---|---|
| jabra.browser.integration-2.0.js | Javascript API client file |
| jabra.browser.integration-2.0.d.ts | Typescript definition file |
The library internally checks for dependencies – and will report this to the app using the library. An example: When trying to initialize Jabra library the promise might fail with an error “You need to use this Extension and then reload this page” if the browser extension is missing.
Notice that the latest API contains breaking changes compared with previous 1.2 version as evident from the change in major version. See upgrade section below for help on upgrading your client code.
| Operating systems | Chrome host native download | Description |
|---|---|---|
| Windows (Windows 7 or newer) | JabraChromeHost2.0.0.msi | Chromehost 2.0 |
| Windows (Windows 7 or newer) | JabraChromeHost2.0.2.msi | Chromehost 2.0 (3CX only) |
| Windows (Windows 7 or newer) | JabraChromeHost0.51.msi | Security fix to allow beta testing |
| macOS (El Capitan or newer) | JabraChromeHost2.0.0.dmg | Chromehost 2.0 |
| macOS (El Capitan or newer) | JabraChromeHost2.0.2.dmg | Chromehost 2.0 (3CX only) |
| macOS (El Capitan or newer) | JabraChromeHost0.5.dmg | Old Mac release |
First, make sure the jabra library javascript file is included in your HTML page (use a local copy - don't link directly).
Secondly, the library must be initialized using javascript like this:
jabra.init().then(() => {
// Handle success
}).catch((err) => {
// Handle error
});Generally, you will also need to setup various event handlers, like for example for when a new Jabra device has been attached to the computer or when the device has requested to be muted (just be aware that some events are only send if the device is in a specific state. For example, mute is only send when the device is off hook):
jabra.addEventListener("device attached", (event) => {
// Handle new device
});
jabra.addEventListener("mute", (event) => {
// Handle mute event.
});When issuing commands, this API only works with one (active/selected) jabra device at the time (only an issue if you have multiple Jabra devices connected at the same time). You can easily issue specific commands to the active device like this example:
jabra.offHook();Importantly, please do consult the typescript definition file for a full description of how to use the API. See also the source code for the examples listed below for usage details.
For many editors and IDE's, the above typescript definition file can be used to provide code completion and context sensitive help. For example for Visual Code, this requires top-level comment like this to your javascript source file:
/// <reference path="<your-path-to-a-local-copy-here>/jabra.browser.integration-2.0.d.ts" />- Call control test - test page to try out basic call control in the library
- Library api test - advanced test page that allows detailed testing of individual API calls)
- Playback demo with auto selection - demo page showing auto selection of jabra device with simple audio playback example
- Amazon Connect client demo - demo showing Jabra and Amazon Connect integration
These sequence diagrams shows typical use of the browser sdk:
Documentation about mass deployment
The extension, chromehost and api has logging support that can be used to diagnose errors.
Logging for javascript components can be seen in the browser developer console for the application and for the background page of the extension (a link is provided under chrome extensions when developer mode is selected). The log level (how much is being logged) can be controlled by right-clicking on the extension and selecting options followed by a restart of the browser.
Logging for all native components (chromehost and platform sdk library) are written to text files. Destination is specified by environment variable LIBJABRA_RESOURCE_PATH or by default to %APPDATA%\JabraSDK on Windows and ~/Library/Application Support/JabraSDK on Mac OS. Log level is specified by the environment variable LIBJABRA_TRACE_LEVEL with possible values "fatal", "error", "warning", "info", "debug".
As noted in the changelog all methods now return values using Javascript promises rather than callbacks. Also, events are now subscribed to using a addEventListener(nameSpec, callback) and removeEventListener(nameSpec, callback) similar to standard libraries. With this new way of subscribing to events, the old requestEnum is removed as it is no longer necessary to switch on events.
The above changes were made to better handle a future expansion of events efficiently and to streamline testing and API usage in a modern way. For example, the changes made it easy to create our new API test tool. With the addition of typescript, the new API is also much easier to use ... and type safe.
The example below shows how to convert old 1.2 code like this:
jabra.init(
function () {
// Handle success
},
function(msg) {
// Handle error
},
function (req) {
if (req == jabra.requestEnum.mute) {
// Handle mute event
} else if (req == jabra.requestEnum.unmute) {
// Handle unmute event.
}
}
);
to new 2.0 compliant code:
jabra.init().then(() => {
// Handle success
}).catch((err) => {
// Handle error
});
jabra.addEventListener("mute", (event) => {
// Handle mute event.
});
jabra.addEventListener("unmute", (event) => {
// Handle unmute event.
});
For information about individual releases see changelog. For information about upcoming changes see also our beta information page.