loading

Answers Initialization

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

  1. Initialize the library
  2. 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 Default 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 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 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.