Build a Search Experience End-to-End – Yext Help

This is a checklist and best-practices reference for building a Yext Search experience from start to finish. It covers the three main components of a Search build: the Yext Knowledge Graph (your content), the Search Backend (your configuration), and the Search Frontend (your user experience).

Step 1: Strategy & Scope

The first step is to define what content you want to include in your search experience - both in the backend (what users should be able to search on) and the frontend (what you want to display on results cards).

You may have to adjust your content strategy based on how easy it is to both collect and maintain your data.

Keep in mind:

Data Quality is Key: The quality of your data directly impacts the overall quality of your build.
Structure Matters: How you structure your data will determine how you set up both the frontend and the backend.

Verticals

Verticals are groups of similar content types (e.g., locations, products, FAQs). If you want to display certain types of content differently or separately, or have them be searched differently, you'll separate them into different verticals.

Verticals may differ depending on the industry you're in as well. Financial institutions may have agents, ATMs, and locations. Healthcare organizations may have doctors and healthcare facilities.

Verticalized search can benefit the overall user experience, however, single vertical experiences can also be created for use cases only requiring a single content type, such as a store locator, doctor finder, or product search.

Determine Your Data Scope

Decide on the verticals you want in the search experience.

Best Practice: We recommend having no more than seven verticals to maintain good search quality and avoid overwhelming users.

Consider these factors for content:

What are users currently searching for and engaging with on your site?
What does success look like? (e.g., increased self-service, higher click-through rate)?
What content do you want to highlight?
- Where on your site would you like to drive more traffic and user engagement?
- What about those content types do you want to be searchable or displayed on the results card?
What are your timeline and dependencies?
- If your data collection timeline doesn't align with your launch, consider starting with sample data or a subset of verticals and adding more later. Be aware that this might create a suboptimal user experience if they expect comprehensive results but only a partial set is shown.

For each vertical, keep track of:

Frontend Search Results: The attributes you want to display on results cards
Backend Searchable Fields: The attributes you want users to be able to search on
Data Ingestion: The source of the data and how it will be kept up-to-date
Additional Configuration: Any custom logic, such as sort options, how a vertical should rank against other verticals, or icons

Step 2: Collect Data and Set Up Knowledge Graph

Now that you have a strategy, it's time to gather and organize your data in the Yext platform.

As mentioned in the previous step, the quality of your data will impact the quality of your Search experience. When collecting data, you'll want to make sure you consider your data sources:

Where will the data come from?
How can you pull that data and ingest it into Yext?
How can you keep that content up-to-date? Be careful not to mislead users with stale data or introduce manual processes to maintain your data.

Set Up Your Content Structure

For each vertical, enable the entity type if it already exists. Otherwise, create a custom entity type for each content type.
Add these custom fields:
- "Active in Search" (Type = Yes/No): Use this field to control which entities appear in search without deleting them.
- "Primary CTA" and "Secondary CTA" (Type = Call to Action): Use these fields for calls to action on result cards.
- Any other relevant fields

Ingest Your Data

The ways you can add data are:

Data Connector: Build a data connector with an optional crawler.
1. If you are using a crawler, make sure you're crawling a structured site to reduce manual adjustment, errors, and poor data in the initial crawl and when new content is introduced.
  - Can you identify the URLs to crawl for each vertical? If yes, are the URL structures comprehensive?
  - Can the pages be mapped using a unique data mapping? If not, can you map another page component (URL, H1, meta, breadcrumbs, etc.)?
2. Once you set up the crawler, set up the corresponding connector.
3. Whitelist the crawler to give it access to your web pages.
4. Ensure the Connector maps to and collects all fields and metadata elements (e.g., Date Posted, Author, etc. for a document) necessary to power your Search experience.
Third-Party Integration: Use an existing app or build an integration with a third-party where your content is stored.
File Upload: Upload a data file (CSV or XLSX).

Organize Your Data

Create saved filters to restrict entities in Search to only those that have been fully vetted and approved. We recommend creating a saved filter for each vertical with the following criteria:

Active on Search = Yes
Entity Type
Fields with Data include "Website URL" or "Primary Image" (if you would like to ensure only entities with populated data for these fields appear in Search)
Any other relevant criteria

Audit Your Data

Ensure you have collected and added the relevant data into the Yext platform:

Have you populated entities for each vertical?
Is structured information available for sorting, filtering, and facets?
Is there structured content for frontend cards (e.g., images)?
Have you added any information needed for query rules or other business logic?

Step 3: Configure Your Search Backend

Once you have content in the platform that can be indexed, it's time to set up the configuration that specifies what data to index and how in your Search experience. You will configure business rules and search logic to define the scope of what the Search algorithms should return.

Create a Search Configuration

Start by creating or duplicating a Search configuration. If you are building a multi-language Search experience, first decide how to structure the backend (i.e., whether you'll use one or multiple configs).

Set Up Vertical Configurations

For each vertical in your experience, add the following:

Verticals: Add verticals, specifying which entities can be returned in each one using saved filters.
Searchable Fields: Specify which fields to index and the algorithm for each. This is required for every vertical.
- Review the Searchable Fields Best Practices document for recommendations on when to use each type of searchable field.
- Best Practice: Start with a few basic searchable fields and add more later based on search quality. Adding too many upfront may obscure search performance.
Display Fields: Use this optional property to specify which fields should be returned in the API response, which helps decrease API latency. By default, the API response returns all fields associated with the entity.
- The API response does not return fields from related entities by default, so you must specify them as display fields if you want to display them in the frontend.
- Note: If you use this property, you must include all fields you want to display on the front end.
Direct Answers: Select fields to display results that directly answer user queries at the top of the results, either as field value direct answers (from structured data) or featured snippets (from unstructured data).
Facets and Filters: Set fields as facets and filters to allow users to refine their search results.
Sorting: Specify how you want results sorted by default.
Dynamic Reranking: Turn this on to allow the algorithm to gradually optimize the order of results based on the number of clicks received.
Vertical Ranking: Configure properties to adjust which verticals are returned and how they rank against each other in search.

Set Up Search-Level Configurations

These configurations apply across your entire search experience. You might have pre-existing or known logic for the following, but otherwise these can be configured and fine-tuned when running test searches to improve search quality.

Synonyms: Specify words and phrases that Search should consider equivalent. We recommend starting with a minimal list and adding more as needed to improve search quality.
Query Rules: Adjust search results with precise rules. We recommend adjusting your core configuration first before adding query rules to modify results returned by the algorithm.
Query Suggestions: Suggest a range of prompts to autocomplete user search queries. We recommend targeting your organization's KPIs, showcasing the breadth of your data, and ensuring prompt results look good.
Generative Answers: Enable AI-generated summaries of top search results to be displayed at the top of the page.
Bounding Box: To get more accurate results when searching for locations within a specific region, add a bounding box to limit the geographic area the algorithm searches.

Set Up Specialized Configurations

International: Set the supported locale(s) to match your entities.
- Note: If your entity profiles use the locale "English" (en), then the requested locale must be exactly "en." Requests for similar locales like "en_GB" or "en_US" will only return profiles with that exact locale.
Healthcare: Follow the Set Up Your Search Configuration for Healthcare guide.
- Consider incorporating the Yext Healthcare Taxonomy to allow users to search for specific conditions (like "knee pain") and return doctors with the appropriate Yext Category.
Third-Party Verticals: If needed, follow the reference doc to set up a third-party vertical.

Test and Refine

Use Test Search to run test queries and ensure you get the expected results. Make tweaks to optimize the configuration and identify areas for improvement. You'll do more thorough QA in a couple of steps.

Step 4: Set Up Search Frontend

Now that you've specified what results to return and how, you can design how users will see the results displayed visually. There are multiple ways you can build a Search frontend.

Hitchhikers Theme (Low Code)

The Hitchhikers Theme is a low-code option that allows you to quickly build an out-of-the-box frontend using JSON, HTML, CSS, and JavaScript. This can be easily configured using a combination of pre-built templates (the Hitchhikers Theme) built off a JavaScript library (the Search UI SDK) and a static site generator (Jambo) that gives you an easy-to-use code editor UI.

If you build your frontend with the Hitchhikers Theme, you'll be working in the Pages section of the Yext platform. Customize according to your branding by configuring which templates you use, customizing certain properties, and adding styling.

Create a Search Frontend Site: Add the experience key to connect the backend and frontend.
- (Multi-language) Add additional locales.
- Set up other global settings, such as logo, favicon, and Google Analytics ID.
Set Up Pages: Create a universal results page (name it "index") and a separate page for each vertical you added to the backend.
Customize Pages:
1. Set page metadata (e.g., page title).
2. In the page settings for vertical pages, make sure the verticalKey is set correctly.
3. Change the card types on the vertical page if you want to use another built-in card.
4. Add or remove page components, then edit the settings. This typically includes commenting in the following components:
  - Facets: Comment in the Handlebars partials, including for collapsible filters.
  - Sorting: Comment in the Handlebars partials and specify component settings for this to appear.
  - Generative Answers: Comment in the Handlebars partials and enable generative answers in the global config file.
5. Edit page and component settings. Adjust any settings from the default.
Add Custom Cards: If you want to change anything from pre-built result card templates, add a custom card and set the card type on the vertical page.
1. Change target behavior of links.
2. Update CTAs, including Analytics event types.
3. Override direct answer card formatting.
(Advanced) If you want to add or re-order anything on either a page or card, you can change the page or card structure.
Add Branding and Styling.
1. Update standard branding elements. Update these common variables:
  - --hh-answers-background-color: background color
  - --yxt-color-brand-primary: includes title links, CTAs, nav menu items and view all links
  - --yxt-color-text-primary: includes text color of the search bar text, card text, nav bar text, and vertical title text
2. Update custom branding elements. If there are still elements you want to update after updating the standard ones, add your own CSS.
3. Add images and fonts.
4. Customize maps and map pins.
5. Customize CTA buttons to match your brand's styling.
Debug any frontend display issues.

Search UI React

The Search UI React library contains customizable UI components that are fully functional and stylized out of the box. This library provides developers the quickest way to get your Search experience up and running.

Note: To get started quickly, check out the quick starts on how to add Search UI React components to a single-page React application using Yext Pages, Vite, or Next.js.

Set up your development environment.
Configure your application for Search.
Add components.
Add Analytics. Follow the Get Started with Analytics guide to add analytics to your search experience.

Other Ways to Build

If you're not looking to use the Hitchhikers Theme or Search UI React and would like to develop your own frontend, get started with these options:

Step 5: QA

Once you've built your Search experience, you'll want to QA it to ensure everything looks and works as expected before sharing it with stakeholders and integrating it onto your site.

Search Quality Testing

Ensure your top queries (such as "locations near me") return expected results and make adjustments as needed.

Remember that Search requires a continuous cycle of improvement. The philosophy behind implementation QA is to account for the top queries. Once the experience is launched, you'll want to monitor what users are searching for, review data and analytics, and further improve the quality of search results.

Run Top Queries: Test 10-20 common queries within the staging environment. These can be top queries from the site's current search or queries you consider most important to perform well. For each query, note whether the results returned meet, partially meet, or do not meet the expected results.
- Distinguish whether improvements needed are for the display (the frontend) or for what results appear, i.e., the search quality (the backend).
- You can also use Test Search, which will only return the results passed by the backend.
Debug: If results are not ideal, debug to determine why the expected results are not returned.
1. Review the trainings related to debugging and optimizing:
  - Search Optimizations: Understand the types of changes needed to improve search quality (content changes, backend configuration changes, and algorithm changes).
  - Debug the Backend: Understand the general approach to debugging backend search quality issues.
  - Experience Training: Understand how you can train the algorithm for inferred filters, spell check, and featured snippets.
  - Overview of Algorithm and Indexing: Understand at a high level how the Search algorithm works. There may be cases where you think there's a search quality issue when it is expected behavior.
  - Query Rules: If, after debugging, you find that the results returned are expected but you still have a reason to tweak them, you can add a query rule.
  - Search Merchandiser: Learn about the UI tool you can use to add particular query rules.
2. Follow How to Start Debugging Backend Search Issues for step-by-step guidance.
Optimize: Make changes to your configuration, run the query again, and note whether the actions taken improved the results. You may need to tinker with the configuration a few times to get the results expected.

Browser and Device Testing

Test different browsers and devices to ensure the experience performs consistently across them. Use an emulator like Browserstack to easily test different browsers and devices.

For each browser or device, run searches and click around to use the different features and verticals of the Search experience. We recommend testing:

Google Chrome (latest two versions)
Firefox (latest two versions)
Safari
Microsoft Edge
Android (Chrome and Firefox)
iPhone (Safari, Chrome, and Firefox)
Tablet (Safari, Chrome, and Firefox)

Feature Testing

We recommend you test this list of features, if applicable. Run searches to activate the feature and click around to use the feature to ensure each works as expected.

Location map on both universal and vertical search
Direct Answers, including Featured Snippets
Vertical Tab & "View All" Navigation
Facets and Filter Components
Configured No Results Behavior
Spellcheck Component
Location Bias Component
Pagination Component
Query Rules
Configurable Sorting
Custom Backends
iFrame ([production url]/iframe.js)
Data Variability: Be sure to run queries that would return different sets of data, including null (blank fields) to ensure the search quality and display are still as expected.

User Interface Testing

While clicking through the Search experience testing all of the above, confirm the experience looks consistent and has no visual defects, including incorrect spacing, adjusted coloring, or trailing text.

Analytics Testing

Ensure Analytics events are firing correctly by following the instructions in the How to QA Analytics section.

Step 6: Integrate and Launch

Now that you've built and tested your Search experience, you're ready to integrate it on your site.

Note: Each site will have a placeholder domain that it publishes to until you set a domain. You don't have to decide on the integration method until you're ready to integrate.

Pre-Integration Checklist

(Subdomain integration) Add your favicon, meta description, and meta title to all pages.
Set up IP filtering if there are any IP addresses you don't want to include in analytics as "external" traffic. Note that all users who log into the Yext platform will be tracked as "internal" via cookie.
Add your Google Analytics ID or Google Tag Manager ID.

Integration

Hitchhikers Theme

Decide on your integration method:
1. JavaScript Snippet (iFrame): Host the search results page somewhere on your existing site. Recommended for a more seamless UX, including keeping the header and footer consistent across your site.
2. Subdomain: Host on Yext if you are unable to host on your existing site. Consider how you will rebuild the header and footer modules to match your site.
Add a Search domain:
1. JavaScript Snippet (iFrame): Use the production version of the placeholder domain, which is automatically assigned when you create your Pages site. You must publish a deploy to production before the production URL is available.
2. Subdomain: Set up a subdomain on your site.
  1. Select a subdomain. We recommend search.[brand].com.
  2. Set up the CNAME record on your site.
  3. Add the chosen domain in the Yext platform (e.g. search.[brand].com).
Publish the frontend and backend to production.
Stand up the search results page.
- (Optional) Add Sitelinks search box schema to allow Google to redirect Google search traffic to your internal search.
Add or update the search bar. We recommend adding a prominent search bar in the header of your website and on your homepage to encourage users to use the search (e.g., expand the search bar by default rather than showing a search icon).
1. Check the UI looks good on mobile.
2. (Optional) Style the search bar as necessary to ensure it is seamless with the rest of the site.
3. (Optional) Add typed animation to prompt more users to search.
We also have options for you to integrate with partners, such as Zendesk and WordPress.

Search UI React

If the site you are adding a Search experience to is already built on React, build the Search experience directly onto a page. Otherwise, use the subdomain method above.

Post-Live Testing

Right after you launch your Search experience and before you make any announcements, do some quick testing to ensure everything is working properly.

Click Testing: Click all clickable items - query suggestions, CTAs, FAQ expansions, filters, pagination, "View All" links, etc.
Mobile Testing: Same as above, but in mobile view.
Confirm GA ID is present (if applicable)
Ensure that analytics are showing on the Search Home Screen

Congratulations on launching your Search experience!

Step 7: Post-Launch Optimization

Now that you've launched your Search experience, you need continuous optimization to be successful. See what users are searching for and how the Search experience changes, so you can adapt.

Monitor Query Trends: Continuously check search terms and clusters to see what users are searching for and optimize those results.
Review Analytics: Measure performance and trends through Search Analytics.
Experience Training: Monitor and approve/reject the inferred filters, spelling corrections, and featured snippets proposed by the system to refine the algorithms.
Continue Debugging any unexpected results and improve the search quality of the experience.
Upgrade Theme: If you used the Hitchhikers Theme, check the Hitchhikers Theme Changelog and upgrade the Theme to take advantage of newly released features.