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.
Maintaining Monetate ID Values
Personalized Search is a RESTful API that requires you to make requests to the Engine API. Because Monetate can't set the monetateId as a first-party cookie (mt.v) in an Engine API implementation as it can in a Monetate tag–based implementation, 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 for Personalized Search
A product catalog dataset that you select for use with one or both 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 |
|---|---|
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 cannot exceed 2,000 characters. |
link |
The URL for a product's detail page cannot exceed 2,000 characters. |
description |
Ensure that each value accurately describes the product and is not placeholder text. The character limit is 5,000, and is truncated if the value exceeds this limit. |
price |
The format must be [0-9].[two decimal places] (for example, 12000.00). |
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 |
The value for this attribute can only be [Ii]n [Ss]tock or [Oo]ut of [Ss]tock. This attribute is required for Personalized Search. |
additional_image_link |
The URL for an additional product image cannot exceed 2,000 characters. |
age_group |
The character limit is 200, and is truncated if the value exceeds this limit. |
brand |
The character limit is 200, and is truncated if the value exceeds this limit. |
color |
The character limit is 200, and is truncated if the value exceeds this limit. |
condition |
The character limit is 200, and is truncated if the value exceeds this limit. |
gender |
The character limit is 200, and is truncated if the value exceeds this limit. |
material |
The character limit is 200, and is truncated if the value 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, and is truncated if the value exceeds this limit. |
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.
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.