Vercel

L’application Vercel de Contentful aide votre équipe à configurer et à maintenir facilement des environnements d’aperçu fonctionnels pour votre application Next.js hébergée sur Vercel et optimisée par Contentful.

Avec un peu de configuration initiale, vos créateurs de contenu pourront prévisualiser les modifications de contenu avant de les publier directement à partir de l’éditeur d’aperçu « côte à côte » de Contentful. Avec un peu plus d’efforts, votre équipe peut également mettre en œuvre le SDK d’aperçu en direct de Contentful, qui débloque un ensemble encore plus puissant de fonctionnalités d’aperçu telles que les mises à jour en direct et l’édition sur place.

• Une fois installée et configurée, l’application Vercel activera les aperçus de contenu dans l’éditeur d’aperçu côte à côte de Contentful pour tout type de contenu que vous spécifiez.

• L’application Vercel fournit également des URL d’aperçu partageables qui sont accessibles aux membres de votre équipe qui n’ont peut-être pas un accès direct à votre projet Vercel.

• L’application Vercel simplifie considérablement le processus de configuration et de maintenance des URL d’aperçu fonctionnelles compatibles avec les fonctionnalités d’aperçu de Contentful.

Pour configurer l’application Vercel, vous aurez besoin de :

• Un accès administrateur d’espace à l’espace Contentful où vous l’installez

• Un accès administrateur de projet au projet Vercel où votre application Next.js connectée à Contentful est déployée

• Un développeur de votre équipe pour vous aider à adapter votre application Next.js afin qu’elle fonctionne avec les fonctionnalités d’aperçu de Contentful

Remarque : ce guide suppose que vous avez déjà une application Next.js fonctionnelle, déployée sur Vercel et connectée à un espace Contentful. Si vous démarrez un projet à partir de zéro, vous pouvez consulter un guide de démarrage pour lancer rapidement un nouveau projet.

Avant que votre équipe puisse commencer à utiliser l’application Vercel, votre application Next.js devra être configurée pour prendre en charge le « mode brouillon ». Le mode brouillon est une fonctionnalité de Next.js qui permet à votre équipe de basculer entre l’affichage des pages de votre site en « mode production » (c’est-à-dire telles que vos utilisateurs finaux les verraient) et l’affichage des pages en « mode aperçu » (telles que vos créateurs de contenu souhaitent les voir lorsqu’ils modifient du contenu non publié).

Vous devrez soit être développeur, soit faire appel à un développeur pour votre projet afin d’apporter les modifications nécessaires à votre code source pour prendre en charge à la fois l’activation du mode brouillon et l’affichage du contenu en aperçu lorsque le mode brouillon est activé.

Bien que cette première étape ne soit pas anodine, Contentful fournit un guide du développeur ainsi que des outils de développement pour faciliter la mise en œuvre du mode brouillon dans votre projet. Ce guide abordera en profondeur les sujets importants suivants :

• Configuration d’un gestionnaire de routes pour activer le mode brouillon. Votre développeur devra installer un « gestionnaire de routes » que l’application Vercel utilisera pour activer en toute sécurité les fonctionnalités d’aperçu dans votre application lorsque votre équipe utilise l’outil d’aperçu de Contentful. Cette étape est obligatoire.

• Ajout de la prise en charge du mode brouillon dans votre application. Notre documentation pour les développeurs fournit des conseils de haut niveau à votre développeur sur la façon d’intégrer le mode brouillon dans les requêtes de l’API Contentful dans votre application, ainsi que sur la façon de mettre en œuvre les fonctionnalités d’aperçu en direct plus puissantes de Contentful, telles que l’édition sur place et les mises à jour en direct.

Remarque : votre équipe n’a pas besoin de mettre pleinement en œuvre toutes les fonctionnalités d’aperçu de Contentful pour utiliser l’application Vercel. Cependant, votre application doit prendre en charge les conseils du gestionnaire de routes donnés ci-dessus et doit mettre en œuvre au moins certaines des fonctionnalités d’aperçu de Contentful avant de passer à l’étape suivante.

L’application peut être installée via Contentful Marketplace ou dans votre espace Contentful.

Configurer l’accès à Vercel

Lors de la première étape du processus d’installation de l’application, vous devrez coller un « jeton d’accès Vercel » qui donne à l’application Vercel l’accès aux projets Vercel de votre équipe.

Pour obtenir un jeton d’accès Vercel à utiliser avec l’application :

• Suivez ces instructions de Vercel pour créer un jeton d’accès. Nommez le jeton comme vous le souhaitez.

• Important : vous devez choisir une équipe dans la liste des champs d’application sur le formulaire « Créer un jeton ». Si vous êtes membre de plusieurs équipes dans Vercel, choisissez celle qui contient le projet Vercel auquel vous essayez de vous connecter.

• Assurez-vous de spécifier « Aucune expiration », sinon vous devrez visiter la page de configuration de l’application et régénérer votre jeton régulièrement.

• Copiez la valeur du jeton et collez-la dans le champ « Jeton d’accès Vercel » de l’application Contentful.

Si vous avez réussi à créer et à coller un jeton d’accès Vercel valide, vous devriez voir une option pour choisir un projet.

Connexion à votre projet Vercel

Dans la liste déroulante « Projet », choisissez un projet Vercel auquel vous connecter. Il doit s’agir du projet auquel l’espace Contentful dans lequel vous installez l’application est connecté.

Ensuite, vous devrez spécifier la « route » dans votre projet qui est configurée pour activer le mode brouillon. (Vous devrez travailler avec votre développeur pour installer cette route, comme cela est décrit à l’étape 1 ci-dessus.)

Remarque : si plusieurs routes sont disponibles dans la liste déroulante et que vous ne savez pas laquelle choisir, parlez-en à votre équipe de développement. Si votre développeur a suivi nos conseils, la route correcte doit être nommée « api/enable-draft » ou quelque chose de similaire.

Maintenant que vous êtes connecté à votre projet Vercel, vous pouvez configurer des environnements d’aperçu pour les types de contenu spécifiques que vous souhaitez que vos éditeurs de contenu puissent prévisualiser.

L’application elle-même se chargera de fournir un domaine et d’autres éléments nécessaires au bon fonctionnement de votre environnement d’aperçu avec Contentful. Mais pour chaque type de contenu, vous devrez toujours spécifier le chemin où les entrées de contenu d’un type de contenu particulier sont visibles.

En général, le « chemin » est simplement une URL sur votre site Web où certains types de contenu peuvent être consultés. Mais comme les différentes entrées de contenu auront des URL distinctes, vous devez également fournir le « jeton » utilisé par votre application pour identifier une entrée de contenu spécifique à prévisualiser.

Vous trouverez un guide détaillé des « jetons » disponibles ici ou dans une référence contextuelle qui apparaît lorsque vous cliquez sur « Afficher les jetons » :

Quelques exemples illustrent comment cela pourrait fonctionner dans une application hypothétique :

• Votre projet héberge un blog où les articles de blog sont visibles dans une URL similaire à celui-ci : http://www.example.com/blog/un-article-de-blog-pour-aujourd-hui. La valeur « un-article-de-blog-pour-aujourd-hui » est présente dans un champ « slug » de votre type de contenu Article de blog. Pour le champ « chemin », vous devez mettre :/blog/{entry.fields.slug}

• Votre projet héberge une base de connaissances où les articles de connaissances sont visibles dans une URL similaire à celui-ci : http://www.example.com/help/questions/7yr4hfr17dfsasdf. La valeur « 7yr4hfr17dfsasdf » est l’ID Contentful de vos entrées de contenu d’article de connaissances. Pour le champ « chemin », vous devez mettre :/help/questions/{entry.sys.id}

Remarque : la construction d’un chemin d’aperçu fonctionnel nécessite une certaine connaissance de la structure des routes de votre application ainsi que des champs de Contentful que ces routes utilisent pour identifier des entrées de contenu spécifiques. Consultez votre équipe de développement si vous ne savez pas comment configurer un chemin d’aperçu fonctionnel.

Une fois que vous avez configuré avec succès les chemins d’aperçu pour les types de contenu, votre équipe de contenu peut commencer à profiter immédiatement des fonctionnalités d’aperçu disponibles dans l’éditeur d’aperçu côte à côte de Contentful.

Configurer l’aperçu du contenu

Normalement, votre équipe configurerait et gérerait les environnements d’aperçu du contenu en allant dans Paramètres > Aperçu du contenu. Bien que vous puissiez continuer à ajouter et à configurer des environnements d’aperçu supplémentaires, vous n’aurez pas besoin d’effectuer de configuration supplémentaire pour opérationnaliser les aperçus fournis par l’application Vercel.

Une fois l’application Vercel installée correctement, vous verrez une section sur les paramètres d’aperçu du contenu qui redirige vos utilisateurs vers la page de configuration de l’application où ils peuvent gérer les paramètres d’aperçu du contenu spécifiques à Vercel (décrits ci-dessus) :

Il y a quelques paramètres supplémentaires sur cette page qui restent pertinents :

• Vous devrez toujours spécifier le « Mode d’aperçu » pris en charge par votre application, soit « Aperçu en direct », soit « Aperçu dans un nouvel onglet »

• Les jetons d’aperçu personnalisés sont toujours configurés et gérés à partir de l’écran des paramètres d’aperçu du contenu. Tous les jetons personnalisés que vous définissez ici seront disponibles dans le champ du chemin d’aperçu, comme décrit dans la section ci-dessus.

Utilisation de l’aperçu du contenu

Vos utilisateurs peuvent déclencher le mode d’aperçu directement à partir de la barre latérale de l’entrée :

Si vous disposez de plusieurs environnements d’aperçu (comme dans l’image ci-dessus), l’environnement d’aperçu fourni par l’application Vercel sera étiqueté comme tel. Vos utilisateurs peuvent basculer entre les modes d’aperçu à l’aide du lien « modifier ».

Remarque : si l’application Vercel est le seul environnement que vous avez configuré pour un espace, vos utilisateurs ne verront pas les options « Plateforme » et « Modifier ».

Il se peut que des messages d’erreur particuliers apparaissent lors de la configuration de l’application Vercel. Vous trouverez ci-dessous quelques-unes des erreurs les plus courantes que vous pourriez rencontrer pour chaque étape de configuration et des suggestions sur la meilleure façon d’y remédier.

Authentification

• Jeton d’accès non valide. Le jeton peut ne pas être un jeton d’accès Vercel valide. Suivez nos instructions ci-dessus pour créer un jeton d’accès Vercel valide.

• Le jeton n’est pas limité à une équipe. Le jeton d’accès que vous avez créé dans Vercel n’est pas limité à une équipe spécifique, mais plutôt à l’ensemble du compte. Assurez-vous que lors de la création du jeton, vous sélectionnez une équipe spécifique pour la spécification intitulée Champ d’application.

• Le jeton a expiré. Le jeton d’accès que vous avez ajouté a expiré. Essayez de créer un nouveau jeton dans Vercel. Nous vous recommandons de créer un jeton sans date d’expiration.

Sélection du projet

• Le projet que vous avez configuré n’est plus disponible. Veuillez en sélectionner un autre. Le projet que vous aviez précédemment configuré n’est plus disponible dans la liste des projets Vercel disponibles, car il a probablement été supprimé dans Vercel. Essayez de sélectionner un autre projet.

• Il semble que vous ayez configuré une variable d’environnement, CONTENTFUL_SPACE_ID, dans le projet Vercel sélectionné qui ne correspond pas à l’ID actuel de l’espace, <space_id>, où cette application est installée. Assurez-vous que la variable d’environnement pointe vers le bon ID d’espace Contentful où l’application est installée. La variable d’environnement se trouve dans votre projet Vercel sous Paramètres > Variables d’environnement. (Notez que ce message est un avertissement. Il est possible que vos développeurs utilisent une autre méthode pour identifier l’espace où réside votre contenu Contentful. Si tout fonctionne correctement, vous pouvez ignorer cet avertissement en toute sécurité.)

• Le contournement de la protection n’est pas activé pour le projet que vous avez configuré. Veuillez l’activer. Assurez-vous que la Protection Bypass for Automation est activée pour le projet Vercel sélectionné. Ceci est essentiel pour que votre application se charge correctement dans la fenêtre d’aperçu côte à côte de Contentful. Ce paramètre se trouve dans votre projet Vercel sous Paramètres > Protection du déploiement ; faites défiler vers le bas jusqu’à la section Protection Bypass for Automation où vous pouvez ensuite activer le paramètre.

Sélection du gestionnaire de routes du mode brouillon

• La route que vous avez configurée n’est plus disponible. Veuillez en sélectionner une autre. La route que vous aviez précédemment sélectionnée pour activer le mode brouillon n’est plus disponible dans la liste des routes configurées associées à votre projet. Essayez de sélectionner une autre route dans la liste déroulante et parlez-en à votre équipe de développement si vous ne trouvez pas la route appropriée.

• Il semble que votre projet Vercel n’ait pas encore de routes configurées. L’erreur apparaîtra avec une entrée de texte pour prendre en charge la saisie manuelle de la route. Cela peut indiquer que votre application n’est pas encore configurée correctement (voir l’étape 1 ci-dessus pour obtenir des conseils sur ce qui est requis de votre équipe de développement pour prendre en charge l’application Vercel). Vous pouvez également confirmer que ces routes existent en consultant votre projet sur Vercel. Sous Déploiements, cliquez sur le dernier déploiement. Dans la section Détails du déploiement de votre dernier déploiement, cliquez sur Résumé du déploiement > Fonctions, où les routes doivent être répertoriées (par exemple, /api/enable-draft).

Sélection du type de contenu et du chemin d’aperçu

• Le champ est vide. Assurez-vous qu’il existe un chemin d’aperçu pour chaque type de contenu que vous avez configuré dans les paramètres d’aperçu.

• Le chemin doit commencer par un « / » et inclure un {token}. Assurez-vous que votre chemin d’aperçu commence par une barre oblique et inclut un jeton dynamique entre accolades, par exemple/blogs/{entry.fields.slug}. Consultez ce guide si vous avez des difficultés à déterminer comment construire un chemin d’aperçu qui fonctionne correctement avec la façon dont votre équipe utilise Contentful.