The information herein can help you determine how you want to implement and optimize Monetate's Personalized Search features on your site(s). Contact your dedicated Customer Success Manager (CSM) if you have follow-up questions.
Implementation Options
Personalized Search is a RESTful API that's available to clients with Engine API implementations as well as to clients using the Monetate JavaScript API, also known as a Monetate tag implementation.
If you've implemented the Monetate tag on your site(s), then instead of making request calls to the Personalized Search API, you can use customized Personalized Search Results and Personalized Search Suggestions action templates to deploy suggested search terms and products and full site search using a Web experience. Refer to Create a Personalized Site Search Experience for more information.
All Monetate clients implementing Personalized Search must send a decision request to the Engine API on page load to receive a search token, which contains information relevant to the experience, and it's required for all Personalized Search API calls. Include this token in all Personalized Search API requests made while the customer is on the same page. Request another search token when the customer navigates to another page of your site.
Maintaining Monetate ID Values
Because the personalization aspects of Personalized Search are fueled by contextual information about a visitor to your site, you must implement some method of identifying visitors and collect data about their onsite behavior.
If you've implemented the Monetate tag, then Monetate can set the monetateId as a first-party cookie (mt.v). Refer to The Monetate Session to learn more.
If you've implemented Engine API on your site(s), then Monetate can't set the mt.v cookie. Therefore, your requesting application is responsible for keeping track of the monetateId by setting the cookie or otherwise storing or maintaining the persistence of the value by other means unique to your application. You must establish some means of storing or maintaining the persistence of the value of a customer's monetateId so that purchase-related data, including sales generated through search, is reported and recorded correctly. Refer to User Identity Persistence in Requests in the Monetate Developer Hub for more information.
Selecting a Product Catalog
Personalized Search doesn't crawl and index your site. Instead, it uses the information that you pass to Monetate in a product catalog dataset that you select along with additional information that you pass in Personalized Search API requests.
The product catalog dataset that you select for use with Personalized Search features must not only adhere to Monetate's product catalog dataset specification, but also comply with requirements for specific attributes and their values that are in addition to the requirements established in Monetate's specification. The following table contains those additional requirements.
| Attribute | Description |
|---|---|
item_group_id |
Each value is limited to a maximum of 50 alphanumeric characters, ampersands, colons, hyphens, underscores, spaces, or periods so that it matches the regular expression ^[a-zA-Z0-9_\- :.&]+$.
Note: These requirements are the same as the ones provided in the product catalog specification. |
id |
Each value, which must match the product SKU if you're passing SKUs in your integration, is limited to a maximum of 50 alphanumeric characters, ampersands, colons, hyphens, underscores, spaces, or periods so that it matches the regular expression ^[a-zA-Z0-9_\- :.&]+$.
Warning: While these requirements are the same as the ones provided in the product catalog specification, be aware that if a value fails to meet these requirments, then the product is unavailable to Personalized Search. |
title |
A product's name is limited to 150 characters and is truncated if the value exceeds this limit. |
image_link |
The URL for a product's main image must begin with https:// or http:// and cannot exceed 2,000 characters. Any commas and spaces that are natively part of the URL must have proper UTF-8 URL encoding. |
link |
The URL for a product's detail page must begin with https:// or http:// and cannot exceed 2,000 characters. Any commas and spaces that are natively part of the URL must have proper UTF-8 URL encoding. |
description |
Ensure that each value accurately describes the product and is not placeholder text. The character limit is 5,000, and the value is truncated if it exceeds this limit. |
price |
The format must be [0-9].[two decimal places] (for example, 12000.00). If sale_price is present, then its value is used instead of the price value. |
product_type |
Use only a greater-than symbol (>) to indicate the hierarchy of the full path of a category to which a product belongs. Each segment of the string can't exceed 100 characters, and the full string cannot exceed 750 characters. |
availability |
This attribute is required for Personalized Search. The value can only be [Ii]n [Ss]tock or [Oo]ut of [Ss]tock. See Maintaining Product Data Integrity for more information. |
additional_image_link |
The URL for an additional product image must begin with https:// or http:// and cannot exceed 2,000 characters. Any commas and spaces that are natively part of the URL must have proper UTF-8 URL encoding. |
age_group |
The character limit is 200. The value is truncated if it exceeds this limit. |
brand |
The character limit is 200. The value is truncated if it exceeds this limit. |
color |
The character limit is 200. The value is truncated if it exceeds this limit. |
condition |
The character limit is 200. The value is truncated if it exceeds this limit. |
gender |
The character limit is 200. The value is truncated if it exceeds this limit. |
material |
The character limit is 200. The value is truncated if it exceeds this limit. |
rating |
The format must be [0-5].[one decimal place] (for example, 4.9). |
sale_price |
The format must be [0-9].[two decimal places] (for example, 12000.00). |
size |
The character limit is 200. The value is truncated if it exceeds this limit. |
When Monetate maps a product catalog dataset for use with Personalized Search, it converts any custom attribute value that is a date, Boolean, or numerical data type to the string data type. This conversion doesn't impact how the product catalog data works with other Monetate features and functions.
Your dedicated CSM will assess the product catalog dataset that you select and alert you to specific modifications required as part of the Personalized Search onboarding process.
Optimizing Key Attributes
Keep in mind these best practices as you prepare a product catalog dataset for mapping with Personalized Search.
Title
Ensure to include the main product noun (for example, coat, lamp) in the title value so that natural language processing can more readily understand the object the title identifies. Personalized Search identifies the main product noun from every title value and prioritizes relevant products when customers search for the respective product noun.
Avoid including unnecessary information such as technical specifications or additional parts in the title value. The title should first and foremost identify what the product is (for example, Men's Wool Sweater or 32-inch LED Monitor). Move supplementary details to their respective attributes (for example, color).
Description
Descriptions should complement—not replace—the product information in the title and other supplemental attributes, such as size and color. The description is the attribute where you can provide details such as potential use cases and suitability criteria.
Use natural, clear language when writing descriptions, and avoid incomplete sentences, which can impact relevance scores.
Size
Although Personalized Search can normalize size information, such as equating S with small and M with medium, use consistent values for this attribute throughout the product catalog when possible. For example, avoid using S for some products but using small for others.
Rating
Monetate cannot import ratings information from third-party vendors you work with to collect user-generated content (UGC). Therefore, if you want to allow your customers to filter search results by product ratings, then you must include this data in the product catalog.
Including Multiple Currencies
If you process purchase transactions in multiple currencies, Monetate strongly recommends preparing a product catalog dataset for each currency.
Displaying Product Variants
Some of your products might have multiple SKUs distinguished by color, size, or other attributes. You can show these attribute variations in one product entry on the search results page or personalized category page.
To display product SKU color options, ensure that you include in your mapped product catalog the following attributes:
| Attribute | Data Type | Description |
|---|---|---|
swatch_color |
String | The color of the product variant, represented either by a six-digit hexadecimal color code (for example, #8566ab or a URL for an image you want displayed as the swatch pattern.
Note: You must include the hash character ( #) with the hex color code. |
swatch_label |
String | The name of the product variant's color of the , represented either by a six-digit hexadecimal color code that cannot exceed 200 characters. |
If you want other attributes of product variants displayed, you can include the additional_data_to_return attribute in your mapped product catalog, with a value that can be a string of attribute-value pairs that you've formatted using the JSON.stringify method (for example, "price": "80","image": "fifthlevelfashion.net/image/i403".
Personalized Search indexes the value data as passed. When you include the additionalDataToReturn key in the fields array in a Personalized Search API request, the response returns that data in the same state. Refer to Personalized Site Search Queries or Personalized Category Page Queries for more information.
Maintaining Product Data Integrity
When Monetate maps your selected product catalog dataset for Personalized Search, it removes a row of product data if any required attribute in that row is missing a value or if the value doesn't meet Monetate's specification and any additional specification for Personalized Search as established in the table in this documentation.
If an optional attribute in a row of product data is missing its value or if that value doesn't conform to Monetate's specification and any additional specification for Personalized Search, then Monetate removes the attribute from the row and maps the rest of the row's data.
Monetate can take these same removal actions after you update the mapped product catalog dataset. Therefore, ensure that every time you upload updated product data to Monetate, the file meets the specifications for both attributes and values.
If Monetate must remove a row of product data because it has one or more attributes that fail to meet the specifications or is missing one or more required attributes, then that removed row represents one fewer product or product SKU that Personalized Search can't include in applicable search results—even though a customer could navigate to that product's detail page through means other than search results.
If Monetate must remove an attribute from a row of product data because its value is missing or its value doesn't meet the specifications, then that's one fewer data point on which Personalized Search could potentially match for a customer's search query. The product or product SKU represented by that row of data could still appear in the initial search results, but it could potentially be overlooked if the customer applies a filter based on the attribute that was removed.
When search results or filtered results don't accurately represent the products you have available for sale, customers may not be able to find the products that they want to buy on your site, which then means that you could lose both sales and customers.
Selecting a Search Method
Personalized Search offers about half a dozen different methods it can use to find matches for a customer's search term. If you don't specify a search method in a Personalized Site Search request, then Personalized Search defaults to using each method in a set order until it identifies matches. This default search method order starts with the AND search method, which requires all the words of a search term to be present exactly as typed in a record for it to be included in the results. Refer to Specifying a Search Method in Personalized Site Search Queries for descriptions of each search method, including the default.
Be aware that if you don't specify a search method in Personalized Site Search requests, then the search method that returns results could conceivably be different each time. One consequence is that a customer who searches for similar products multiple times may not see similar results.
Consider this example. A customer comes to a retailer's site, searches for insulated coat, and the associated Personalized Site Search request doesn't have a search method specified. This first time the Personalized Search API identifies matches applying only the AND search method, so the customer is presented with 20 different insulated coats. The customer returns later after the cold weather season has ended. They use the same search term, and the associated Personalized Site Search request once again doesn't have a search method specified. This time, however, the Personalized Search API only identifies five matches after applying the FUZZY_AND search method because it could find no matches using the AND search method (no records containing insulated coat in any mapped attribute value) nor using the WILDCARD_AND search method (no records containing insulated and any words beginning with coat in any mapped attribute value).
Setting a Sort Order
You can set one of nine different sort order options for search results. As with the search method, if you don't specify a sort order in a Personalized Site Search request, then Personalized Search defaults to sorting results by relevance to the search term. Refer to Sorting Results in Personalized Site Search Queries for descriptions of each sort order option.
Determining Relevance
Personalized Search considers a number of data points when calculating each result's relevance to the customer's search term. Over time the weight, or different levels of importance, these data points have on the relevance score evolves as Personalized Search's machine learning observes more of your customers' on-site behavior.
Initially, Personalized Search assigns a default weight to certain key attributes in your mapped product catalog, with the title attribute assigned the most weight. Other highly weighted attributes include product_type, description, price, link, and availability. Personalized Search then calculates a relevancy score for each search result based on which product catalog attribute values contained the customer's search term.
A result's relevancy can then be impacted by a final applied boosting score (FABS) that's determined using three scores: a Product Level Score (PLS), any Rule Based Merchandising Score (RMS) for which the product might qualify, and the product's Self Learning Score (SLS). You can set a PLS for individual products and an RMS for a set of products that share one or more specified values for one or more specified product catalog attributes in the Personalized Search interface. Personalized Search determines the SLS based on such analytics data as product clicks, product purchases, as well as rating data if you choose to include that information. Refer to Boost or Bury Products in Search Results to better understand how each type of rule works and the various ways that Personalized Search can calculate a product's FABS.
Finally, Personalized Search multiplies a product's FABS by its relevancy score to calculate the final relevancy score.
Displaying the Sorted Products
Regardless of which sort order option you use, Personalized Search still considers additional factors to determine the order in which the results are displayed.
Inventory status — If a product is out of stock and you haven't enabled the Show out of stock products in search results setting, then it won't appear in the search results.
Keyword-level rules — Results that are subject to a keyword-level merchandising rule that's been triggered by the customer's search term are always pinned to the top positions. Conversely, results that are subject to a keyword-based product exclusion rule that's been triggered by the customer's search term aren't displayed. If a product is subject to both a keyword-level merchandising rule and a keyword-based product exclusion rule for the same search term, then Personalized Search gives the exclusion rule higher priority.
After accounting for inventory status and keyword-level rules, Personalized Search then sorts the remaining results by their final relevancy score.
Figuring Out Facets
Many of the attributes in your mapped product catalog you can display as filters on your site for customers to use to narrow search results.
By default Personalized Search displays all eligible facets as search results filters on your site, with the filter label as it appears and in the order in which they're listed on the Facets tab of the Personalized Search interface. Therefore, ensure that you take time to think through which product catalog attributes make sense to offer to customers as filters, as well as how you want to style each filter label. Refer to Facets in Search Results Customizations for more information.
Be aware that the price-based filter requires additional configuration not only in Personalized Search API requests but also in your site's code. Refer to Customizing the Price Filter in Search Results Customizations as well as Retrieving the Price Facet in Retrieve and Apply Facets in the Monetate Developer Hub for more details and code samples.