Connect your website

Interfejs API CMS pozwala Twojej witrynie pobierać i renderować opublikowane treści z Profound CMS. Możesz go użyć do zasilania stron z dokumentacją, stron marketingowych, blogów, centrów pomocy lub dowolnych innych doświadczeń opartych na treści.

Typowa integracja składa się z trzech części:

1. Skonfiguruj połączenie z CMS-em
2. Pobierz opublikowane treści
3. Renderuj treści w swojej aplikacji

Konfiguracja

Aby połączyć aplikację z CMS-em, podaj adres URL interfejsu API CMS, identyfikator witryny i klucz API.

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

Używaj zmiennych środowiskowych dla wartości, które różnią się między środowiskami:

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

Nie ujawniaj prywatnych kluczy API w kodzie po stronie klienta. Klucze API powinny być używane na serwerze, w procesie budowania lub w trasach backendowych.

Pobieranie treści

Treści w CMS-ie są zorganizowane według schematów. Na przykład Twój projekt może mieć schematy takie jak post, category, page lub section.

Użyj nazwy schematu, aby pobrać treść:

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

Aby pobrać pojedynczy dokument według identyfikatora:

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

Aby pobrać treści zlokalizowane, poproś o przetłumaczoną wersję schematu:

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

Renderowanie tras

W witrynach, które korzystają ze stron zarządzanych przez CMS, możesz pobierać treści na podstawie bieżącej ścieżki URL.

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

Odpowiedź trasy identyfikuje stronę i bloki do renderowania. Twoja aplikacja może następnie pobrać bloki i wyrenderować je za pomocą własnych komponentów.

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

Przykład: renderowanie strony dokumentacji

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,
  };
}

Zwróconych bloków możesz użyć do wyrenderowania strony z wykorzystaniem systemu komponentów Twojej aplikacji.

Buforowanie

Opublikowane treści CMS można bezpiecznie buforować. W przypadku większości witryn buforuj odpowiedzi API przez krótki czas i przeprowadzaj ponowną walidację, gdy treść się zmienia.

Typowa konfiguracja wygląda następująco:

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

Zalecane zachowanie bufora:

• Buforuj opublikowane odczyty.
• Stosuj krótsze okna buforowania dla treści często aktualizowanych.
• Używaj tagów bufora, jeśli framework obsługuje unieważnianie na żądanie.
• Unikaj buforowania treści w trybie podglądu lub w wersjach roboczych.

Tryb podglądu

Tryb podglądu umożliwia edytorom zobaczenie nieopublikowanych zmian przed ich publikacją.

Powszechnym wzorcem jest użycie osobnej trasy podglądu, na przykład:

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

Strony produkcyjne powinny pobierać wyłącznie opublikowane treści. Strony podglądu mogą przyjmować parametry podglądu, takie jak:

?edit_mode=true

Trasy podglądu powinny zazwyczaj być dynamiczne i nie powinny być buforowane statycznie.

Obsługa błędów

Treści CMS mogą być niedostępne podczas budowania lub żądania. Twoja aplikacja powinna radzić sobie z tym w sposób kontrolowany.

Zalecane zachowanie:

• Zwracaj 404, gdy trasa nie istnieje.
• Zwracaj pustą listę, gdy nie można załadować opcjonalnej nawigacji.
• Loguj błędy pobierania po stronie serwera.
• Unikaj ujawniania odwiedzającym wewnętrznych błędów API.

Przykład:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Nie udało się pobrać wpisu CMS', error);
    return null;
  }
}

Bezpieczeństwo

Przechowuj klucze API w tajemnicy i używaj ich wyłącznie na serwerze. Nie umieszczaj prywatnych poświadczeń w pakietach przeglądarkowych ani publicznym JavaScripcie.

Używaj publicznych zmiennych środowiskowych wyłącznie dla niewrażliwych wartości, takich jak:

• Publiczny adres URL CMS
• Identyfikator witryny
• Konfiguracja lokalizacji

Używaj prywatnych zmiennych środowiskowych do:

• Kluczy API
• tokenów podglądu
• poświadczeń administratora
• sekretów wdrożeniowych

Podsumowanie

Korzystaj z interfejsu API CMS, gdy Twoja witryna musi pobierać ustrukturyzowane treści, renderować trasy zarządzane przez CMS lub wspierać przepływy pracy podglądu dla edytorów.

Standardowa integracja powinna:

• Skonfigurować adres URL CMS, identyfikator witryny i klucz API.
• Pobierać dokumenty według schematu.
• Pobierać strony według ścieżki trasy.
• Renderować bloki CMS przy użyciu własnych komponentów.
• Buforować opublikowaną treść.
• Utrzymywać treści podglądowe jako dynamiczne.
• Przechowywać prywatne poświadczenia na serwerze.