Website mit der CMS-API verbinden

Die CMS-API ermöglicht es Ihrer Website, veröffentlichte Inhalte aus Profound CMS abzurufen und darzustellen. Sie können sie nutzen, um Dokumentationsseiten, Marketingseiten, Blogs, Helpcenter oder jede andere inhaltsorientierte Erfahrung zu betreiben.

Die typische Integration besteht aus drei Teilen:

1. Konfigurieren Sie Ihre CMS-Verbindung
2. Abrufen veröffentlichter Inhalte
3. Rendern Sie die Inhalte in Ihrer Anwendung

Konfiguration

Um Ihre Anwendung mit dem CMS zu verbinden, geben Sie Ihre CMS-API-URL, die Website-ID und den API-Schlüssel an.

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

Verwenden Sie Umgebungsvariablen für Werte, die sich zwischen Umgebungen ändern:

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

Geben Sie private API-Schlüssel nicht im Client-Code preis. API-Schlüssel sollten auf Ihrem Server, in Ihrem Build-Prozess oder in Ihren Backend-Routen verwendet werden.

Inhalte abrufen

Inhalte im CMS sind nach Schemas organisiert. Ihr Projekt kann beispielsweise Schemas wie post, category, page oder section haben.

Verwenden Sie den Schema-Namen, um Inhalte abzurufen:

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

So rufen Sie ein einzelnes Dokument anhand der ID ab:

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

Um lokalisierte Inhalte abzurufen, fordern Sie die übersetzte Version des Schemas an:

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

Routen rendern

Für Websites, die CMS-verwaltete Seiten verwenden, können Sie Inhalte anhand des aktuellen URL-Pfads abrufen.

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

Die Routen-Antwort identifiziert die Seite und die zu rendernden Blöcke. Ihre Anwendung kann anschließend die Blöcke abrufen und mit den eigenen Komponenten rendern.

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

Beispiel: Eine Dokumentationsseite rendern

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

Sie können die zurückgegebenen Blöcke verwenden, um die Seite mit dem Komponenten-System Ihrer Anwendung zu rendern.

Caching

Veröffentlichte CMS-Inhalte können bedenkenlos zwischengespeichert werden. Für die meisten Websites sollten Sie API-Antworten für einen kurzen Zeitraum cachen und sie erneut validieren, wenn sich Inhalte ändern.

Eine gängige Konfiguration ist:

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

Empfohlenes Cache-Verhalten:

• Veröffentlichte Lesezugriffe zwischenspeichern.
• Kürzere Cache-Zeiträume für häufig aktualisierte Inhalte verwenden.
• Cache-Tags verwenden, sofern Ihr Framework On-Demand-Invalidierungen unterstützt.
• Vorschau- oder Entwurfsinhalte nicht zwischenspeichern.

Vorschaumodus

Der Vorschaumodus ermöglicht es Redakteuren, unveröffentlichte Änderungen vor der Veröffentlichung zu sehen.

Ein gängiges Muster ist die Verwendung einer separaten Vorschaustrecke, zum Beispiel:

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

Produktionsseiten sollten nur veröffentlichte Inhalte abrufen. Vorschauseiten können Vorschauparameter akzeptieren, beispielsweise:

?edit_mode=true

Vorschaustrecken sollten in der Regel dynamisch sein und nicht statisch zwischengespeichert werden.

Fehlerbehandlung

CMS-Inhalte können während eines Builds oder einer Anfrage nicht verfügbar sein. Ihre Anwendung sollte damit elegant umgehen.

Empfohlene Vorgehensweise:

• Geben Sie 404 zurück, wenn eine Route nicht existiert.
• Geben Sie eine leere Liste zurück, wenn optionale Navigationselemente nicht geladen werden können.
• Protokollieren Sie serverseitige Abruf-Fehler.
• Vermeiden Sie es, interne API-Fehler gegenüber Besuchern offenzulegen.

Beispiel:

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

Sicherheit

Bewahren Sie API-Schlüssel privat auf und verwenden Sie sie nur auf dem Server. Fügen Sie keine privaten Zugangsdaten in Browser-Bundles oder öffentliches JavaScript ein.

Verwenden Sie öffentliche Umgebungsvariablen nur für nicht sensible Werte wie:

• Öffentliche CMS-URL
• Website-ID
• Locale-Konfiguration

Verwenden Sie private Umgebungsvariablen für:

• API-Schlüssel
• Vorschau-Tokens
• Administrator-Zugangsdaten
• Bereitstellungsgeheimnisse

Zusammenfassung

Verwenden Sie die CMS-API, wenn Ihre Website strukturierte Inhalte abrufen, CMS-verwaltete Routen rendern oder Vorschau-Workflows für Redakteure unterstützen muss.

Eine Standardintegration sollte:

• Die CMS-URL, die Website-ID und den API-Schlüssel konfigurieren.
• Dokumente nach Schema abrufen.
• Seiten anhand des Routenpfads abrufen.
• CMS-Blöcke mit den eigenen Komponenten rendern.
• Veröffentlichte Inhalte zwischenspeichern.
• Vorschauinhalte dynamisch halten.
• Private Zugangsdaten auf dem Server belassen.