Button customization

The Button customization module allows you to customize buttons and LEDs on supported Jabra headsets. You can take control of buttons, listen for button interactions, and control LED colors and modes.

Live sample implementation

The demo implementation includes details on common properties for Jabra Engage 40 and 50 II headset devices.

Initialize

Before you can use the Button customization module in your application, you must initialize the core SDK and install the button customization npm package:

npm install @gnaudio/jabra-js-button-customization

To start working with button customization, create a device controller and get access to the button you want to customize:

import { ButtonInteraction, createDeviceController, ButtonId, Color, LedMode } from '@gnaudio/jabra-js-button-customization';

async function setupButtonCustomization(device) {
  const controller = await createDeviceController(device);
  if (!controller) {
    console.error("Failed to create device controller. The device may not support button customization.");
    return;
  }

  // Get the three-dot button
  const threeDotButton = await controller.getButton(ButtonId.threeDot);

  // Take control of the button (disables default functionality)
  threeDotButton.open();

  return { controller, threeDotButton };
}

Setting LED color and mode

Once you have control of a button, you can set its LED color and mode:

// Set LED to green with slow pulsing
threeDotButton.setColor(Color.green, LedMode.slowPulse);

// Set LED to solid red
threeDotButton.setColor(Color.red, LedMode.on);

// Turn LED off
threeDotButton.setColor(Color.red, LedMode.off);

Available predefined colors:

• Color.red
• Color.green
• Color.blue
• Color.yellow
• Color.cyan
• Color.magenta
• Color.white

Available LED modes:

• LedMode.off - LED is turned off
• LedMode.on - LED is on with steady light
• LedMode.slowPulse - LED is pulsing slowly
• LedMode.fastPulse - LED is pulsing quickly

Custom RGB colors

You can also create custom colors using RGB values (0-255):

// Create custom orange color
const orange = new Color(255, 165, 0);
threeDotButton.setColor(orange, LedMode.on);

Listening for button interactions

To respond to button presses, use the listenFor method:

// Listen for button taps
const taps = await threeDotButton.listenFor(ButtonInteraction.tap);
taps.subscribe({
  next: () => {
    // Called when a button tap event is received
  },
  error: (error) => {
    // Called if an error occurs when listening for button events
  },
  complete: () => {
    // Called when listening for button events is stopped
  }
});

Available button interactions:

• ButtonInteraction.press - Button held down longer than a tap
• ButtonInteraction.tap - Quick button press
• ButtonInteraction.doubleTap - Two quick taps in succession
• ButtonInteraction.down - Button is pressed down
• ButtonInteraction.up - Button is released

Releasing button control

If you're done with button customization, call close() to restore the button's default functionality:

// Release control and restore default functionality
threeDotButton.close();

Important

When a button is opened for control, any other functionality assigned to the button is disabled until control is released through close(). When closed, any custom LED configurations are reset and standard functionality is restored.

Supported devices

Button customization is currently supported on:

• Jabra Engage 40
• Jabra Engage 50
• Jabra Engage 50 II