Connect your website

CMS-API-en lar nettstedet ditt hente og gjengi publisert innhold fra Profound CMS. Du kan bruke den til å drive dokumentasjonssider, markedssider, blogger, hjelpesentre eller enhver annen innholdsbasert opplevelse.

En typisk integrasjon har tre deler:

1. Konfigurer CMS-tilkoblingen din
2. Hent publisert innhold
3. Gjengi innholdet i applikasjonen din

Konfigurasjon

For å koble applikasjonen din til CMS-et, oppgi CMS API-URL, nettsteds-ID og API-nøkkel.

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

Bruk miljøvariabler for verdier som endrer seg mellom miljøer:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=din-nettsteds-id
PROFOUND_API_KEY=din-api-nøkkel

Ikke eksponer private API-nøkler i klientkode. API-nøkler bør brukes på serveren din, i byggeprosessen din eller i backend-rutene dine.

Hent innhold

Innholdet i CMS-et er organisert etter skjema. For eksempel kan prosjektet ditt ha skjemaer som post, category, page eller section.

Bruk skjemanavnet for å hente innhold:

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

For å hente et enkelt dokument etter ID:

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

For å hente lokalisert innhold, forespør den oversatte versjonen av skjemaet:

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

Gjengi ruter

For nettsteder som bruker CMS-administrerte sider, kan du hente innhold basert på gjeldende URL-bane.

const route = await cms.route.getByPath({
  websiteId: 'din-nettsteds-id',
  path: '/docs/komme-i-gang',
});

Ruteresponsen identifiserer siden og blokkene som skal gjengis. Applikasjonen din kan deretter hente blokkene og gjengi dem med dine egne komponenter.

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

Eksempel: Gjengi en dokumentasjonsside

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 bruke de returnerte blokkene til å gjengi siden med applikasjonens eget komponentsystem.

Mellomlagring

Publisert CMS-innhold er trygt å mellomlagre. For de fleste nettsteder bør API-responser mellomlagres i en kort periode og revalideres når innholdet endrer seg.

Et vanlig oppsett er:

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

Anbefalt cache-atferd:

• Mellomlagre forespørsler for publisert innhold.
• Bruk kortere cache-vinduer for innhold som oppdateres ofte.
• Bruk cache-tagger hvis rammeverket ditt støtter invalidering på forespørsel.
• Unngå å mellomlagre forhåndsvisnings- eller kladdeinnhold.

Forhåndsvisningsmodus

Forhåndsvisningsmodus lar redaktører se upubliserte endringer før de publiseres.

Et vanlig mønster er å bruke en egen forhåndsvisningsrute, for eksempel:

/docs/komme-i-gang
/cms-preview/docs/komme-i-gang

Produksjonssider bør hente kun publisert innhold. Forhåndsvisningssider kan ta imot forhåndsvisningsparametere, slik som:

?edit_mode=true

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

Feilhåndtering

CMS-innhold kan være utilgjengelig under en bygging eller forespørsel. Applikasjonen din bør håndtere dette på en smidig måte.

Anbefalt oppførsel:

• Returner 404 når en rute ikke finnes.
• Returner en tom liste når valgfritt navigasjonsinnhold ikke kan lastes.
• Logg hente-feil på serversiden.
• Unngå å eksponere interne API-feil for besøkende.

Eksempel:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Kunne ikke hente CMS-innlegg', error);
    return null;
  }
}

Sikkerhet

Hold API-nøkler private og bruk dem bare på serveren. Ikke inkluder private legitimasjoner i nettleserbundler eller offentlig JavaScript.

Bruk offentlige miljøvariabler bare for ikke-sensitive verdier som:

• Offentlig CMS-URL
• Nettsteds-ID
• Lokaliseringskonfigurasjon

Bruk private miljøvariabler for:

• API-nøkler
• forhåndsvisningstokener
• administratorlegitimasjon
• distribusjonshemmeligheter

Sammendrag

Bruk CMS-API-et når nettstedet ditt trenger å hente strukturert innhold, gjengi CMS-administrerte ruter eller støtte redaktørenes forhåndsvisningsarbeidsflyter.

En standard integrasjon bør:

• Konfigurere CMS-URL, nettsteds-ID og API-nøkkel.
• Hente dokumenter etter skjema.
• Hente sider etter rutebane.
• Gjengi CMS-blokker med egne komponenter.
• Mellomlagre publisert innhold.
• Holde forhåndsvisningsinnholdet dynamisk.
• Holde private legitimasjoner på serveren.