Sanity.io: синхронизация через вебхуки

Sanity.io синхронизируется с AACsearch через вебхуки. Когда вы публикуете контент в Sanity, он автоматически попадает в поиск за несколько секунд.

Как это работает

1. Вы публикуете документ в Sanity
2. Sanity отправляет уведомление на AACsearch
3. Документ добавляется в поиск (за 1–2 секунды)

Требования

• Аккаунт Sanity.io с проектом
• Определённые схемы документов (Schema)
• Аккаунт на AACsearch и созданный индекс
• Ключ интеграции для Sanity (ss_connector_*)

Шаг 1: Получите ключ интеграции

В панели AACsearch:

1. Перейдите в Поиск → Подключения
2. Нажмите Новое подключение
3. Выберите тип: Sanity.io
4. Скопируйте ключ (начинается с ss_connector_)

Также скопируйте ID организации из Настройки → API.

Шаг 2: Создайте вебхук в Sanity

1. Откройте manage.sanity.io
2. Откройте ваш проект
3. Перейдите в Settings → Webhooks
4. Нажмите Create Webhook

Шаг 3: Заполните параметры вебхука

На странице создания вебхука:

Шаг 4: Добавьте аутентификацию

В разделе Custom HTTP headers добавьте:

Замените YOUR_KEY и YOUR_ORG_ID на ваши значения из AACsearch.

Шаг 5: Выберите события

В разделе Trigger on выберите события, которые должны синхронизировать документы:

Основные события

• ✓ Create — когда создан новый документ
• ✓ Update — когда обновлён документ
• ✓ Delete — когда удалён документ

Для большинства случаев этих трёх событий достаточно.

Шаг 6: Фильтруйте по типам документов (рекомендуется)

Если вы хотите синхронизировать только определённые типы (например, только "product" и "blogPost", но не "author"):

В разделе Filter by document type добавьте нужные типы.

Пример: если у вас схемы "product", "blogPost", "author", и вы хотите индексировать только товары и статьи:

• Выберите product
• Выберите blogPost
• Исключите author

Шаг 7: Сохраните вебхук

Нажмите Create. Sanity создаст вебхук и покажет его в списке.

Шаг 8: Проверьте синхронизацию

Способ 1: История вебхука

1. В списке вебхуков нажимайте на ваш вебхук
2. Откроется Invocations (история запросов)
3. Вы должны увидеть успешные запросы (Status: 200)

Способ 2: Опубликуйте документ

1. Откройте документ в Sanity
2. Нажмите Publish (опубликовать)
3. В панели AACsearch → Поиск → Синхронизация проверьте, что документ появился

Если появился — синхронизация работает!

Синхронизация контента

Какие поля передаются?

Sanity отправляет в поиск:

• Идентификатор — уникальный ID документа
• Название — из поля title/name
• Описание — из полей description/content
• Категория / Теги — если есть в схеме
• Изображение — URL из поля image/featured_image
• Дата — дата публикации или создания
• Ссылка — URL на страницу документа

Сопоставление полей

Если у вас есть пользовательские поля в схеме, они также синхронизируются. Sanity автоматически определяет типы полей.

Если нужно специальное сопоставление, напишите на support@aacsearch.com с примером вашей схемы.

Черновики и версионирование

Синхронизировать только опубликованные документы?

Используйте фильтр Filter by document type, исключив документы в статусе "draft".

Или настройте события вебхука только на Update (обновление опубликованных документов), исключив Create (создание черновиков).

Синхронизировать черновики?

Включите все события (Create, Update, Delete), и вебхук будет отправлять даже черновики.

Встраивание виджета поиска

После синхронизации встройте виджет на ваш фронтенд (Next.js, React, Vue и т.д.):

<div id="aac-search"></div>
<script 
  src="https://app.aacsearch.com/api/widget/widget.js"
  data-base-url="https://app.aacsearch.com"
  data-api-key="ss_search_***"
  data-index-slug="products"
  data-container="#aac-search">
</script>

Или используйте NPM пакет:

npm install @aacsearch/react

import { AacsearchWidget } from '@aacsearch/react';

export default function SearchPage() {
  return (
    <AacsearchWidget
      baseUrl="https://app.aacsearch.com"
      apiKey="ss_search_***"
      indexSlug="products"
    />
  );
}

Подробнее о виджете

Часто задаваемые вопросы

Q: Вебхук создан, но документы не синхронизируются
A: Проверьте:

1. История вебхука в Sanity (Settings → Webhooks → ваш вебхук → Invocations)
   • ✅ 200 — вебхук работает
   • ❌ 401/403 — проблема с заголовками авторизации
   • ❌ 404 — неправильный URL
2. В панели AACsearch → Поиск → Синхронизация видны попытки?

Q: Я опубликовал документ, но его нет в поиске
A: Проверьте:

1. Событие Update включено в вебхуке?
2. Тип документа не исключён фильтром?
3. Подождите 1–2 минуты на индексирование

Q: Как синхронизировать только часть документов?
A: Используйте фильтр Filter by document type в вебхуке. Выберите только те типы, которые нужны.

Q: Документ удалён в Sanity, но всё ещё в поиске
A: Убедитесь, что событие Delete включено в вебхуке.

Q: Можно ли синхронизировать несколько датасетов (production, staging)?
A: Да, создайте отдельный вебхук для каждого датасета и укажите разные индексы AACsearch.

Помощь и поддержка

• Обзор коннекторов
• Документация по виджету
• Email: support@aacsearch.com
• Документация Sanity: https://www.sanity.io/docs/webhooks