AnyQuery — Инструкция по компоновке глобального фида

📖

Что такое глобальный фид

Роль фида в работе AnyQuery

Партнёр передаёт нам ссылку, перейдя по которой мы можем скачать файл фида. После загрузки файла в систему скрипт разбирает его на составные части (парсит) и записывает / обновляет базу данных. Дальнейшая работа с информацией о каталоге клиента происходит при обращении именно к базе данных.

🔗

Общую информацию по формату YML можно посмотреть по ссылке: yandex.ru/support/marketplace/ru/assortment/auto/yml

⚙️

Специфические требования

Обязательные условия для корректной обработки фида

🚫Фид не должен быть заархивирован

🔓Фид не должен быть защищён паролем

📦Фид должен содержать все товары на сайте для показа в поиске и привязку их к категориям, соответствующую уровням вложенности на сайте

⏱️Фид должен быть статическим, либо полностью формироваться динамически в течение 3 минут после запроса

🔒Сертификат сервера не ниже A

🔗Важно передавать фид по прямой ссылке, без использования редиректа

🔤

Экранирование символов

Правила замены спецсимволов в XML-файле

1️⃣ Символы " & > < ', содержащиеся в значениях тегов, нужно заменять на эквивалентные XML-коды:

Символ в тексте	Код для XML-файла
"	"
&	&
>	>
<	<
'	'

2️⃣ Допустимые кодировки XML-файла: UTF-8, windows-1251

3️⃣ Допускается использование символов из пункта 1 в блоке CDATA

💡

Пример использования CDATA: <name><![CDATA[Кроссовки "Air" & стиль]]></name> — внутри блока CDATA спецсимволы экранировать не нужно.

🏷️

Описание тегов в фиде

Полный справочник тегов и атрибутов глобального YML-фида

Обязательный

Условно обязательный

Важный необязательный

Необязательный

Корневые теги

Тег / атрибут	Описание	Обязательность
<?xml version="1.0" encoding="utf-8"?>	Обязательный для XML-файла. Мы понимаем любую кодировку, главное чтобы кодировка была указана и формат текста с ней совпадал.	обязательный
yml_catalog, shop	Обязательны для YML-файла, без них фид не будет обновляться. Информацию после них и до тега `categories` мы не учитываем.	обязательные

Категории

Тег / атрибут	Описание	Обязательность
categories	Список категорий, без него фид не будет обновляться. Внутри этого тега находятся все категории сайта. Каждая категория описана внутри пары тегов `category`.	обязательный
category	Тег категории. Желательно чтобы в названиях категорий не было союза «и» и названий товаров, перечисленных через запятую. Логично разделять разные товары в разные категории. ВАЖНО: Если внутри тега не указать названия, то поиск будет вставлять вместо названия слово «undefined».	обязательный
category.id	Обязательный атрибут, номер категории в системе. Если его не будет или он будет пустой, будет считаться, что такой категории не существует.	обязательный
category.parentId	Обязательный атрибут для каждой подкатегории, содержит id родительской категории. У корневых категорий parentId не указывается или `parentId=0`. На примере: категория «Чаи» — общая и является родительской для категории «Зелёные чаи». ВАЖНО: Если указан parentId, то категория с таким id должна существовать в фиде, иначе возникнут ошибки при обработке. Если указан `parentId=0` и такой корневой категории нет в фиде, у неё тоже будет название «undefined».	обязательный для подкатегорий
category.url	Ссылка на категорию на сайте — нужна чтобы выводить кликабельные подсказки на категории. Лучший вариант — передавать её в фиде. Если атрибута нет, мы будем сами сопоставлять ссылки, используя один из подходов: • сопоставляем ID категории в фиде с ID категории на сайте. Чтобы не было ошибок, они должны совпадать; • сопоставляем иерархию структуры в фиде по значениям атрибутов parentId и хлебным крошкам на сайте. Чтобы не было ошибок, нужно чтобы структура фида полностью повторяла каталог на сайте.	необязательный

Товары (offer)

Тег / атрибут	Описание	Обязательность
offers	Список товаров. Внутри этого тега находятся все товары сайта.	обязательный
offer	Тег товара, без него фид не будет обновляться. Каждый товар описан внутри пары тегов `offer`, внутри него заключены все другие теги, описывающие товар.	обязательный
offer.id	Обязательный атрибут, без него фид не будет обновляться. Номер товара в системе — должен быть непустым и уникальным, может состоять как из букв, так и из цифр. Если у нескольких товаров id будет совпадать, из них в выдачу попадёт случайный товар. Аналогично, если у нескольких товаров пустой id, из них в выдачу попадёт случайный товар. Не должен содержать пробелов.	обязательный
offer.available	Обязательный атрибут, показывает наличие товара. Если атрибута не будет или он будет пустым — по умолчанию мы будем считать, что товар недоступен. Даже если наличие товара указано где-то ещё (например как отдельный тег), сервис смотрит только на атрибут тега `offer`.	обязательный
offer.group_id	Опциональный атрибут, нужен если есть вариации товаров, может состоять как из букв, так и из цифр. Например, одинаковые штаны разных размеров или одинаковый тональный крем разных оттенков — цена и название одинаковые, но отличается какой-то атрибут. Подобные товары лучше группировать в фиде самостоятельно, указывая им одинаковый `group_id` — это лучший вариант, потому что тогда процесс контролируем.	необязательный
любые другие атрибуты	Можно передавать в фиде, но мы их никак не используем.	необязательные

Дополнительные теги товара

Тег / атрибут	Описание	Обязательность
name	Имя товара. Внутри этого тега заключено название товара, которое мы будем отображать в выдаче. Если тега нет или он пустой, то мы составляем название из содержимого тегов `typePrefix`, `vendor`, `model`. Если любого из тегов нет, то имя будет составлено из тех, что есть. Несмотря на это, тег условно относим к обязательным.	условно обязательный
url	Прямая ссылка на карточку этого товара.	необязательный
price	Цена товара, должна совпадать с фактической. Значение обязательно должно быть числовым, другие значения не допускаются (например, диапазоны — т.к. это строковые значения). Цена не может быть отрицательной. Если цена с копейками, то передавать важно через «.» — т.е. 79.50	обязательный
picture	Прямая ссылка на изображение с превью товара. Их может быть несколько, но мы будем использовать только первую. Рекомендуемый вес менее 100 кб (30–50 кб). Оптимально передавать картинку товара из превью категории. Серьёзно влияет на скорость работы виджета.	необязательный
categoryId	Показывает к какой категории относится товар; в этом теге всегда указывается только одна категория. Если товар относится к нескольким категориям, товару добавляется несколько тегов `categoryId`. Можно обернуть список из таких пар тегов в тег `categories` для улучшения читабельности, но это не обязательно — к офферу привяжутся все существующие значения `categoryId`. Также чем меньше товаров лежат более чем в одной категории — тем выше качество поиска.	обязательный
vendor	Бренд товара, используется для формирования фильтров по бренду и составления имени товара, если тег `name` пустой или отсутствует. Если нужны фильтры по бренду — обязателен. Также поисковый запрос, который полностью совпадает с содержимым этого тега, считается брендовым. Если запрос брендовый, можем включить автоматическую фильтрацию продуктов по бренду — отображать только продукты этого бренда.	условно обязательный
oldprice	Старая цена без учёта скидки. Нужен если на продукт акция или скидка (на сайте выглядит как перечёркнутая старая цена и т.п.)	необязательный
typePrefix	Тип товара, необязательный. Используется только для составления имени товара, если тег `name` пустой или отсутствует.	необязательный
model	Модель товара, необязательный. В этом теге клиенты могут передавать что угодно, не обязательно модель товара. Используется только для составления имени товара, если тег `name` пустой или отсутствует.	необязательный
description	Описание товара, которое клиент добавляет на свой сайт. Напрямую не используется в поиске, тексты из описания могут быть использованы для обучения модели выпрямителя. Для оптимизации размера фида оптимально удалить тег из фида.	необязательный
param (name)	Важный тег параметров товара, обязан содержать атрибут name. Мы используем эти параметры для поиска товаров по значениям параметров и для формирования фильтров. Количество параметров не ограничено. Их нужно брать из характеристик товаров на сайте и добавлять через `<param name="Название фильтра">Значение</param>`. Чем больше консистентных параметров, тем лучше. Если процент заполненности одного из параметров у товаров ниже 70% — передавать его не нужно. В том числе по значениям параметров возможен поиск. Для указания характеристики товара необходимо использовать конструкцию: `<param name="Глубина" unit="мм">800</param>` Важно передавать поля без массива в значениях, для примера с кейсом программы: `<param name="Программы">Режим Eco Mix 20</param>` `<param name="Программы">Быстрая 14'-30'-44'</param>`	необязательный (важный для поиска и фильтров)
vendorCode	Код товара / артикул. Аналогично, если нужно искать товар по артикулу, то его нужно передавать `<param name='Артикул'>746891</param>` или через `vendorcode`. Рекомендуем добавлять сокращённую версию артикула через `<param name='Артикул'>746</param>` при наличии в vendorcode или через декомпозицию `<param name='Артикул'>746891</param>` / `<param name='Артикул2'>746</param>` + также важно добавлять штрихкоды, код производителя и другие аналогичные SKU-атрибуты через `<param name='название'>значение</param>`	необязательный

📋

Пример качественного фида

Полный YML-файл с двумя товарами

yml / xml

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-09-23T14:37:38+03:00">
  <shop>
    <name>site</name>
    <company>site</company>
    <url>https://site.ru</url>
    <categories>
      <category id="1" url="https://site.ru/catalog/smartfon">Смартфоны</category>
      <category id="2" parentId="1" url="https://site.ru/catalog/samsung">Samsung</category>
      <category id="4" url="https://site.ru/catalog/charging">Зарядные устройства</category>
      <category id="5" parentId="4" url="https://site.ru/catalog/xiaomi charging">Xiaomi</category>
    </categories>
    <offers>
      <!-- ======= Товар 1: смартфон с group_id, ценой со скидкой ======= -->
      <offer id="100" available="true" group_id="100-1">  <!-- уникальный ID, статус наличия, groupId -->
        <name>Смартфон Galaxy S22</name>
        <url>https://site.ru/product/Galaxy S22</url>         <!-- ссылка на карточку товара -->
        <price>79000</price>                                         <!-- цена со скидкой -->
        <oldprice>120000</oldprice>                                 <!-- цена без скидки (перечёркнутая) -->
        <categoryId>2</categoryId>                                   <!-- привязка к категории -->
        <vendor>Samsung</vendor>                                     <!-- бренд -->
        <vendorCode>BKT000855</vendorCode>
        <picture>https://site.ru/image/123.jpg</picture>           <!-- ссылка на изображение -->
        <param name="Тип товара">Смартфон</param>                  <!-- доп. параметры для поиска, -->
        <param name="Страна">Китай</param>                           <!-- фильтров и карточки товара -->
        <param name="Количество памяти" unit="гб">256</param>
        <param name="Артикул">000855</param>
        <param name="Цвет">чёрный</param>
        <param name="Материал">пластик</param>
        <param name="Материал">алюминий</param>
      </offer>
      <!-- ======= Товар 2: зарядное устройство, привязка к нескольким категориям ======= -->
      <offer id="110" available="false">  <!-- товар недоступен -->
        <name>Зарядное устройство Xiaomi BPM206</name>
        <url>https://site.ru/product/Зарядное устройство Xiaomi</url>
        <price>1690</price>
        <categories>  <!-- привязка к нескольким категориям (только конечного уровня) -->
          <categoryId>4</categoryId>
          <categoryId>5</categoryId>
        </categories>
        <vendor>Xiaomi</vendor>
        <vendorCode>5458487</vendorCode>
        <picture>https://site.ru/product/Зарядное устройство Xiaomi.jpg</picture>
        <param name="Хит">да</param>
        <param name="Новинка">да</param>
        <param name="Тип подключения">type c</param>
        <param name="Материал">пластик</param>
        <param name="Страна">Китай</param>
        <param name="Артикул">545</param>
      </offer>
    </offers>
  </shop>
</yml_catalog>

Разбор качественного offer

Тег offer — имеет открывающий и закрывающий теги, уникальный ID (id), статус наличия (available) и необязательный group_id для группировки вариаций

name, url, price, oldprice, categoryId, vendor, vendorCode, picture — у товара есть цена со скидкой и без, привязка к категории, бренд, а также ссылки на карточку товара и изображение

param name — дополнительные параметры, которые можно использовать для настройки алгоритмов поиска и рекомендаций, фильтров и вывода в карточку товара

✅

Дополнительная проверка готового фида

Валидация перед отправкой

🔍

Мы настоятельно рекомендуем дополнительно проверять готовый фид в валидаторе перед отправкой: feedchecker.any-platform.ru

⚠️

Возможные ошибки

Типичные проблемы при компоновке фида

1

Не нужно добавлять товар во все элементы дерева категорий. Достаточно добавить его только к последнему элементу дерева и в offers в поле <categoryId></categoryId> его передать. Он будет доступен для всех его родителей через тег parentId. Например, если структура каталога: матрасы → ортопедические → беспружинные, то товар должен быть добавлен только в категорию «беспружинные».

2

Отсутствие в фиде всех числовых обозначений (код, артикул, штрих-код), которые присутствуют на сайте. При поиске по таким значениям искомые товары не попадут в выдачу.

3

Переданы не все товары каталога через offer.

4

Не переданы атрибуты у товаров.

5

Важно минимизировать количество пустых категорий в фиде и передавать только категории с товарами.