Migration Guide: Upgrading to the New Brainfish Popup Widget

This guide will help you transition from the older version of the Brainfish widget to the newer implementation. The new version offers improved reliability and functionality while maintaining a similar user experience.

Key Changes

• Dynamic Button Creation: The new version creates the button programmatically rather than requiring it in the HTML.
• Toggle Functionality: The new implementation provides cleaner open/close toggling.
• Event Handling: Simplified event handling approach.

Step-by-Step Migration

1. Remove Static Button from HTML

The new implementation creates the button dynamically:

<!-- Remove this from your HTML -->
<button class="brainfish-trigger-button" onClick="Brainfish.HelpWidget.open('brainfish-trigger-button')">
  <i class="ph ph-question-mark"></i>
</button>

2. Update Widget Initialization

Replace your existing initialization code with the new pattern:

// Old implementation

Brainfish.Widgets.init({
  widgetKey: "your_old_widget_key"
});

// New implementation 
Brainfish.Widgets.init({ 
  widgetKey: "your_new_widget_key"
});

// Add this to dynamically create the button

setTimeout(() => {
  if (document.querySelector(".brainfish-trigger-button")) return;

  let isBrainfishWidgetOpen = false;
  
  const button = document.createElement("button");
  button.className = "brainfish-trigger-button";
  button.innerHTML = '<i class="ph ph-question-mark"></i>';
  button.onclick = function() {
    if (isBrainfishWidgetOpen) {
      Brainfish.HelpWidget.close();
    } else {
      Brainfish.HelpWidget.open();
    }
    isBrainfishWidgetOpen = !isBrainfishWidgetOpen;
  };
  
  document.body.appendChild(button);
}, 3000);

3. Remove Old Event Listeners

Replace the old event handling approach with the simplified toggle in the button click handler:

// Remove these event listeners

window.removeEventListener('onBrainfishHelpWidgetOpened', hideIcon);
window.removeEventListener('onBrainfishHelpWidgetClosed', showIcon);
window.removeEventListener('onBrainfishActionClick', (ev) => {
  console.log('Action clicked:', ev)
});

Custom Button Implementation

If you want to use a custom button instead of the default popup experience, you can manually add your own button and use JavaScript to trigger the Brainfish widget:

const customButton = document.getElementById("my-custom-button");
customButton.addEventListener("click", () => {
  Brainfish.HelpWidget.open();
});

Otherwise, the new experience will use a popup by default.

Troubleshooting

• Button Not Appearing: Ensure the timeout is sufficient (3000ms) for Brainfish to initialize.
• Multiple Buttons: The new code checks for existing buttons to prevent duplicates.
• Widget Not Opening: Verify your widget key is correct.
• Styling Issues: Check that your CSS classes match the dynamically created elements.

For additional support, please contact the Brainfish team.