loading

Criteria| Hitchhikers Platform

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 Answers experience. This will stay consistent during their Answers 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.

light bulb
Tip
Get insight into where users are coming to Answers from by dimensioning on Referrer URL or Referrer Domain in Report Builder. Learn more about this use case in the Answers 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:

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 Answers 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 Answers 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 Answers library is initialized. Looking at the instructions to initialize the library in the (integration guide here), you’ll see that the onReady function calls an Answers 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 Answers 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 Answers 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"
          ]
        }
      ]
    }
  ],
unit Quiz
+20 points
Daily Quiz Streak Daily Quiz Streak: 0
Quiz Accuracy Streak Quiz Accuracy Streak: 0
    Error Success Question 1 of 3

    Which of the following is NOT a supported property for criteria?

    Error Success Question 2 of 3

    If a site is already capturing whether a site visitor is a ‘prospect’, could context be used to tailor an Action for ‘prospect’ site visitors?

    Error Success Question 3 of 3

    How can the context object be set? Select all that apply.

    Way to go, you passed! 🏁

    You've already completed this quiz, so you can't earn more points.You completed this quiz in 1 attempt and earned 0 points! Feel free to review your answers and move on when you're ready.
1st attempt
0 incorrect
Splash Loading