Search

Overview

This guide focuses on the SCAYLE Search configuration in the SCAYLE Panel. To gain a better understanding of the search logic and technical implementation, refer to the Developer Guide.

The search consists of two main endpoints, the /v2/suggestions and the /v2/resolve endpoint.

While they have many similarities, there are also some differences between the two:

As a response to a search term, they may return categories, products, or navigation items.

Both endpoints rely on a good configuration to yield satisfying results.

On this page, you will find out how to define your SCAYLE Search in order to get optimal results.

Configuration

SCAYLE offers a search module that allows you to adjust the output of frontend search results.
You can access the search configuration options in the Shops area through Shops > Shop Name > Storefront > Search.

You can configure the following settings:

• Searchable Navigation Items
• Searchable Attributes
• Synonyms
• Typo Tolerance
• Category Exclusions

Include Navigation Items in Search Results

As our search is category-based, you'll need to manually set the visibility of pages that you want to be searchable, such as Shipping, FAQs, Article pages or SEO pages to include them in the search results.

Define a Navigation Item as Searchable

1. the Go to Shops > Shop > Storefront > Navigation.
2. Click the pen icon next to the required navigation item.
3. Select the Include to Search checkbox.
4. In the Target, select Page from the dropdown.
5. Under Page, select the page you want to include.
6. Click SAVE.

Customers can now retrieve this page by entering relevant keywords or synonyms in the search bar. Synonyms have to be added first. Find out how to add them in the section Navigation Synonyms.

Searchable Attributes

SCAYLE uses attribute groups to define search result logic. Searchable Attributes only affect the Text Search of the Storefront API.

Guidelines

Understanding which attribute groups make for an excellent searchable attribute and which don't is essential. When an attribute group is set as searchable, the search will try to match against any of the words in the assigned attribute.

Examples of suitable searchable attributes

A good candidate for a searchable attribute is an attribute group with short values that users often search for. Here are some common examples:

• Attribute group "color" with example values:
  • "blue"
  • "green"
  • "black"
• Attribute group "material" with example values:
  • "leather"
  • "jeans"
  • "wool"
• Attribute group "productLine" with example values:
  • "airmax"
  • "airforce"
  • "jordan"

Examples of unsuitable searchable attributes

A wrong candidate for a searchable attribute is an attribute group with long descriptions, full of words that will result in unexpected search outcomes. Here are some common examples:

• Attribute group "productDescription" with example values:
  • "This product is sustainable and ecologically sourced from various places in the world"
  • "This product was made with recycled materials and is created by reusing pre- or post-consumer materials"
  • "Waterproof hi-top trainers with a padded edge and tongue, elasticated lacing and a hook and loop tab at the front"

The reason these are bad is that if any word in the user's search matches any word in the attribute value, the product will be returned in the search results.
As an example, if a user searches for "tongue brush", the search will also return products with the 3rd attribute value in the above example, as it includes the word "tongue". Even though the product has nothing to do with the user's search term.

Another common issue is when a searchable attribute includes unnecessary terms or search-unfriendly terms. Here are some examples:

• Attribute group "material", with example values:
  • "Linen (from organic farming)"
  • "Dried flowers"
  • "Broom plant"
• Attribute group "color" with example values:
  • "Off white"
  • "Egg shell"
  • "Mixed color"

These examples have a high chance of showing up in completely irrelevant searches.
As an example, if someone searches for "broom", products with the material "broom plant" will show up, regardless of whether they're brooms or not. Or if someone searches for "off season", then products with the color "off white" will show up.

It is strongly recommended that the searchable attribute groups have very straightforward, simple and commonly searched terms as values.

Add an Attribute to the Search Result Logic

1. Click + Add First Attribute.
2. Select an attribute from the dropdown.

Use drag and drop to assign priorities to these groups to influence their order in the search results. Attribute groups with a higher priority affect the search results order significantly more than those with a lower priority.

Synonyms

The Synonyms area bundles various options for managing synonyms. Synonyms play an essential role in the output of search results, as the system can recognize which terms are considered equivalent. Use the tabs to define synonyms for single search words, categories, and attributes.

Category Synonyms

We support defining synonyms for your existing categories. The category synonyms work like alternative names for the specified category, as they are stored alongside the normal name of the category.

Benefits

1. Synonyms stay attached to the category even if you rename the category
2. They are easier to maintain and feature less risk
3. They work with autocomplete endpoints
4. They work with typo tolerance

Guidelines

As a general guideline, we recommend adding category synonyms to applicable categories instead of word synonyms. Adding category synonyms will work seamlessly with other endpoint functionalities, such as autocomplete and typo tolerance.

As an example, if a category is called "Shirts", but users search for "T-Shirt" then this would be a good candidate to add "T-Shirt" as a synonym.
On our search endpoints, the category "Shirts" would then be returned when the user types in "Shirts" or "T-Shirt".

Before you start:

Add a New Category Synonym

1. Go to Shops > Shop Name > Storefront > Search > Synonyms.
2. Select CATEGORIES tab.
3. Click + New Category.
4. A drop-down menu opens where you select the corresponding category and enter suitable synonyms.

Add Category Synonyms in Bulk

To find out how to add category synonyms in bulk, please see the documentation on imports & jobs in the User Guide.

Attribute Group Synonyms

We support defining synonyms for your existing attributes. Similar to the category synonyms, these are alternative names for your specified attribute and are stored alongside the normal name of the attribute.

Benefits

1. Synonyms stay attached to the attribute even if you rename the attribute
2. They are easier to maintain and feature less risk
3. They work with autocomplete endpoints
4. They work with typo tolerance

Guidelines

As an example, if an attribute group "color" has an attribute "purple", but users search "lila" then this would be a good candidate to add "lila" as a synonym.

Before you start:

For attributes to be used for matching search terms to products, you must add these attributes to the Search Result Logic first.

Add a New Attribute Group Synonym

1. Go to Shops > Shop Name > Storefront > Search > Synonyms.
2. Select the ATTRIBUTES tab.
3. Click + New Attribute.
4. In the popup, select Attribute group, Attribute, and Synonyms.

Add Attribute Group Synonyms in Bulk

To find out how to add attribute group synonyms in bulk, please see the documentation on imports & jobs in the User Guide.

Word synonyms

Word Synonyms allow you to dynamically replace certain words from the user's search term.

Benefits

Word synonyms are synonyms that apply across our search endpoints suggestions and resolve, but also work for product search through the products endpoint, which can be used as a fallback, when no matching category or navigation item is found.

Guidelines

The general guideline is to put existing categories, product names and attributes on the left and terms that users might search for (but don't have a matching category/product name/attribute) on the right.

Word synonyms work best for cases where a user searches for a single word, which is a combined term of an existing attribute and an existing category. This is quite common in some languages, like German.
As an example, if a user searches "leinenhose", but "leinen" is an attribute and "hose" is a category, then this is a good candidate for adding a word synonym, where "leinenhose" (the right term) would get mapped into "leinen hose" (the left term).

Word synonyms are also good candidates for improving search on product names.
As an example, the product is called "air max", but the users search for "airmax". This is then a good candidate for a word synonym, where "airmax" (right term) would get mapped into "air max" (left term).

Add a New Word Synonym

1. Go to Shops > Shop Name > Storefront > Search > Synonyms.
2. Select the WORDS tab.
3. Click + New Word to enter search terms and synonyms for words.
4. Under Word, enter the terms which your users are searching for.
5. Under Synonyms, enter the alternatives for the search term.

When searching, the searched terms on the right side (in the screenshot below) will be linked with the term on the left.
As an example, if there is a synonym set up for "denim => jeans" and the user searches for "denim", in the background we will search for "jeans".

Navigation Synonyms

Add a synonym of a navigation item at a local shop level.

Benefits

In the case of navigation items, there may be a lot of use cases for different wording. While a product usually has a given name, a page can be named in very different ways from website to website. Navigation item synonyms allow for you to cover those different wordings.

Guidelines

When you want your users to be able to search for navigation items, make sure to include some synonyms as well. Imagine you have a page called "Shipping", that informs user about expected delivery timelines, delivery cost, etc.

Once you define that navigation item as searchable, consider what synonyms users could also be searching for. An example for a good synonym in this use case would be "Delivery".

If you have an FAQ page, consider adding "Frequently Asked Questions" as a synonym.

Add a Navigation Item Synonym

1. Go to Shops > Country > Storefront > Search > Synonyms.
2. In the NAVIGATION ITEMS section, click + ADD SYNONYM.
3. Click SAVE SYNONYM.

Typo Tolerance

For our previous endpoints /v1/typeahead and /v1/resolve it was allowed to configure the typo tolerance we apply; however, we recommend leaving this with AUTO.

In the new V2 endpoints, /v2/suggestions and /v2/resolve, the setting is not considered anymore. The typo tolerance settings are explained more in detail in the Developer Guide.

Stop Words

In the Words area, you define "stop words". Stop words are those words that occur particularly frequently but do not have much meaning or are used as filler words (for example, "the", "that", "everything", "at", "on" or "in"). By excluding stop words from search queries, the quality of generated search results is increased.

Excluding Categories from Search Results

Benefits

When you exclude a specific category from the search results, they will not be returned through any of our search endpoints. You may use this functionality if, for example, you have a category for VIP products that should not be visible to every user of your shop.

Exclude a Category from Search Results

1. In the SCAYLE Panel, go to Shops > Shop Name > Products > Categories.
2. Under GENERAL INFO > Category Configuration, select the Exclude from Search checkbox.
3. Click SAVE.

Result: This shop category will not be considered for the search in the Shop Storefront.

Further education - SCAYLE Academy

Course

The new SCAYLE search

Functionality of the V2 search endpoints

• Search
• Business

Pia Nadolny

Junior Business Consultant

Onsite Search

The new SCAYLE search

• Beginner
• 2 lessons
• 6m

Play tutorial

Frequently Asked Questions

General

Question:

• Can a search request for a specific Product ID be redirected directly to the Product Detail Page (PDP)?

Answer:

• Yes, this is possible, but it requires proper frontend implementation. Storefront API tries to resolve the Product ID based on the Product Id, Reference Key or EAN if the perfect match is provided.

---

Question:

• Can a Product ID be set up as a synonym for a specific term?

Answer:

• Technically, it is possible to set up a word synonym for a Product ID. However, with the Search V2 endpoints, a perfect match is required for the product search, as no fuzziness is applied.

---

Question:

• We use Navigation Items to create content pages like FAQs, Shipping Costs, Size Guides, etc. I read that Navigation Items are supported in the Search V2 endpoints. If I set them up in the SCAYLE Panel, will they work by default?

Answer:

• If your e-commerce shop already uses Navigation Items and you tag them with the “Include in search” checkmark, they will be available to the new Search V2 endpoints. However, to display them in the frontend search, you will need to implement additional frontend changes.

---

Question:

• I recently updated some search configurations for synonyms in the SCAYLE Panel for my e-commerce shop. When will these changes be visible to users?

Answer:

• The changes won't be applied immediately. However, depending on the client and the size of the shop, it takes between 1 to 3 hours for the changes to become visible to your users.

---

Question:

• What technical requirements must be met to implement Search V2 endpoints?

Answer:

• For clients using our NPM packages, the only requirement is to use the @scayle/storefront-api NPM package.

---

Question:

• Where can I find more information on configuring search with Search V2 endpoints?

Answer:

• You can refer to the SCAYLE Configuration guidelines or visit our SCAYLE Academy platform, where you can take search courses to enhance your search skills.

---

Question:

• Can we choose where to direct the user if there are multiple categories with similar names?

Answer:

• Yes, the best approach is to exclude the categories you don’t want users to find, leaving only the one you want them to be directed to. You can exclude categories through the configuration settings outlined here.

Question:

• Why is my search term not resolved to a Category Page?

Answer:

• The highest priority is to resolve search terms to specific category pages. In case you identify that certain search terms are not resolved to a category page but rather redirected to a search result page, you can take the following actions:
  Try to discover the intention of the users when searching for the term. In most cases, the term can be translated to a shop category. For instance, customers searching for “denim” could also refer to “jeans”.
  Check whether you maintain a shop category that matches the meaning of the search term. If yes, you can create a category synonym to map further searches with the term to the corresponding category page.
  If you do not maintain a matching category, you can create a category. This is especially recommended when the search term is frequently used.
  If the search term is only used a few times, it is also feasible to accept that users are redirected to a search result page. In such cases, we recommend configuring a proper setup of Searchable Attributes.

---

Question:

• How can I improve the results on my Result Page?

Answer:

• A search results page should only be shown in exceptional cases, as the goal is to always redirect the user to a matched category page.
  Still, the results on the search results page should be of good quality. For that, a good configuration of the Searchable Attributes is key.
  Check our configuration guide on how to configure your Searchable Attributes.
  Furthermore, you can create word synonyms for products that users may search for with different spellings (for example, Air Max and Airmax). Find out how to create word synonyms here.

---

Question:

• How Can I Improve my Search Results with Compound Words?

Answer:

• Compound words are individual words made from two or more words working together. These can be very typical in the German language, for example: "Leinenhose", "Strickjacke", "Kaschmirpullover", "Rippenhose".
  In this case, we recommend to create a word synonym that splits the two words into separate words.
  Leinen Hose <= Leinenhose
  This will allow our system to correctly identify the category and other attributes in the search term.

---

Configuration:

Question:

• I read that your Search V2 endpoints support boolean filters, such as “New” or “Sale”, in addition to attribute filters. However, when I search for “shoes sale,” I am not redirected to the “Shoes” category with the “Sale” filter applied.

Answer:

• While Search V2 endpoints do support boolean filters like “Sale” or “New,” proper functionality in the e-commerce shop requires a frontend implementation to handle this use case and redirect the user to the correct URL. In the response body of the Storefront API search endpoints, you can find data of category & applied filters and use this data to build a frontend behavior to forward the user to the PLP Page with applied filters. As a preparation for configuring your boolean filters before they are used in search, please use this guideline to set them up with the correct translations.

---

Question:

• Is it possible that for 2 different words, I can set up the same synonym and will it work with new Search V2 endpoints?
  • Example: “trousers” & “pants” with synonyms “jeans”

Answer:

• Yes, you can configure this in the Word Synonyms section of the SCAYLE Panel, and it will work with the new Search V2 endpoints if they are implemented following our guidelines.

---

Question:

• Can synonyms be set up for boolean-defined filters? For example, can "sale" be synonym with "discount"?

Answer:

• Yes, you can configure this in the Word Synonyms section of the SCAYLE Panel. This way, if a user searches for “discount shirts,” the search will yield results as if they had typed “sale shirts.”

---

Question:

• Can I create a synonym for the overall brand category used in our e-commerce shop, rather than doing it for the brand categories on the different gender levels? For example, create a synonym for the category Brands/AboutYou, rather than for Men/Brands/AboutYou and Women/Brands/AboutYou?

Answer:

• If you have two brand categories, one for female and one for male, the synonyms need to be set on both categories. Additionally, if you create a third category, e.g. Brands/AboutYou and only set the synonym here, the gender-specific brands will not be suggested.

---

Question:

• Can I configure which filters for a specific category will be considered in the search?

Answer:

• Yes, all filters assigned to a category will be taken into account in the search algorithm. You can add or remove filters, and based on that, they will either appear or disappear on the category page and in the search results.