Connect your website

API CMS позволяет вашему веб-сайту получать и отображать опубликованный контент из Profound CMS. Вы можете использовать его для работы страниц документации, маркетинговых страниц, блогов, справочных центров или любого другого опыта, основанного на контенте.

Типичная интеграция состоит из трех частей:

1. Настройте подключение к CMS
2. Получите опубликованный контент
3. Отобразите контент в своем приложении

Конфигурация

Чтобы подключить ваше приложение к CMS, укажите URL API CMS, идентификатор веб-сайта и ключ API.

const cmsConfig = {
  cmsUrl: 'https://cms.dev.tryprofoun.com',
  websiteId: 'your-website-id',
  apiKey: process.env.PROFOUND_API_KEY,
};

Используйте переменные окружения для значений, которые меняются между окружениями:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=your-website-id
PROFOUND_API_KEY=your-api-key

Не раскрывайте приватные ключи API в клиентском коде. Ключи API следует использовать на сервере, в процессе сборки или во внутренних маршрутах вашего бэкенда.

Получение контента

Контент в CMS организован по схемам. Например, в вашем проекте могут быть схемы post, category, page или section.

Используйте название схемы для получения контента:

const posts = await cms.schema('post').fetchAll();

Чтобы получить отдельный документ по идентификатору:

const post = await cms.schema('post').fetchSingleById('document-id');

Чтобы получить локализованный контент, запросите переведенную версию схемы:

const frenchPost = await cms
  .schema('post')
  .translation('fr')
  .fetchSingleById('document-id');

Отрисовка маршрутов

Для веб-сайтов, которые используют управляемые CMS страницы, вы можете получать контент на основе текущего пути URL.

const route = await cms.route.getByPath({
  websiteId: 'your-website-id',
  path: '/docs/getting-started',
});

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

const blocks = await cms.block.getByIds({
  websiteId: 'your-website-id',
  ids: route.blockIds,
});

Пример: отрисовка страницы документации

async function getDocsPage(path: string) {
  const route = await cms.route.getByPath({
    websiteId: process.env.WEBSITE_ID,
    path,
  });

  const blocks = await cms.block.getByIds({
    websiteId: process.env.WEBSITE_ID,
    ids: route.blockIds,
  });

  return {
    title: route.label,
    path: route.path,
    blocks,
  };
}

Вы можете использовать возвращенные блоки, чтобы отобразить страницу с помощью системы компонентов вашего приложения.

Кэширование

Опубликованный контент CMS можно безопасно кэшировать. Для большинства веб-сайтов кэшируйте ответы API на короткий период и повторно валидируйте их при изменении контента.

Распространенная настройка:

const content = await cache(
  () => cms.schema('post').fetchAll(),
  {
    revalidate: 60,
    tags: ['cms-posts'],
  }
);

Рекомендуемое поведение кэша:

• Кэшируйте опубликованные запросы на чтение.
• Используйте более короткие окна кэширования для часто обновляемого контента.
• Используйте теги кэша, если ваш фреймворк поддерживает инвалидизацию по требованию.
• Избегайте кэширования контента предпросмотра или черновиков.

Режим предпросмотра

Режим предпросмотра позволяет редакторам видеть неопубликованные изменения до их публикации.

Распространенный подход — использовать отдельный маршрут предпросмотра, например:

/docs/getting-started
/cms-preview/docs/getting-started

Производственные страницы должны получать только опубликованный контент. Страницы предпросмотра могут принимать параметры предпросмотра, например:

?edit_mode=true

Маршруты предпросмотра обычно должны быть динамическими и не должны кэшироваться статически.

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

Контент CMS может быть недоступен во время сборки или запроса. Ваше приложение должно обрабатывать это корректно.

Рекомендуемое поведение:

• Возвращайте 404, когда маршрут не существует.
• Возвращайте пустой список, если необязательный навигационный контент нельзя загрузить.
• Логируйте ошибки получения на стороне сервера.
• Избегайте раскрытия внутренних ошибок API посетителям.

Пример:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Failed to fetch CMS post', error);
    return null;
  }
}

Безопасность

Храните ключи API в секрете и используйте их только на сервере. Не включайте приватные учетные данные в браузерные бандлы или публичный JavaScript.

Используйте публичные переменные окружения только для несекретных значений, таких как:

• Публичный URL CMS
• Идентификатор веб-сайта
• Конфигурация локали

Используйте приватные переменные окружения для:

• Ключей API
• токенов предпросмотра
• учетных данных администратора
• секретов развертывания

Сводка

Используйте API CMS, когда вашему веб-сайту нужно получать структурированный контент, отображать маршруты, управляемые CMS, или поддерживать сценарии предпросмотра для редакторов.

Стандартная интеграция должна:

• Настроить URL CMS, идентификатор веб-сайта и ключ API.
• Получать документы по схеме.
• Получать страницы по пути маршрута.
• Отображать блоки CMS с помощью собственных компонентов.
• Кэшировать опубликованный контент.
• Оставлять контент предпросмотра динамичным.
• Хранить приватные учетные данные на сервере.