Connect your website

CMS-API:t gör att din webbplats kan hämta och rendera publicerat innehåll från Profound CMS. Du kan använda det för att driva dokumentationssidor, marknadssidor, bloggar, hjälpcenter eller andra innehållsdrivna upplevelser.

Den typiska integrationen består av tre delar:

1. Konfigurera din CMS-anslutning
2. Hämta publicerat innehåll
3. Rendera innehållet i din applikation

Konfiguration

För att ansluta din applikation till CMS:et anger du din CMS API-URL, webbplats-ID och API-nyckel.

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

Använd miljövariabler för värden som skiljer sig mellan miljöer:

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

Exponera inte privata API-nycklar i klientkod. API-nycklar ska användas på din server, i din byggprocess eller i dina backend-rutter.

Hämta innehåll

Innehållet i CMS:et är organiserat efter scheman. Till exempel kan ditt projekt ha scheman som post, category, page eller section.

Använd schemats namn för att hämta innehåll:

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

För att hämta ett enskilt dokument via ID:

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

För att hämta lokalt anpassat innehåll begär du den översatta versionen av schemat:

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

Rendera rutter

För webbplatser som använder CMS-hanterade sidor kan du hämta innehåll baserat på den aktuella URL-sökvägen.

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

Svaret från rutten identifierar sidan och blocken som ska renderas. Din applikation kan sedan hämta blocken och rendera dem med dina egna komponenter.

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

Exempel: Rendera en dokumentationssida

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 använda de returnerade blocken för att rendera sidan med din applikations komponentsystem.

Cachelagring

Publicerat CMS-innehåll är säkert att cachelagra. För de flesta webbplatser bör du cachelagra API-svar under en kort period och revalidera dem när innehållet ändras.

En vanlig uppsättning är:

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

Rekommenderat cachebeteende:

• Cachelagra publicerade läsningar.
• Använd kortare cachefönster för innehåll som uppdateras ofta.
• Använd cache-taggar om ditt ramverk stöder ogiltigförklaring på begäran.
• Undvik att cachelagra förhandsgranskat eller utkastinnehåll.

Förhandsgranskningsläge

Förhandsgranskningsläget låter redaktörer se opublicerade ändringar innan de publiceras.

Ett vanligt mönster är att använda en separat förhandsgranskningsrutt, till exempel:

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

Produktionssidor bör endast hämta publicerat innehåll. Förhandsgranskningssidor kan ta emot parametrar för förhandsgranskning, till exempel:

?edit_mode=true

Förhandsgranskningsrutter bör vanligtvis vara dynamiska och bör inte cachelagras statiskt.

Felhantering

CMS-innehåll kan vara otillgängligt under en byggprocess eller begäran. Din applikation bör hantera detta på ett smidigt sätt.

Rekommenderat beteende:

• Returnera 404 när en rutt inte finns.
• Returnera en tom lista när valfritt navigationsinnehåll inte kan laddas.
• Logga hämtfel på serversidan.
• Undvik att exponera interna API-fel för besökare.

Exempel:

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

Säkerhet

Håll API-nycklar privata och använd dem endast på servern. Inkludera inte privata autentiseringsuppgifter i webbläsarpaket eller offentlig JavaScript.

Använd offentliga miljövariabler endast för icke-känsliga värden såsom:

• CMS offentlig URL
• Webbplats-ID
• Lokaliseringskonfiguration

Använd privata miljövariabler för:

• API-nycklar
• förhandsgranskningstoken
• adminuppgifter
• distributionshemligheter

Sammanfattning

Använd CMS-API:t när din webbplats behöver hämta strukturerat innehåll, rendera CMS-hanterade rutter eller stödja redaktörers förhandsgranskningsarbetsflöden.

En standardintegration bör:

• Konfigurera CMS-URL, webbplats-ID och API-nyckel.
• Hämta dokument efter schema.
• Hämta sidor via ruttsökväg.
• Rendera CMS-block med dina egna komponenter.
• Cachelagra publicerat innehåll.
• Behåll förhandsgranskningsinnehållet dynamiskt.
• Behåll privata autentiseringsuppgifter på servern.