Lighthouse Widget API

Updated 1 month ago by Jake Peters

You can customize the behaviour and appearance of Lighthouse through the widget API.

When you initialize Lighthouse you'll have used a snippet of Javascript code from your HelpDocs dashboard. Something like this:

<script type="text/javascript">
            window.hdlh = {
              widget_key: "your-super-secret-widget-key"
            };
            (function(h,d){var s=d.createElement("script");s.type='text/javascript';s.async=true;s.src=h+"?t="+new Date().getTime();d.head.appendChild(s);})("https://lighthouse.helpdocs.io/load",document);
          </script>

You can add more parameters to that window.hdlh config object to do things like change your primary color, navigate to a new article, or hide the widget completely.

Lighthouse is currently in private beta, and will become a Pro plan feature. If you wanna try it out before the official launch, contact support.

Config

There's a number of config values you can change. These impact the behaviour and appearance of Lighthouse inside your app.

window.hdlh = {
            ...,
            language_code: 'fr', // one of the language codes from your HelpDocs account
            logo: 'https://cdn.helpdocs.io/img/logo_white.svg', // an absolute URL to an image to use as the logo, or pass false to disable the logo completely
            primary_color: '#ff63aa', // the hex code of primary color you'd like Lighthouse to base all other colors from
            color_mode: 'light|dark|auto', // force the complementary color scheme (like the headers) to light or dark. Default is auto, so we'll try to guess if your primary color needs light or dark complementary colors.
            brand: 'Support', // shows up in the top bar of Lighthouse
            frame_width: '400px', // how wide you'd like the main frame to appear
            suggestions: [String], // an array of suggestions to show the user. e.g. ['tag:test','article:12a45b78', 'category:ab3c5d7e']
            disable_contact_button: true, // disable the contact button completely, regardless of live chat integrations
            disable_authorship: true, // disable authorship (faces/names) on articles and suggestions
            i18n: { // change the value of the strings we use inside Lighthouse, for internationalization
              contact_button: 'Contact',
              contact_email_placeholder: 'j.doe@example.com',
              contact_message_placeholder: 'I need help with...',
              contact_submit: 'Send',
              search_placeholder: 'Find articles...',
              view_all: 'View All',
              suggested_articles: 'Suggested Articles'
            }
          };
          

Methods

Methods are ways to trigger a change in Lighthouse's state. For instance, to navigate to a piece of content, or to open the widget. These can be called from anywhere in your app, but be sure to check that Lighthouse is loaded successfully first.

All methods are available on the window.Lighthouse variable. So you'd call e.g. window.Lighthouse.hideButton() to hide the button completely from the user.

Method NamePurposeExample(s)
hide()Collapse the main Lighthouse panelLighthouse.hide();
show()Show the main Lighthouse panelLighthouse.show();
hideButton()Hide the actual Lighthouse button completelyLighthouse.showButton();
showButton()Show the Lighthouse button againLighthouse.hideButton();
navigate(page, id?)Open the main Lighthouse panel if you need, and navigate to a specific pageLighthouse.navigate('suggestions');
Lighthouse.navigate('home');
Lighthouse.navigate('category', 'ab3c56d8');
Lighthouse.navigate('article', '12a45b78');
Lighthouse.navigate('contact');
reload()Reload the config values and refresh LighthouseLighthouse.reload();

Callbacks

Callbacks tell your code when something's happened in Lighthouse, be it from a user action or from a method being triggered. The most common callback would be onReady(), to check when Lighthouse is ready to roll.

window.hdlh = {
            ...,
            onLoad: function () {}, // fires when Lighthouse has loaded all data from the server
            onReady: function () {}, // fires when the Lighthouse API is ready for use
            onShow: function () {}, // fires when the main Lighthouse panel is shown
            onHide: function () {}, // fires when the main Lighthouse panel is hidden
            onButtonShow: function () {}, // fires when the Lighthouse button is shown
            onButtonHide: function () {}, // fires when the Lighthouse button is hidden
            onNavigate: function (data) {
              /*  fires when Lighthouse navigates to a new page
               *
               *  data = {
               *    page: 'suggestions|home|contact|article|category',
               *    category_id: '', // category_id of the category or article that's being navigated to
               *    article_id: '' // article_id of the article that's being navigated to
               *  }
               */
            },
            onSearch: function (data) {
              /*  fires when someone performs a search in Lighthouse
               *  Note: Lighthouse uses realtime search, so this could be fired
               *  up to once every 500ms
               *
               *  data = {
               *    query: '', // the query these results are for
               *    results: [{title: '', href: '', ...}, ...] // array of articles that were found for this query
               *  }
               */
            },
            onContactFormSubmit: function (data) {
              /*  fires when someone submits a contact form
               *
               *  data = {
               *    email: '', // the email that was submitted
               *    message: '' // the message that was submitted
               *  }
               */
            },
          };

Reloading Lighthouse

When you make changes to config on the fly, for example in a single page app, you'll need to reload Lighthouse for those changes to take effect. Reloads are instant and maintain internal state, so it's safe to do these often. Use the reload() method to apply your new config after making the change to window.hdlh.


What did you think of this doc?