algoliasearch.zendesk-hc

JavaScript library: algoliasearchZendeskHC

This JavaScript library allows you to replace the default search of your Zendesk Help Center by Algolia. Algolia is a hosted full-text, numerical, and faceted search engine capable of delivering realtime results from the first keystroke.

To browse through the crawler, visit the crawler/ folder.

Documentation

Note: You need to have an Algolia account. Please login or sign-up first. {: .alert.alert-info}

Synchronize Algolia with your Help Center

1. Visit the Algolia for Zendesk home page
2. Enter your zendesk subdomain (your_subdomain in your_subdomain.zendesk.com) and click Join the Beta
3. When Zendesk asks you to approve Algolia in your Zendesk instance, click Allow
4. Starting from that point, the content of your Help Center will be synchronized with Algolia's indices.

Updating your Help Center theme

Once your data has been extracted to Algolia, you need to update your Help Center theme in order to replace the search feature by Algolia.

1. Copy the code displayed on the Zendesk Connector page in your Algolia account
2. Head to your Zendesk Help Center
3. Click General > Customize the design in the top bar
4. In the Theme section, click on Edit theme
5. In the top left corner dropdown, select the Document Head template
6. Paste at the end of the template the code you've just copied
7. Click Save and ensure everything is working using the preview on the right (if you have some small CSS issues, read this part)
8. Click Publish Changes

Available options

Here is a full breakdown of the available options for the JavaScript library:

<link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/2/algoliasearch.zendesk-hc.min.css">
<script type="text/javascript" src="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/2/algoliasearch.zendesk-hc.min.js"></script>
<script type="text/javascript">
  algoliasearchZendeskHC({
    applicationId: '<YOUR APPLICATION_ID>',
    apiKey: '<YOUR SEARCH ONLY API KEY>',
    subdomain: '<YOUR ZENDESK APPLICATION NAME>',

    //
    // Optional configuration:
    //
    indexPrefix: 'zendesk_',    // or your custom <INDEX_PREFIX>
    baseUrl: '/hc/',            // the base URL of your Help Center
    poweredBy: true,            // show the "Search by Algolia" link (required if you're on Algolia's FREE plan)
    debug: false,               // debug mode prevents the autocomplete to close when trying to inspect it
    color: '#D4D4D4',           // main color (used for links)
    highlightColor: '#D4D4D4',  // highlight color to emphasize matching text
    responsive: true,           // responsive instantsearch page
    autocomplete: {
      enabled: true,            // is the autocomplete feature enabled?
      inputSelector: '#query',  // the DOM selector to select the search box
      hits: 5                   // the number of suggestions to display
    },
    instantsearch: {
      enabled: true,
      tagsLimit: 15             // Maximum number of tags to display
    },
    translations: {             // These accept strings or objects associating locale with value
                                // e.g. {
                                //   found_in: {
                                //     'en-us': 'Found in',
                                //     'fr': 'En'
                                //   }
                                // }
      article: 'Article',
      articles: 'Articles',
      categories: 'Categories',
      filter: 'Filter results',
      found_in: 'Found in',
      no_result: 'No result',
      placeholder_autocomplete: 'Search in sections and articles',
      placeholder_instantsearch: 'Search in articles',
      result: 'Result',
      results: 'Results',
      search_by: 'Search by',
      sections: 'Sections',
      tags: 'Tags'
    }
  });
</script>

Customizing the CSS

It is definitely possible that, when you install the application, it doesn't exactly display as you expect.
No worries, these are usually just a few conflicting rules between your design and our integration.

You might also just want to change the look & feel of the search.

Either way, just follow the following steps:

• Ensure you read the SCSS source file to see all the rules we're using
• Add a <style> tag after the <link> tag you've already added in your Document Head template and add your custom CSS here

Example:

<link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/CURRENT_VERSION/algoliasearch.zendesk-hc.min.css">
<style>
  .aa-dropdown-menu {
    background-color: #ccc;
  }
</style>
<script type="text/javascript" src="//cdn.jsdelivr.net/algoliasearch.zendesk-hc/CURRENT_VERSION/algoliasearch.zendesk-hc.min.js"></script>
<script type="text/javascript">
  algoliasearchZendeskHC(/* ... */);
</script>

Note: You might have some trouble trying to customize the autocomplete menu because it automatically closes when you try to Inspect it. Just set debug: true to avoid this behaviour.

Supporting multiple languages

Out of the box, the library limits the results to the currently selected language. However, some constant strings like the ones used in the sentence "12 results found in 1ms" need to be translated in your language. In order to do so, you need to use the translations parameter described in the documentation above.

If you're using only one language in your Help Center, just pass the strings of this specific language. For example, for French, you might want to pass:

translations: {
  article: 'Article',
  articles: 'Articles',
  categories: 'Catégories',
  found_in: 'Trouvés en',
  no_result: 'Aucun résultat',
  placeholder_autocomplete: 'Rechercher dans les articles et sections',
  placeholder_instantsearch: 'Rechercher dans les articles',
  result: 'Résultat',
  results: 'Résultats',
  search_by: 'Recherche par',
  sections: 'Sections',
  tags: 'Tags'
}

If you want to support multiple languages though, you'll need to pass for each key an object using locales as key. The locale is en-us in yoursupport.zendesk.com/hc/en-us. For example, for English and French, you might want to pass:

translations: {
  article: {
    'en-us': 'Article',
    'fr': 'Article'
  },
  articles: {
    'en-us': 'Articles',
    'fr': 'Articles'
  },
  categories: {
    'en-us': 'Categories',
    'fr': 'Catégories'
  },
  filter: {
    'en-us': 'Filter results',
    'fr': 'Filtrer les résultats'
  },
  found_in: {
    'en-us': 'Found in',
    'fr': 'Trouvés en'
  },
  no_result: {
    'en-us': 'No result',
    'fr': 'Aucun résultat'
  },
  placeholder_autocomplete: {
    'en-us': 'Search in articles and sections',
    'fr': 'Rechercher dans les articles et sections'
  },
  placeholder_instantsearch: {
    'en-us': 'Search in articles',
    'fr': 'Rechercher dans les articles'
  },
  result: {
    'en-us': 'Result',
    'fr': 'Résultat'
  },
  results: {
    'en-us': 'Results',
    'fr': 'Résultats'
  },
  search_by: {
    'en-us': 'Search by',
    'fr': 'Recherche par'
  },
  sections: {
    'en-us': 'Sections',
    'fr': 'Sections'
  },
  tags: {
    'en-us': 'Tags',
    'fr': 'Tags'
  }
}

Zendesk Community search

We do not index community forums for now. If you're using them, you'll probably want to disable instantsearch by setting enabled: false and just provide the auto-complete feature on your home page.

Development

The package.json holds multiple scripts:

• build:css: Compiles the CSS files to dist/algoliasearch.zendesk-hc.css
• build:docs: Extracts the documentation from this README.md to ../docs/documentation.md
• build:js: Compiles the JS files to dist/algoliasearch.zendesk-hc.js and dist-es5-module/*.js
• build: Launches all 3 previous builds
• clean: Removes dist/ and dist-es5-module
• dev: Launches build and server, and watches the files to rebuild them if needed
• lint: Lints the JS files
• server: Runs a simple HTTP server pointing to dist/
• test:coverage: Runs test with coverage enabled
• test: Runs the test suite

build:js, build:css, build and dev can be passed a NODE_ENV environment variable.
If set to production, it also creates minified files and map files.

server accepts a PORT environment variable to change on which port it will run.

Contributing

We're considering any contribution and PR, please go ahead!

License

This project is under the MIT License.

Changelog

2.3.0 (2016-04-26)

Bug Fixes

• autocomplete: add clearfix after suggestion (2eded23)

Features

• app: debug parameter (d42fdb6)
• autocomplete: restore adaptative snippeting (486cdfe)

<a name="2.2.0"></a>