Connect your website

L'API CMS permet à votre site web de récupérer et de rendre le contenu publié à partir de Profound CMS. Vous pouvez l'utiliser pour alimenter des pages de documentation, des pages marketing, des blogs, des centres d'aide ou toute autre expérience axée sur le contenu.

L'intégration type se compose de trois parties :

1. Configurer votre connexion au CMS
2. Récupérer le contenu publié
3. Afficher le contenu dans votre application

Configuration

Pour connecter votre application au CMS, fournissez l'URL de l'API CMS, l'ID du site web et la clé API.

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

Utilisez des variables d'environnement pour les valeurs qui changent selon les environnements :

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

N'exposez pas les clés API privées dans le code côté client. Les clés API doivent être utilisées sur votre serveur, dans votre processus de build ou dans vos routes backend.

Récupérer du contenu

Le contenu dans le CMS est organisé par schéma. Par exemple, votre projet peut avoir des schémas tels que post, category, page ou section.

Utilisez le nom du schéma pour récupérer du contenu :

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

Pour récupérer un document unique par ID :

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

Pour récupérer du contenu localisé, demandez la version traduite du schéma :

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

Afficher les routes

Pour les sites web qui utilisent des pages gérées par le CMS, vous pouvez récupérer du contenu en fonction du chemin d'URL actuel.

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

La réponse de la route identifie la page et les blocs à afficher. Votre application peut ensuite récupérer les blocs et les afficher avec vos propres composants.

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

Exemple : afficher une page de documentation

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

Vous pouvez utiliser les blocs renvoyés pour afficher la page avec le système de composants de votre application.

Mise en cache

Le contenu publié du CMS peut être mis en cache en toute sécurité. Pour la plupart des sites web, mettez en cache les réponses de l'API pendant une courte période et revalidez-les lorsque le contenu change.

Une configuration courante est :

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

Comportement de cache recommandé :

• Mettre en cache les lectures publiées.
• Utiliser des fenêtres de cache plus courtes pour le contenu fréquemment mis à jour.
• Utiliser des balises de cache si votre framework prend en charge l'invalidation à la demande.
• Éviter de mettre en cache le contenu d'aperçu ou les brouillons.

Mode aperçu

Le mode aperçu permet aux éditeurs de voir les modifications non publiées avant leur publication.

Une pratique courante consiste à utiliser une route d'aperçu distincte, par exemple :

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

Les pages de production doivent récupérer uniquement le contenu publié. Les pages d'aperçu peuvent accepter des paramètres d'aperçu, par exemple :

?edit_mode=true

Les routes d'aperçu devraient généralement être dynamiques et ne pas être mises en cache de manière statique.

Gestion des erreurs

Le contenu du CMS peut être indisponible pendant une compilation ou une requête. Votre application doit gérer cette situation élégamment.

Comportements recommandés :

• Retournez 404 lorsqu'une route n'existe pas.
• Retournez une liste vide lorsque le contenu de navigation facultatif ne peut pas être chargé.
• Consignez les erreurs de récupération côté serveur.
• Évitez d'exposer les erreurs internes de l'API aux visiteurs.

Exemple :

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Échec de la récupération de l\'article CMS', error);
    return null;
  }
}

Sécurité

Gardez les clés API privées et utilisez-les uniquement sur le serveur. N'incluez pas d'identifiants privés dans les bundles du navigateur ou dans du JavaScript public.

Utilisez des variables d'environnement publiques uniquement pour des valeurs non sensibles telles que :

• URL publique du CMS
• ID du site web
• Configuration locale

Utilisez des variables d'environnement privées pour :

• clés API
• jetons d'aperçu
• identifiants administrateur
• secrets de déploiement

Résumé

Utilisez l'API CMS lorsque votre site web doit récupérer du contenu structuré, afficher des routes gérées par le CMS ou prendre en charge les workflows d'aperçu pour les éditeurs.

Une intégration standard devrait :

• Configurer l'URL du CMS, l'ID du site web et la clé API.
• Récupérer les documents par schéma.
• Récupérer les pages par chemin de route.
• Afficher les blocs CMS avec vos propres composants.
• Mettre en cache le contenu publié.
• Maintenir le contenu d'aperçu dynamique.
• Conserver les identifiants privés sur le serveur.