Connect your website

A CMS API lehetővé teszi, hogy a webhelyed lekérje és megjelenítse a Profound CMS-ben közzétett tartalmat. Használhatod dokumentációs oldalak, marketingoldalak, blogok, ügyfélszolgálati központok vagy bármilyen más tartalomközpontú élmény kiszolgálására.

A tipikus integráció három részből áll:

1. Állítsd be a CMS kapcsolatot
2. Kérd le a közzétett tartalmat
3. Jelenítsd meg a tartalmat az alkalmazásodban

Konfiguráció

Az alkalmazás CMS-hez való csatlakoztatásához add meg a CMS API URL-t, a webhelyazonosítót és az API-kulcsot.

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

Használj környezeti változókat a környezetenként változó értékekhez:

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

Ne tedd közzé a privát API-kulcsokat a kliensoldali kódban. Az API-kulcsokat használd a szerveren, a build folyamatban vagy a háttérrendszer útvonalaiban.

Tartalom lekérése

A CMS-ben a tartalom sémák szerint van szervezve. Például a projektedben lehetnek olyan sémák, mint a post, category, page vagy section.

Használd a sémanevet a tartalom lekéréséhez:

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

Egyetlen dokumentum lekéréséhez azonosító alapján:

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

Lokálisított tartalom lekéréséhez kérd le a séma fordított változatát:

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

Útvonalak megjelenítése

Azoknál a webhelyeknél, amelyek CMS által kezelt oldalakat használnak, a tartalmat az aktuális URL-útvonal alapján kérheted le.

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

Az útvonal válasza azonosítja az oldalt és a megjelenítendő blokkokat. Az alkalmazásod ezután lekérheti a blokkokat, és a saját komponenseiddel renderelheti őket.

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

Példa: Dokumentációs oldal megjelenítése

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

A visszaadott blokkokat felhasználhatod az oldal megjelenítéséhez az alkalmazásod komponens rendszerével.

Gyorsítótárazás

A közzétett CMS-tartalom biztonságosan gyorsítótárazható. A legtöbb webhely esetében érdemes az API-válaszokat rövid ideig cache-elni, és akkor újraérvényesíteni őket, amikor a tartalom megváltozik.

Gyakori beállítás:

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

Ajánlott gyorsítótárazási viselkedés:

• Gyorsítótárazd a közzétett lekérdezéseket.
• Használj rövidebb cache-ablakot a gyakran frissülő tartalmakhoz.
• Használj cache-címkéket, ha a keretrendszered támogatja az igény szerinti érvénytelenítést.
• Kerüld a preview vagy piszkozat tartalom cache-elését.

Előnézeti mód

Az előnézeti mód lehetővé teszi a szerkesztők számára, hogy a közzététel előtt megtekintsék a publikálatlan módosításokat.

Gyakori minta egy külön előnézeti útvonal használata, például:

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

A production oldalaknak csak a közzétett tartalmat kell lekérniük. Az előnézeti oldalak elfogadhatnak olyan előnézeti paramétereket, mint például:

?edit_mode=true

Az előnézeti útvonalaknak általában dinamikusnak kell lenniük, és nem szabad őket statikusan cache-elni.

Hibakezelés

Előfordulhat, hogy a CMS-tartalom nem érhető el a build vagy a kérés során. Az alkalmazásodnak ezt elegánsan kell kezelnie.

Ajánlott működés:

• Adj vissza 404-et, ha az útvonal nem létezik.
• Adj vissza üres listát, ha az opcionális navigációs tartalom nem tölthető be.
• Naplózd a szerveroldali lekérési hibákat.
• Kerüld a belső API-hibák felfedését a látogatók előtt.

Példa:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Nem sikerült lekérni a CMS-bejegyzést', error);
    return null;
  }
}

Biztonság

Tartsd privátan az API-kulcsokat, és csak a szerveren használd őket. Ne illeszd be a privát hitelesítő adatokat böngészős csomagokba vagy nyilvános JavaScriptbe.

Nyilvános környezeti változókat csak nem érzékeny értékekhez használj, például:

• CMS nyilvános URL
• Webhelyazonosító
• Területi beállítások

Privát környezeti változókat használj a következőkhöz:

• API-kulcsok
• előnézeti tokenek
• adminisztrátori hitelesítő adatok
• telepítési titkok

Összegzés

Használd a CMS API-t, amikor a webhelyednek strukturált tartalmat kell lekérnie, CMS által kezelt útvonalakat kell megjelenítenie, vagy szerkesztői előnézet munkafolyamatot kell támogatnia.

Egy szabványos integráció esetén érdemes:

• Beállítani a CMS URL-t, a webhelyazonosítót és az API-kulcsot.
• Dokumentumokat lekérni sémánként.
• Oldalakat lekérni útvonal alapján.
• A CMS blokkokat a saját komponenseiddel renderelni.
• Gyorsítótárazni a közzétett tartalmat.
• Dinamikusan tartani az előnézeti tartalmat.
• A privát hitelesítő adatokat a szerveren tartani.