Lighthouse Widget API

Jake Peters Updated 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 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 = {
..., // the rest of your widget config would replace the ... here, e.g. your widget_key
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. Ideally an SVG, but a 180px square PNG/JPG will work great.
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
position: 'bottom right|bottom left', // set to 'bottom left' to move Lighthouse to the left corner. Defaults to the right
article_link_target: '_blank|_top|auto', // ADVANCED: set the target of all links in articles. Default is '_blank' to open in new tab, can also be '_top' to open in same tab or 'auto' to respect what you choose in the article editor
article_html_clean_mode: 'aggressive|standard', // ADVANCED: by default Lighthouse aggressively cleans HTML to remove inline styles and many types of element. You can preserve inline styles, divs, spans and more by reducing the aggression. Recommended not to adjust this.
ignore_contact_widgets: true, // ADVANCED: don't automatically detect contact widgets on the page, use the email form (or nothing) instead
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();

You can trigger Lighthouse methods from a hyperlink in your app. e.g. to head to an article, you can have a link like <a href="#" onclick="Lighthouse.navigate('article', '12a45b78');">Click here</a>

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 = {
..., // the rest of your widget config would replace the ... here, e.g. your widget_key
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?

Understanding Lighthouse

Installing Lighthouse

Get in touch