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

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

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

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

Требования

• Аккаунт Contentful с пространством (Space)
• Хотя бы одна модель контента (Content Model)
• Аккаунт на AACsearch и созданный индекс
• Ключ интеграции для Contentful (ss_connector_*)

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

В панели AACsearch:

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

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

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

1. Откройте ваше пространство (Space) в Contentful
2. Перейдите в Settings → Webhooks (в левом меню внизу)
3. Нажмите Add Webhook

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

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

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

Нажимайте Add Custom Header и добавьте два заголовка:

Заголовок 1:

• Name: Authorization
• Value: Bearer ss_connector_YOUR_KEY (замените на ваш ключ)

Заголовок 2:

• Name: X-Project-ID
• Value: YOUR_ORG_ID (скопируйте из панели AACsearch)

Шаг 5: Настройте события-триггеры

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

Основные события (обязательные)

• ✓ Entry → Publish — когда вы публикуете новую запись
• ✓ Entry → Unpublish — когда вы снимаете запись с публикации
• ✓ Entry → Delete — когда вы удаляете запись

Дополнительные события (опционально)

• ✓ Entry → Save — синхронизирует при каждом сохранении (даже неопубликованные записи)
• ✓ Asset → Publish — обновляет URL изображений

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

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

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

1. Нажмите Filters внизу
2. Выберите Content Type
3. Добавьте нужные типы

Пример: если у вас есть модели "Product", "BlogPost" и "Page", и вы хотите индексировать только товары:

• Выберите Product в фильтре

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

Нажмите Save / Создать. Contentful покажет уведомление о создании вебхука.

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

Способ 1: Тестовый запрос

В Contentful в списке вебхуков нажимайте на ваш вебхук и нажмите Send test event. Вы должны увидеть в истории 200 OK.

Способ 2: Опубликуйте запись

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

Если появилась — всё работает!

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

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

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

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

Сопоставление полей (опционально)

Если вам нужно дополнительное сопоставление полей (например, переименование), напишите на support@aacsearch.com с информацией о вашей модели контента.

Локализованный контент

Если ваш контент на нескольких языках (Contentful поддерживает локализацию):

• Вебхук будет отправлять все языковые версии
• Вы можете создать отдельный индекс для каждого языка (например, "products-ru", "products-en")
• Или создать один индекс и использовать фильтры для разделения по языку

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

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

1. В Contentful в Settings → Webhooks → ваш вебхук откройте Call attempts — какой статус?
   • ✅ 200 OK — вебхук работает, но может быть проблема с индексированием
   • ❌ 401/403 — проблема с заголовком Authorization или X-Project-ID
   • ❌ 404 — неправильный URL вебхука
2. В панели AACsearch → Поиск → Синхронизация видны попытки синхронизации?

Q: Я опубликовал запись, но её нет в поиске
A: После синхронизации запись встает в очередь на индексирование (1–2 минуты). Подождите и попробуйте поиск снова.

Q: Как исключить черновики из поиска?
A: Настройте вебхук только на события Publish (опубликовано), не включайте Save (сохранено).

Q: Я удалил запись в Contentful, но она всё ещё в поиске
A: Убедитесь, что в вебхуке включено событие Delete. Удалённые записи удаляются из поиска за 1–2 секунды.

Q: Можно ли синхронизировать черновики?
A: Да, включите событие Save в триггерах. Но это увеличит нагрузку на вебхуки.

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

После синхронизации встройте виджет на ваш фронтенд:

<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>

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

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

• Обзор коннекторов
• Документация по виджету
• Email: support@aacsearch.com
• Документация Contentful: https://www.contentful.com/developers/