Connect your website

API-ul CMS permite site-ului tău să preia și să redea conținut publicat din Profound CMS. Îl poți folosi pentru a alimenta pagini de documentație, pagini de marketing, bloguri, centre de asistență sau orice altă experiență bazată pe conținut.

Integrarea tipică are trei părți:

1. Configurează conexiunea CMS
2. Preia conținutul publicat
3. Redă conținutul în aplicația ta

Configurare

Pentru a conecta aplicația la CMS, furnizează URL-ul API-ului CMS, ID-ul site-ului și cheia API.

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

Folosește variabile de mediu pentru valorile care se schimbă între medii:

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

Nu expune cheile API private în codul rulat pe client. Cheile API ar trebui folosite pe server, în procesul de build sau în rutele backend.

Preluarea conținutului

Conținutul din CMS este organizat pe scheme. De exemplu, proiectul tău poate avea scheme precum post, category, page sau section.

Folosește numele schemei pentru a prelua conținut:

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

Pentru a prelua un singur document după ID:

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

Pentru a prelua conținut localizat, solicită versiunea tradusă a schemei:

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

Redarea rutelor

Pentru site-urile care folosesc pagini gestionate de CMS, poți prelua conținut în funcție de calea URL curentă.

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

Răspunsul rutei identifică pagina și blocurile de redat. Aplicația ta poate apoi să preia blocurile și să le redea cu propriile componente.

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

Exemplu: Redarea unei pagini de documentație

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

Poți folosi blocurile returnate pentru a reda pagina folosind sistemul de componente al aplicației tale.

Cache

Conținutul publicat în CMS poate fi memorat în siguranță în cache. Pentru majoritatea site-urilor, memorează în cache răspunsurile API pentru o perioadă scurtă și revalidează-le când se schimbă conținutul.

O configurare frecventă este:

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

Comportament recomandat pentru cache:

• Pune în cache lecturile publicate.
• Folosește ferestre de cache mai scurte pentru conținutul actualizat frecvent.
• Folosește etichete de cache dacă framework-ul tău acceptă invalidarea la cerere.
• Evită punerea în cache a conținutului de previzualizare sau a ciornelor.

Modul de previzualizare

Modul de previzualizare le permite editorilor să vadă modificările nepublicate înainte de publicare.

Un pattern des întâlnit este să folosești o rută separată pentru previzualizare, de exemplu:

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

Paginile din producție ar trebui să preia doar conținut publicat. Paginile de previzualizare pot accepta parametri de previzualizare, precum:

?edit_mode=true

Rutele de previzualizare ar trebui, de obicei, să fie dinamice și să nu fie memorate static în cache.

Gestionarea erorilor

Conținutul CMS poate fi indisponibil în timpul unui build sau al unei cereri. Aplicația ta ar trebui să gestioneze această situație elegant.

Comportament recomandat:

• Returnează 404 atunci când ruta nu există.
• Returnează o listă goală atunci când conținutul opțional de navigare nu poate fi încărcat.
• Înregistrează erorile de preluare de pe server.
• Evită expunerea erorilor interne ale API-ului către vizitatori.

Exemplu:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Nu s-a reușit preluarea postării CMS', error);
    return null;
  }
}

Securitate

Păstrează cheile API private și folosește-le doar pe server. Nu include credențiale private în bundle-urile pentru browser sau în JavaScript public.

Folosește variabile de mediu publice doar pentru valori nesensibile, precum:

• URL public al CMS-ului
• ID-ul site-ului
• Configurarea localizării

Folosește variabile de mediu private pentru:

• Chei API
• tokenuri de previzualizare
• credențiale de administrator
• secrete de deployment

Rezumat

Folosește API-ul CMS atunci când site-ul tău are nevoie să preia conținut structurat, să redea rute gestionate de CMS sau să susțină fluxurile de lucru de previzualizare pentru editori.

O integrare standard ar trebui să:

• Configureze URL-ul CMS, ID-ul site-ului și cheia API.
• Preia documente după schemă.
• Preia pagini după calea rutei.
• Redea blocurile CMS cu propriile componente.
• Pune în cache conținutul publicat.
• Păstreze conținutul de previzualizare dinamic.
• Păstreze credențialele private pe server.