Lighthouse Widget API

Lighthouse ships with everything you need by default. But if you're looking to customize it I come bearing good news! You can use the Lighthouse Widget API to change how it looks and behaves.

Changing the Lighthouse Config

When you initialize Lighthouse you'll have used a snippet of Javascript code from your HelpDocs dashboard in Settings > Lighthouse. 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>

Notice the window.hdlh object? That holds a lotta power since you can include values to change how Lighthouse looks and acts. Let's dive in and explore the different options.

window.hdlh = {
  ..., // the rest of your widget config would replace the ... here, e.g. your widget_key
  language_code: 'fr', // Type: String. One of the language codes from your HelpDocs account.
  text_direction: 'ltr|rtl', Type: String. Set to 'rtl' to change text direction to right to left. Default is left to right.
  logo: 'https://cdn.helpdocs.io/img/logo_white.svg', // Type: String or Bool. 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', // Type: String. Include a hex code you'd like Lighthouse to base all other colors from.
  color_mode: 'light|dark|auto', // Type: String. Force the complementary color scheme (like the headers) to become light or dark. Default is auto so we'll try to guess if your primary color needs light or dark complementary colors.
  brand: 'Support', // Type: String. Change the string that shows up in the top bar of Lighthouse.
  launcher_button_image: 'https://cdn.helpdocs.io/img/logo_white.svg',  // Type: string. 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', // Type: String. How wide you'd like the main frame to appear.
  position: 'bottom right|bottom left', // Type: String. Set to 'bottom left' to move Lighthouse to the left corner. Defaults to the right.
  article_link_target: '_blank|_top|auto', // Type: String. 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', // Type: String. 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: Bool: string. Don't automatically detect contact widgets on the page and use the email form (or nothing) instead.
  suggestions: [String], // Type: Array of Strings. An array of suggestions to show the user. e.g. ['tag:test','article:12a45b78', 'category:ab3c5d7e', "tag:url:"+window.location.pathname]
  disable_contact_button: true, // Type: Bool. disable the contact button completely, regardless of live chat integrations
  disable_authorship: true, // disable authorship (faces/names) on articles and suggestions
  shared_password: 'fluffyeggbaskets', // Type: String. Include your shared password so the user can open articles in a tab.
  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'
  },
  user: { // Prefill contact form submission values
    name: 'Jane Doe',
    email: 'j.doe@helpdocs.io'
  }
};

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.

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.