Criteria | Hitchhikers

What You’ll Learn

In this section, you will learn:

How to structure the criteria object
Supported properties for criteria
What is context and how is it used

Criteria Structure

The criteria object will be the first property of a Query Rule. An example of the structure is below:

    {
     "criteria": {
        "searchTermContains": [
          "SEARCH_TERM_PHRASE1",
          "SEARCH_TERM_PHRASE2"
        ],
        "searchTypes": "UNIVERSAL"
      },
      "actions": ...
    },

Within the criteria object, you’ll be able to list several properties that represent conditions the search needs to meet.

Criteria Options

Here are the supported properties:

Criteria	Type	Notes	Example Value
searchTermContains	String or Array of Strings	This will do a token match on the search term. If multiple tokens are included it will make sure they are all present	[“Heart attack”, “911”]
searchTermStartsWith	String	This will check if the search term starts with exactly this phrase	“Do you have”
searchTermEndsWith	String	This will check if the search term ends with exactly this phrase	“Near me”
searchTermExactlyMatches	String	This will check if the search term exactly matches this phrase	“Knee Doctors”
searchTermMatchesRegex	Regular Expression	This will use RegEx to determine search term matches. See more on RegEx below.	”.*ologist”
contextContainsKey	JSONPath String	This will check if the context object contains a certain key. If the context contains the key, this criteria will be met. This uses JSONPath.	”$.mobile”
contextMatches	Filter	Using the filter syntax in the example, you can check if a property in the context object equals a specific value.	“contextMatches”: { “$.test”: { “$eq”: “answers”}}
referrerPageURLRegex	Regular Expression	The referrer Page URL is the user’s entry point into the Search experience. This will stay consistent during their Search session.	”.yext.com.“
verticalKeys	Array of Strings	This will restrict the rule to only one or more verticals	[“people”, “locations”]
searchTypes	“ALL”, “VERTICAL”, “UNIVERSAL”	Easily restrict to just Vertical or Universal search. All is the default.	VERTICAL

All criteria must be met in order for the rule to fire. As a note, Search Term based criteria do not take synonyms into consideration.

Want to learn more?

Get insight into where users are coming to Search from by dimensioning on Referrer URL or Referrer Domain in Report Builder. Learn more about this use case in the Search Analytics in Report Builder unit .

Using Regular Expressions

Regular expressions allow you to search for a pattern of characters, and allows more flexibility when you’re looking for query matches.

We won’t dive into the intricacies of regex in this module, but here are some good resources to learn more about using regex:

https://regexone.com/ - Walks through exercises of regex examples
https://regex101.com/ - Allows you to test and validate your regex

Common Regex Examples

You can see a few common examples here:

Zip Code - This will check for any queries that have a 5-digit zip code.
Single and Plural Words - This captures both singular and plural forms of the term you enter.

Have other common regex examples to share? Post in the community!

Context

The context object is simply an arbitrary JavaScript object you can set with any properties you want. This is an incredibly flexible and powerful concept - you can pass in any data you want and use that in a rule.

Context can be set either via a function in the Search JavaScript Library, or by using query parameters that are passed along when a user conducts a search.

Setting the Context

You can set the context via the Search JavaScript library function ANSWERS.setContext(). The function accepts a JavaScript object. Below are the three most common ways you’ll be setting the context. In our examples, we will be setting the below context:

{
  jobProspect: true, 
  market: "Mid-Atlantic"
}

Search Bar Integration

In order to use the setContext function, you’ll need to place this after the Search library is initialized. Looking at the instructions to initialize the library in the ( integration guide here ), you’ll see that the onReady function calls a Search function (addComponent). A good place to set the context would be underneath the addComponent call, as you can see below.

<head>
  <!-- Other stuff in the head here -->
  <link
    rel="stylesheet"
    type="text/css"
    href="https://assets.sitescdn.net/answers-search-bar/v1.0/answers.css"
  />
  <script src="https://assets.sitescdn.net/answers-search-bar/v1.0/answerstemplates.compiled.min.js"></script>
  <script>
    function initAnswers() {
      ANSWERS.init({
        apiKey: "REPLACE_ME_API_KEY",
        experienceKey: "REPLACE_ME_EXPERIENCE_KEY",
        experienceVersion: "PRODUCTION",
        locale: "en", // e.g. en
        businessId: "REPLACE_ME_BUSINESS_ID",
        templateBundle: TemplateBundle.default,
        onReady: function() {
          ANSWERS.addComponent("SearchBar", {
            container: ".search_form",
            name: "search-bar", 
            redirectUrl: "REPLACE_ME_SEARCH_RESULT_URL",
            placeholderText: "Search...",
          });
          //Set Context Function goes here
          ANSWERS.setContext({jobProspect: true, market: "Mid-Atlantic"});
        },
      });
    }
  </script>
  <script
    src="https://assets.sitescdn.net/answers-search-bar/v1.0/answers.min.js"
    onload="ANSWERS.domReady(initAnswers)"
    async
    defer
  ></script>
</head>

Jambo Search Results Page

Similarly, we need to call the setContext function after the Search library is initialized on the search results page. To do this, you will need to override the theme and edit the script > after-init.js file. This file loads after the Search library is loaded on the page, which ensures you’re able to call the setContext() function.

In this file, you’ll see a section that looks like the below. Here, we’ve added the line ANSWERS.setContext({jobProspect: true, market: "Mid-Atlantic"}); within the onReady to set the context to these values.

  ANSWERS.setContext({jobProspect: true, market: "Mid-Atlantic"});

Using Query Parameters

You’ll notice that when you start setting the context, the URL will update to reflect that context. You can also set the context by adding the query parameter yourself - simply append the context to the end of the URL.

&context={"jobProspect": true, "market": "Mid-Atlantic"}

Context Contains Key

You may want to base a rule off of whether a specific key exists in your context object. For example, if you’re already capturing whether a site visitor is a prospect, you could create a context object with a key prospect.

{
 "prospect": true
}

Then, in your criteria, you can check whether or not the context contains the prospect key. (Criteria Context uses JSONPath to do matching. Learn more about JSONPath here .)

      "criteria": {
        "contextContainsKey": "$.prospect"
      }

After you have this knowledge, you can use this to create an ‘action’ tailored to the user type - for example, promote sales-related FAQs or demote promotions geared towards existing customers.

Context Matches

If you want to take it a step further, you’re also able to match the value of a property in order to trigger an action. For example, we could check that the value of the jobProspect equals true and the market equals Mid-Atlantic.

  "criteria": {
        "contextMatches": {
            "$.jobProspect": {
              "$eq": true
            }, 
            "$.market": {
              "$eq": "Mid-Atlantic"
            }
          }
      },

If the key does not exist, or the value doesn’t match the condition, the rule will not fire.

Using the Context in Actions

Lastly, you’re able to use the value of a property in your context object in your action itself. You can reference the value using bracket notation and JSONPath. If we have a field called market in our Product entity, we would be able to:

Use contextContainsKey to check if the key is present

Use the value of $.market to filter the Product results returned

"rules": [
{
  "criteria": {
    "contextContainsKey": "$.market"
  },
  "actions": [
    {
      "actionType": "ADD_FILTER",
      "filter": {
        "c_market": {
          "$eq": "{{$.market}}"
        }
      },
      "verticalKeys": [
        "products"
      ]
    }
  ]
}
],

Criteria | Yext Hitchhikers Platform