Best Practices and Troubleshooting | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• Best practices for creating a new vertical
• Common errors and ways to troubleshoot

Best Practices

Adding a new vertical can be daunting, but it’s actually pretty straightforward if you follow a few key best practices:

Understand the entity type’s data first. What type of data is it? What kind of fields will it have? What is the data itself like and in what format? You don’t need to know everything because you can always make adjustments later, but it’s still important to know what kind of information you’re hoping will surface in the search results.

Understand the KPIs of the entity type. Why is it important to add this entity type? Are you trying to drive more bookings? Drive down customer support costs? Quicken the customer’s conversion funnel? All of the above? This is important in figuring out things like what searchable fields to use, what CTAs to surface, and so on.

Start Basic and then get more advanced. It’s always easiest if you have something up and running and then to make it look and behave more advanced after that. We recommend getting started with the basics and adding advanced components, additional features, and advanced data mappings once you have something to work with. It’s always easier to iterate!

Common Troubleshooting

If you’re having any issues with adding a new vertical, here are some common things that might have happened:

Knowledge Graph:

You should see most of these errors surfaced while you’re in the Knowledge Graph. For example, if your file doesn’t have the required data, you’ll receive feedback from the Entity Upload. That said, here are some common issues:

• Forgetting to enable the entity type before uploading data
• Forgetting to create fields before uploading data
• Forgetting to include both Country and Entity Type for all new entities in the file
• Forgetting to set “Active on Search” field, or whatever field(s) you’re using to define the saved filter

Search Configuration:

The Search Configuration comes with fairly rigid validation built-in, automatically checking to make sure that the fields and entity types are valid for the account. That said, here are some things to watch out for:

• Saved Filter doesn’t have entities
• Entity type synonyms haven’t been added
• Syntax issues if you’re using the JSON Code Editor
• No searchable fields set, or not the right fields

Frontend:

The frontend can be a little trickier as there’s a wide range of things that could be wrong. For example,

• Invalid verticalKey due to a typo or slight difference in spelling
• Forgetting to create the page
• Invalid data mappings for the type, e.g., the field doesn’t exist

When you’re debugging the frontend, it’s important to use the tools at your disposal that you’ll learn more about in the Debugging module . However, if you’re seeing that your frontend isn’t loading as you would expect, you can always use:

1. the browser’s built-in developer tools for some quick checking
2. the Code Editor’s console

For example, if you’re adding a new vertical for “Community Stories” and your frontend comes out like this:

You know there’s a problem! We would recommend Inspecting the page (right click > Inspect, or something similar depending on your browser) and clicking on the Console tab. While you are not expected to understand all of the details printed on this page (and often times the errors shown on the page can be from completed unrelated extensions or other features, like a password vault or a screenshotting tool), there may be some helpful hints. In this case, there’s a line that tells us what the problem is:

For those without a magnifying glass, that reads: Caused By: ReferenceError: joinList is not defined

This might set off a lightbulb for you if you know you used a formatter for “joinList” and might point you in the right direction.

The other place to check is the Code Editor console. When you click “Update Preview”, there may be an error that is printed in the console logs as jambo attempts to build your site. For example, this might catch things like invalid syntax with missing or extra commas.