Lighthouse Widget API

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 available on the free trial, then in the Pro plan and above.

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
launcher_button_image: 'https://cdn.helpdocs.io/img/logo_white.svg', // an absolute URL to an image to use as the background of the launcher button. If you don't pass this we'll use the default Lighthouse icon
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_name_placeholder: 'Jane Doe',
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 Name

Purpose

Example(s)

hide()

Collapse the main Lighthouse panel

Lighthouse.hide();

show()

Show the main Lighthouse panel

Lighthouse.show();

hideButton()

Hide the actual Lighthouse button completely

Lighthouse.showButton();

showButton()

Show the Lighthouse button again

Lighthouse.hideButton();

navigate(page, id?)

Open the main Lighthouse panel if you need, and navigate to a specific page

Lighthouse.navigate('suggestions');
Lighthouse.navigate('home');
Lighthouse.navigate('category', 'ab3c56d8');
Lighthouse.navigate('article', '12a45b78');
Lighthouse.navigate('contact');

reload()

Reload the config values and refresh Lighthouse

Lighthouse.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 = {
* name: '', // the name that was submitted
* 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?