Connect your website

CMS-i API võimaldab teie veebisaidil Profound CMS-ist avaldatud sisu hankida ja renderdada. Saate seda kasutada dokumentatsioonilehtede, turunduslehtede, blogide, abikeskuste või mis tahes muu sisupõhise kogemuse toetamiseks.

Tüüpiline integratsioon koosneb kolmest osast:

1. Konfigureerige oma CMS-ühendus
2. Tooge avaldatud sisu
3. Renderdage sisu oma rakenduses

Konfigureerimine

Et ühendada oma rakendus CMS-iga, esitage CMS-i API URL, veebisaidi ID ja API-võti.

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

Kasutage keskkonnamuutujaid väärtuste jaoks, mis erinevad keskkondade vahel:

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

Ärge avaldage privaatseid API-võtmeid kliendipoolses koodis. API-võtmeid tuleks kasutada teie serveris, ehitusprotsessis või taustateenuse marsruutides.

Sisu toomine

CMS-is on sisu organiseeritud skeemide kaupa. Näiteks võib teie projektil olla skeeme nagu post, category, page või section.

Kasutage skeemi nime sisu toomiseks:

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

Üksiku dokumendi hankimiseks ID järgi:

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

Lokaliseeritud sisu toomiseks küsige skeemi tõlgitud versiooni:

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

Marsruutide renderdamine

Veebisaitidel, mis kasutavad CMS-i hallatavaid lehti, saate sisu tuua vastavalt praegusele URL-i teele.

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

Marsruudi vastus tuvastab lehe ja plokid, mida renderdada. Seejärel saab teie rakendus plokid tuua ja renderdada need teie enda komponentidega.

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

Näide: dokumentatsioonilehe renderdamine

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

Tagastatud plokke saate kasutada lehe renderdamiseks oma rakenduse komponentide süsteemi abil.

Puhverdamine

Avaldatud CMS-i sisu on ohutu vahemällu salvestada. Enamiku veebisaitide puhul salvestage API vastused lühikeseks ajaks vahemällu ja valideerige need uuesti, kui sisu muutub.

Levinud seadistus on:

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

Soovitatav vahemälu käitumine:

• Salvestage avaldatud päringute tulemused vahemällu.
• Kasutage sagedasti uueneva sisu jaoks lühemaid vahemälu aknaid.
• Kasutage vahemälu silte, kui teie raamistik toetab nõudmisel tühistamist.
• Vältige eelvaate või mustandi sisu vahemällu salvestamist.

Eelvaaterežiim

Eelvaaterežiim võimaldab toimetajatel näha avaldamata muudatusi enne nende avaldamist.

Levinud muster on kasutada eraldi eelvaate marsruuti, näiteks:

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

Tootmislehed peaksid tooma ainult avaldatud sisu. Eelvaatelehed võivad aktsepteerida eelvaate parameetreid, näiteks:

?edit_mode=true

Eelvaate marsruudid peaksid tavaliselt olema dünaamilised ja neid ei tohiks staatiliselt vahemällu salvestada.

Vigade käsitlemine

CMS-i sisu ei pruugi ehituse või päringu ajal saadaval olla. Teie rakendus peab sellega elegantselt toime tulema.

Soovitatav käitumine:

• Tagastage 404, kui marsruuti ei ole olemas.
• Tagastage tühi loend, kui valikulist navigeerimissisu ei saa laadida.
• Logige serveripoolsed hanketõrked.
• Vältige külastajatele sisemiste API-tõrgete avaldamist.

Näide:

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

Turvalisus

Hoidke API-võtmed privaatsena ja kasutage neid ainult serveris. Ärge lisage privaatseid mandaate brauseri pakkidesse ega avalikku JavaScripti.

Kasutage avalikke keskkonnamuutujaid ainult mittetundlike väärtuste jaoks, näiteks:

• CMS-i avalik URL
• Veebisaidi ID
• Lokaliseeringu seadistus

Kasutage privaatseid keskkonnamuutujaid järgmiseks:

• API-võtmed
• eelvaate tokenid
• administraatori mandaadid
• juurutuse saladused

Kokkuvõte

Kasutage CMS-i API-t, kui teie veebisait vajab struktureeritud sisu toomist, CMS-i hallatavate marsruutide renderdamist või toimetaja eelvaate töövoogude toetamist.

Standardne integratsioon peaks:

• Konfigureerima CMS-i URL-i, veebisaidi ID ja API-võtme.
• Tooma dokumente skeemi kaupa.
• Tooma lehti marsruudi tee järgi.
• Renderdama CMS-i plokke oma komponentidega.
• Salvestama avaldatud sisu vahemällu.
• Hoidma eelvaate sisu dünaamilisena.
• Hoidma privaatseid mandaate serveris.