Интеграция корзины и избранного

🛒 Интеграция корзины с SearchBooster

Обзор

Для синхронизации корзины с виджетом SearchBooster необходимо реализовать набор глобальных функций, доступных через объект window.

Виджет использует эти функции для:

• получения состояния корзины;

• изменения количества товаров;

• синхронизации UI.

⚠️ Важное примечание для клиента

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

Контракты данных

type ProductId = string;

type CartItems = Record<ProductId, number>;

type OperationType = 'add' | 'inc' | 'dec' | 'removeAll';

type Offer = {
  id: ProductId;
  name?: string;
  price?: number;
  [key: string]: any;
};

type UpdateCartItemParams = {
  operationType: OperationType;
  currentQuantity: number;
} & Offer;

1. Получение содержимого корзины

Возвращает текущее состояние корзины.

window.getCartItems(): Promise<CartItems> | CartItems

Требования:

• ключ — id товара из фида SearchBooster;

• значение — количество товара (целое число ≥ 0);

• возвращать только товары с количеством > 0. Пример

window.getCartItems = async () => {
  return {
    '1234': 1,
    '5678': 2
  };
};

Когда вызывается:

• при инициализации виджета;

• при полном обновлении (UPDATE_CART);

• при синхронизации состояния.

2. Изменение количества товара

Вызывается при любом изменении количества товара.

window.updateCartItem(params: UpdateCartItemParams): Promise<number> | number

Параметры:

• operationType:

• add — первый клик "В корзину";

• inc — увеличение;

• dec — уменьшение;

• removeAll — удаление;

• currentQuantity — текущее количество;

• offer — объект товара.

Требования:

• функция должна вернуть финальное количество товара;

• значение должно быть ≥ 0.

Пример

window.updateCartItem = async ({ operationType, currentQuantity, ...offer }) => {
  const cart = window.yourCart || {};

  switch (operationType) {
    case 'add':
      cart[offer.id] = 1;
      break;

    case 'inc':
      cart[offer.id] = currentQuantity + 1;
      break;

    case 'dec':
      cart[offer.id] = Math.max(currentQuantity - 1, 0);
      break;

    case 'removeAll':
      delete cart[offer.id];
      break;
  }

  if (cart[offer.id] === 0) {
    delete cart[offer.id];
  }

  window.yourCart = cart;

  return cart[offer.id] || 0;
};

Обработка ошибок

Рекомендуется обрабатывать ошибки внутри функции и возвращать консистентное состояние:

try {
  // обновление корзины
} catch (e) {
  return currentQuantity;
}

3. Кастомизация кнопки (опционально)

Позволяет изменить поведение кнопки.

window.getAddToCartConfig(offer)

window.getAddToCartConfig = (offer) => {
  if (!offer.available) {
    return {
      label: 'Подробнее',
      action: () => {
        window.location.href = offer.url;
      }
    };
  }

  return undefined;
};

4. Переход в корзину (опционально)

Синхронизация состояния

window.goToCart = () => {
  window.location.href = '/cart';
};

Если корзина изменилась вне виджета:

Частичное обновление (рекомендуется):

if (window.sbEvents) {
  window.sbEvents.pushEvent('UPDATE_CART', {
    '123': 2,
    '777': 0
  });
}

Полное обновление

if (window.sbEvents) {
  window.sbEvents.pushEvent('UPDATE_CART');
}

Минимальная интеграция

window.getCartItems = async () => ({});
window.updateCartItem = async () => 0;

Поведение при отсутствии функций:

• если getCartItems не определена — корзина не отображается;

• если updateCartItem не определена — изменения невозможны.

Flow взаимодействия:

1. Пользователь нажимает «В корзину».

2. Виджет вызывает updateCartItem.

3. Функция обновляет состояние.

4. Возвращает новое количество.

5. Виджет обновляет UI.

❤️ Интеграция избранного с SearchBooster

Обзор

Виджет SearchBooster может отображать и управлять избранными товарами через глобальные функции.

⚠️ Важное примечание для клиента

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

Контракты данных

type ProductId = string;

type Favourites = Record<ProductId, boolean>;

type Offer = {
  id: ProductId;
  name?: string;
  price?: number;
  [key: string]: any;
};

1. Получение избранного

Возвращает текущее состояние избранного.

window.getFavourites(): Promise<Favourites> | Favourites

Требования:

• возвращать только товары в избранном (true);

• отсутствующие товары считаются false.

Пример:

window.getFavourites = async () => {
  return {
    '1234': true,
    '5678': true
  };
};

2. Изменение состояния избранного

Вызывается при клике на иконку избранного.

window.toggleFavourite({ isFavourite, ...offer }): Promise<boolean> | boolean

Параметры:

• isFavourite — желаемое состояние;

• offer — объект товара.

Требование: вернуть финальное состояние (true / false).

Пример

window.toggleFavourite = async ({ isFavourite, ...offer }) => {
  const favourites = window.yourFavourites || {};

  if (isFavourite) {
    favourites[offer.id] = true;
  } else {
    delete favourites[offer.id];
  }

  window.yourFavourites = favourites;

  return isFavourite;
};
//Синхронизация состояния
//Частичное обновление
if (window.sbEvents) {
  window.sbEvents.pushEvent('UPDATE_FAVOURITES', {
    '123': true,
    '777': false
  });
}

//Полное обновление
if (window.sbEvents) {
  window.sbEvents.pushEvent('UPDATE_FAVOURITES');
}

Важно:

• при partial update необходимо передавать все изменённые товары, включая удалённые (false);

• если второй параметр не передан — вызывается getFavourites.

Минимальная интеграция:

window.getFavourites = async () => ({});
window.toggleFavourite = async () => false;

Flow взаимодействия:

1. Пользователь нажимает на иконку избранного.

2. Виджет вызывает toggleFavourite.

3. Функция обновляет состояние.

4. Возвращает результат.

5. Виджет обновляет UI.