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 theinit
function. The rest of the examples on this page omit this piece to focus solely on components, but components should ALWAYS be added in theonReady
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
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.