Connect your website

CMS-API'en gør det muligt for dit website at hente og gengive publiceret indhold fra Profound CMS. Du kan bruge den til at understøtte dokumentationssider, marketingsider, blogs, hjælpecentre eller enhver anden indholdsbaseret oplevelse.

Den typiske integration består af tre dele:

1. Konfigurer din CMS-forbindelse
2. Hent publiceret indhold
3. Gengiv indholdet i din applikation

Konfiguration

For at forbinde din applikation til CMS'et skal du angive din CMS-API-URL, website-id og API-nøgle.

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

Brug miljøvariabler til værdier, der ændrer sig mellem miljøer:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=dit-website-id
PROFOUND_API_KEY=din-api-nøgle

Eksponér ikke private API-nøgler i klientsidekode. API-nøgler bør bruges på din server, i din buildproces eller i dine backend-ruter.

Hent indhold

Indholdet i CMS'et er organiseret efter skema. For eksempel kan dit projekt have skemaer såsom post, category, page eller section.

Brug skemanavnet til at hente indhold:

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

For at hente et enkelt dokument via ID:

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

For at hente lokaliseret indhold skal du anmode om den oversatte version af skemaet:

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

Gengiv ruter

For websites, der bruger CMS-administrerede sider, kan du hente indhold baseret på den aktuelle URL-sti.

const route = await cms.route.getByPath({
  websiteId: 'dit-website-id',
  path: '/docs/kom-i-gang',
});

Rutesvaret identificerer siden og de blokke, der skal gengives. Din applikation kan derefter hente blokkene og gengive dem med dine egne komponenter.

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

Eksempel: Gengiv en dokumentationsside

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

Du kan bruge de returnerede blokke til at gengive siden ved hjælp af din applikations komponentsystem.

Cachelagring

Publiceret CMS-indhold er sikkert at cache. For de fleste websites bør du cache API-svar i en kort periode og revalidere dem, når indholdet ændrer sig.

En almindelig opsætning er:

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

Anbefalet cacheadfærd:

• Cache læsninger af publiceret indhold.
• Brug kortere cachevinduer til indhold, der opdateres ofte.
• Brug cache-tags, hvis dit framework understøtter invalidering efter behov.
• Undgå at cache forhåndsvisning eller kladdeindhold.

Forhåndsvisningstilstand

Forhåndsvisningstilstand lader redaktører se upublicerede ændringer, før de bliver publiceret.

Et almindeligt mønster er at bruge en separat forhåndsvisningsrute, for eksempel:

/docs/kom-i-gang
/cms-preview/docs/kom-i-gang

Produktionssider bør kun hente publiceret indhold. Forhåndsvisningssider kan acceptere forhåndsvisningsparametre såsom:

?edit_mode=true

Forhåndsvisningsruter bør som regel være dynamiske og bør ikke cachelagres statisk.

Fejlhåndtering

CMS-indhold kan være utilgængeligt under et build eller en forespørgsel. Din applikation bør håndtere dette elegant.

Anbefalet adfærd:

• Returner 404, når en rute ikke findes.
• Returner en tom liste, når valgfrit navigationsindhold ikke kan indlæses.
• Log serverside-fejl ved fetch.
• Undgå at eksponere interne API-fejl for besøgende.

Eksempel:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Det lykkedes ikke at hente CMS-indlæg', error);
    return null;
  }
}

Sikkerhed

Hold API-nøgler private, og brug dem kun på serveren. Medtag ikke private legitimationsoplysninger i browser-bundles eller offentligt JavaScript.

Brug kun offentlige miljøvariabler til ikke-følsomme værdier såsom:

• Offentlig CMS-URL
• Website-id
• Locale-konfiguration

Brug private miljøvariabler til:

• API-nøgler
• forhåndsvisningstokens
• administrative legitimationsoplysninger
• deploymentshemmeligheder

Resumé

Brug CMS-API'en, når dit website skal hente struktureret indhold, gengive CMS-administrerede ruter eller understøtte redaktørers forhåndsvisnings-workflows.

En standardintegration bør:

• Konfigurere CMS-URL'en, website-id'et og API-nøglen.
• Hente dokumenter efter skema.
• Hente sider efter rutesti.
• Gengive CMS-blokke med dine egne komponenter.
• Cache publiceret indhold.
• Holde forhåndsvisningsindhold dynamisk.
• Holde private legitimationsoplysninger på serveren.