Universal vs. Vertical Search

Answers Initialization

Adding Answers JS to a page is a two step process.

Initialize the library
Add components.

Basic Initialization

The first step is to initalize the library. This is done using the ANSWERS.init command. This function accepts a set of configuration options.

At a minimum apiKey, experienceKey, businessId and experienceVersion must be specified. Here is an example.

ANSWERS.init({
  apiKey: "3517add824e992916861b76e456724d9",
  experienceKey: "answers-js-docs",
  businessId: "3215760",
  experienceVersion: "PRODUCTION",
  onReady: function() {
    // ADD COMPONENTS HERE
  },
});

The onReady property is used to add components. You can learn more about adding components in the Components section.

Additional Initialization Options

Learn more about additional initialization configuration below and in the Initialization Options section.

Answers Initialization API

Property	Type	Default	Description
apiKey	string		REQUIRED Your API key; this or `token` is required, but both cannot be specified.
token	string		A JWT used to access Answers; this or `apiKey` is required, but both cannot be specified. If specified, this will be passed in the `authorization` header of the API request.
experienceKey	string		REQUIRED Your answers experienceKey
onReady	function	function() {}	REQUIRED Invoked when the Answers component library is loaded/ready
businessId	string		Yext businessId, strongly encouraged. If not provided, analytics requests will not succeed.
useTemplates	boolean	true	If false, don’t fetch pre-made templates. Only use this if you plan to implement custom renders for every component!
templateBundle	object		If `useTemplates` is `false`, provide the precompiled templates here.
locale	string	en	The locale of the configuration. The locale is passed to the api request, and will affect how queries are interpreted and the results returned.
experienceVersion	string	PRODUCTION	The Answers Experience version to use for api requests. Can be a label or version number.
debug	boolean		Prints full Answers error details when set to `true`.
sessionTrackingEnabled	boolean	true	If true, the search session is tracked using session storage and session cookies. If false, there is no tracking. Can also be set using the `setSessionSessionOption(bool)` function.
analyticsEventsEnabled	boolean	true	If true, analytics events are sent when users engage with the experience. If false, no analytics events are set. Can also be set using the `setAnalyticsOptIn(bool)` function.
disableCssVariablesPonyfill	boolean		Opt-out of automatic css variable resolution on init for legacy browsers
onStateChange	function	function() {}	Invoked when the state of any component changes
onVerticalSearch	function	function() {}	Analytics callback after a vertical search, see onVerticalSearch Configuration for additional details
onUniversalSearch	function	function() {}	Analytics callback after a universal search, see onUniversalSearch Configuration for additional details
search	object		Search specific settings, see Search Configuration.
verticalPages	array		provide configuration for each vertical that is shared across components, see Vertical Pages Configuration.
navigation	object		DEPRECATED Provide navigation configuration including tab configurations. Use `verticalPages` instead.
querySource	string	STANDARD	The analytics key describing the Answers integration type. Accepts ‘STANDARD’, ‘OVERLAY’, or arbitrary strings. Can be updated using `ANSWERS.setQuerySource(string)`.
visitor	object		Configuration related to displaying a microphone icon for conducting a search with voice using the Web Speech API
id	string		The current visitor’s ID
idMethod	string		The current visitor’s ID method.
environment	enum	production	The Answers environment to use. Can be “production” or “sandbox”.

Components

This is the current version of answers components

Overview

Components are the core building block of an Answers Search Experience. Each component represents a standalone piece of functionality. Some of the most common components include:

SearchBar - Displays a NLP Powered Search Bar
Navigation - Displays tabs to navigate between search pages
UniversalResults - Displays results combining multiple verticals
VerticalResults - Displays results for a single vertical

Adding a Component

Components are added to the page one by one using the addComponent API. Here is a basic example adding a search bar.

ANSWERS.init({
  apiKey: "df4b24f4075800e5e9705090c54c6c13",
  experienceKey: "rosetest",
  businessId: "2287528",
  experienceVersion: "PRODUCTION",
  onReady: function() {
    ANSWERS.addComponent("SearchBar", {
      container: ".search-container",
    });
  },
});

You will notice that components are added in the onReady property of the init function. The rest of the examples on this page omit this piece to focus solely on components, but components should ALWAYS be added in the onReady function.

Component Container

The container property is required for every component you wish to add to the page. This property is a JavaScript selector that must match an HTML element. You should choose a unique class name (you cannot add a component to multiple places on the page). In the example above, this HTML should be somewhere on the page:

<div class="search-container"></div>

Full Example

Putting this together a full HTML page could look like this:

<body>
  <div class="search-container"></div>
  <script>
    ANSWERS.init({
      apiKey: "3517add824e992916861b76e456724d9",
      experienceKey: "answers-js-docs",
      businessId: "3215760",
      experienceVersion: "PRODUCTION",
      onReady: function() {
        ANSWERS.addComponent("SearchBar", {
          container: ".search-container",
        });
      },
    });
  </script>
</body>

Overriding a Template

To completely override the UI of a component, you can pass in a custom Handlebars template to the template option. See custom templates for more information.

Custom Rendering

If you want to use a different templating language, you can use the render option. This option accepts a function that returns HTML. See custom rendering for more information.

Custom Components

If you want to create completely custom components, see custom components for more information.

Components API

Property	Type	Description
container	string	REQUIRED the CSS selector to append the component
name	string	a unique name, if using multiple components of the same type
class	string	a custom class to apply to the component
template	string	override internal Handlebars template
render	function	override render function. data provided
transformData	function	A hook for transforming data before it gets sent to render
onMount	function	invoked when the HTML is mounted to the DOM
analyticsOptions	object	additional properties to send with every analytics event

Universal vs. Vertical Search

Before diving into building an experience, it’s important to understand the difference between Vertical and Universal Search.

Universal Search

Universal Search is a search page that combines results from multiple different backends (vertical) together. For example, a Universal Search page might combine locations, events, people and FAQ into one search experince.

A Universal Search page should use the UniversalResults components for displaying results. Generally, universal search is labeled with the All tab in the navigation.

Vertical Search

Vertical Search is a search page that only shows results from a single backend (vertical). For example, a Vertical Search page might show a list of locations, or a list of events.

A Vertical Search page should use the VerticalResults components for displaying results. Additionally, the SearchBar component must have the verticalKey property set.