网站商品搜索

商品搜索是网站上的搜索框：输入时显示联想提示，并提供由 OneTrace.pro 用您目录中的商品填充的结果页。搜索能识别错别字、词形变化、用错键盘布局输入的查询、查询文本中的价格和品牌以及描述性查询的含义，并按访客的兴趣和其他顾客的选择排列靠前的结果。现成的搜索小组件会自行显示联想提示和结果页，无需在网站上编写代码。

使用搜索需要已安装追踪器（接入网站）和商品目录（推荐与商品目录）。并非所有套餐都包含搜索：如果您的套餐不包含，菜单中没有商品搜索项，安装选项卡中不会显示代码区块，搜索请求会收到“功能不可用”错误。

如何搜索商品

• 查询词会在商品的名称、品牌、分类和规格中搜索；货号则按精确匹配。
• 支持项目语言的词形变化：“куртки”能找到“Куртка зимняя”。语言在项目设置中指定，参见项目设置、套餐与审计。
• 自动纠正错别字：“крутка”能找到“куртку”，“dres”能找到“dress”。
• 用错键盘布局输入的查询同样有效：“ghbdtn”会按“привет”搜索。
• 如果没有同时包含所有词的结果，搜索会显示至少包含其中一个词的商品。
• 热门商品和有货商品排名更靠前。热度取自推荐，每天更新一次。
• 靠前的结果会按访客的兴趣重新排序：访客浏览和购买过的分类与品牌中的商品会排得更高。
• 如果店铺行业支持，查询中的尺寸和参数（“205/55 r16”“5x112”“冬季”）会变成筛选条件。
• 文本中的价格、品牌和特征取值会变成筛选条件，参见理解查询。
• 描述性查询也会按含义找到商品，参见语义搜索。
• 针对该查询更常被选择和购买的商品排名更靠前，参见基于行为的学习。

目录中新增和修改的商品会在上传商品源或发出 API 请求后一分钟内进入搜索。

纠正错别字

如果某个查询没有找到任何结果，或只按部分词找到了商品，搜索会根据您目录的词典纠正查询中的词并再次搜索。词典包括目录所有语言的商品名称、品牌、分类以及网站的热门搜索。按纠正后的查询得到的结果会标注“已显示‘…’的搜索结果。”，并附带“仍然搜索‘…’”链接，以便按原样搜索输入的内容。如果只按部分词语找到商品，纠正会以提示“您是不是要找‘…’？”的形式给出。按全部词语或按语义找到的结果不会显示该提示：目录中没有的词不一定是拼写错误。

词典会在目录变更后自动更新。在输入时的联想提示中，如果按输入内容找不到商品，纠正后的查询也会显示为一行。

理解查询

搜索会识别查询文本中访客通常通过筛选来选择的内容，并立即应用：

带计量单位的数字（“до 3 лет”“до 5 кг”）不会被视为价格。识别出的内容会在结果中显示为已选的筛选条件：访客能看到结果为何被筛选，并可以取消该筛选，此后文本中的这一特征将不再被识别。如果应用识别出的筛选后没有任何结果，搜索会按普通文本重新进行。

语义搜索

描述性查询（如“适合山地跑步的鞋”“送妈妈什么礼物”“防雨”）可能不包含商品名称中的任何一个词。对于这类查询，搜索还会查找含义相近的商品：OneTrace.pro 为每个商品保存一份语义描述，内容来自目录所有语言的商品名称和分类、品牌以及特征。

• 语义搜索适用于三个词及以上的查询，以及按词没有找到结果或只找到部分结果的查询。能按词找到结果的短查询照常搜索。
• 同时按词和按含义找到的商品排名更靠前。
• 如果目录中有商品名称的翻译，其他语言的查询也能按含义找到商品。
• 与店铺商品无关的查询（例如服装店中的“汽车保险”）通常不会按含义得到结果。
• 语义搜索在按相关性排序时生效。

语义描述只针对有变更的商品重新计算，通常在目录上传后一分钟内完成。

基于行为的学习

搜索每天一次根据网站 90 天内的事件进行学习：对于至少有 5 位不同访客搜索过的每个查询，找出在结果中至少被两人点击过的商品；点击后购买商品的权重相当于三次点击。这些商品会在该查询的结果开头排得更高——仅限已找到的商品，且仅在按相关性排序时生效。

在网站 → 商品搜索页面的报告中，已学习的搜索词指标表示有多少个查询的排序已参考了访客行为，表格中这些查询带有“已学习”标记。

搜索小组件

搜索小组件是由追踪器显示的现成联想提示和结果页。在网站 → 商品搜索页面的搜索小组件区块中启用：勾选在网站上显示搜索浮层并保存。

搜索浮层。 点击搜索框时，下方会打开一个浮层：访客最近的搜索、当前热门以及为访客推荐的商品。输入时显示搜索建议、分类、品牌、知识库中的网站页面，以及带图片和价格的商品。在手机上，浮层会全屏打开。浮层会连接带 data-cdp-search 属性的输入框以及**网站的其他搜索框（CSS 选择器）**中指定的输入框，例如您主题的搜索框，无需修改主题代码。

预览区块会用您目录中的商品显示真实的浮层和结果。

结果页。 在网站的搜索页上放置一个容器，追踪器会在其中显示带筛选、排序和滚动加载的结果：

<div data-cdp-search-results data-query-param="q"></div>

查询和筛选条件保存在页面地址中：可以分享带结果的链接，“返回”会恢复之前的选择。data-query-param 是地址中的查询参数（默认为 q），data-per-page 是每页商品数（最多 48），data-cart-url 是购物车地址（如果与设置中的不同）。如果网站既没有结果页也没有搜索表单，结果会以覆盖在页面上的窗口打开。

“加入购物车”按钮。 按钮会向您网站的购物车地址发送带数量 quantity 的 POST 请求，并等待 JSON 响应：{"ok": true} 表示商品已加入，按钮显示“已加入”；{"ok": false, "redirect": "…"} 表示需要为商品选择规格，此时打开指定的页面。加入后，追踪器会通过 cdp:add-to-cart 事件通知网站，主题可据此更新迷你购物车。购物车地址必须位于网站的域名下：其他网站的购物车无法识别顾客。

网店插件。 在 WooCommerce、Magento 2 插件和 1C-Bitrix 模块中启用搜索小组件设置后，商店的搜索页将显示小组件的结果，“加入购物车”按钮会把商品加入商店的购物车。只要此处的小组件处于关闭状态，商店就会显示其自带的搜索页。

搜索框

不使用小组件时，可以通过 data-cdp-search 属性为您网站的搜索字段启用联想提示：

<form action="/search">
  <input name="q" data-cdp-search data-category-url="/catalog/{id}">
</form>

输入时，字段下方会出现联想提示：网站的热门搜索、匹配的分类，以及带图片和价格的商品。可以用方向键浏览，Enter 打开所选行，Esc 关闭提示。未选择任何行时按 Enter，会照常提交网站表单。

联想提示使用网站的字体，不含界面文字，因此适用于任何语言的网站。

结果页

现成的网店插件会自动将结果填入商店的搜索页。在您自己的网站上，请通过追踪器获取商品：

window.addEventListener('load', async () => {
  const q = new URLSearchParams(location.search).get('q');
  const result = await cdp.search(q, { perPage: 24 });
  // result.items — 商品，result.total — 找到的数量，result.facets — 用于筛选的分类、品牌、价格和特征
});

参数：category、brand、priceMin、priceMax、sort（relevance、popular、price_asc、price_desc）、page、perPage、attributes。点击商品时，请调用 cdp.searchResultClicked(商品)。

特征筛选。 result.facets.attributes 中是店铺行业的特征，带有访客语言的名称以及每个取值对应的商品数量，例如“轮辋直径（英寸）”：16、17、18。将所选取值传入 attributes：cdp.search(q, { attributes: { rim_diameter: [17, 18], season: 'winter' } })。同一特征的多个取值按“或”组合，不同特征之间按“且”组合。result.filters 中是从查询文本中识别出的尺寸和参数：请将它们展示给访客，让访客知道结果为何被筛选。需要追踪器 1.15.0。

如果该搜索词设置了重定向规则（参见搜索词规则），result.redirect 中为页面地址：请打开该页面，而不是显示结果。

响应中还包括：result.corrected——结果按纠正后的查询显示，result.suggestion——“您是不是要找”，result.filters——还包括从文本中识别出的价格（price_min、price_max）和品牌，result.learned——排序参考了访客行为，result.semantic——有按含义找到的商品。选项 correct: false——按原样搜索输入的内容，ignore: ['price']——不识别文本中的价格、品牌（brand）或特征。

服务器可以使用写入密钥发起相同的请求：https://cdp.onetrace.pro/api/v1/search 和 https://cdp.onetrace.pro/api/v1/search/suggest。完整的参数列表请参阅 API 参考：https://cdp.onetrace.pro/api/v1/openapi.json。

搜索词报告

网站 → 商品搜索页面显示访客在过去 7、30 或 90 天内在您的网站上搜索了什么：

• 搜索次数和访客——搜索了多少次、有多少不同的人搜索。
• 无结果——什么都没找到的搜索所占比例。
• 点击率——在自己搜索词的结果中点击了商品的访客比例。
• 购买和收入——在搜索结果中被点击、并由同一顾客在 7 天内购买的商品。收入按目录中的商品价格计算。在推荐设置中设置了购买事件时显示，参见推荐和商品目录。
• 已学习的搜索词——有多少个查询的结果排序参考了点击和购买，参见基于行为的学习。

图表下方的表格：

比较搜索词时忽略大小写和多余空格。您可以直接从表格行为搜索词添加同义词或规则。

同义词

同义词是一起搜索的词和短语：包含组内任一词的搜索也会按其他词查找商品。例如，有了“运动鞋, 球鞋, sneakers”这组同义词，搜索“白色球鞋”也会找到白色运动鞋。

• 双向组——每个词都按其他词搜索。
• 单向组——只有第一个词按其他词搜索：“苹果手机 → iphone”在搜索“苹果手机”时会找到 iPhone，但搜索“iphone”不会按“苹果手机”查找。

只有当组内的词或短语在搜索词中完整出现时才会被替换。同义词保存后立即生效，适用于搜索结果和建议。每个项目最多 500 组，每组最多 20 个词。

搜索词规则

当访客搜索的正是该搜索词（忽略大小写、多余空格和首尾标点）时，规则生效，并执行以下一项或两项操作：

• 置顶商品——最多 24 个商品按您设定的顺序显示在结果顶部，即使搜索本身找不到它们。其他结果紧随其后，不会重复。置顶在按相关性排序且未筛选时生效；缺货商品不显示。
• 重定向——打开您网站的某个页面，而不是显示结果，例如“配送” → 配送条款页面。

重定向由跟踪器的搜索框（对有规则的搜索词按 Enter）、您自己结果页面上的 cdp.search()（redirect 字段）以及 WooCommerce 和 Magento 2 插件执行。每个项目最多 1000 条规则。

请求限额

搜索请求（包括结果页和输入时的联想提示）计入套餐的每月限额。限额随套餐的档案量增长：“增长版”为档位内每个档案每月 20 次请求，“企业版”为 40 次；试用期内为 50,000 次请求。用量可在“套餐与付款”部分查看，参见套餐与付款。

用量达到限额的 90% 和 100% 时，项目所有者会收到邮件。超出限额后的 10% 内搜索仍可使用，之后直到下个月初都不可用：小组件不再接管网站的搜索框，并在结果中提示搜索不可用，网店插件则立即显示商店自带的搜索。您自己的结果页会在 cdp.search() 中收到 unavailable 标记——请显示网站自己的搜索。

统计

追踪器会记录两个事件：

提示中的热门搜索由 30 天内的 search 事件汇总而成。这些事件可在客户的档案卡片中查看，也可在分群中使用，例如“搜索过但未购买”，参见分群。