Connect your website

Το API του CMS επιτρέπει στον ιστότοπό σας να ανακτά και να αποδίδει δημοσιευμένο περιεχόμενο από το Profound CMS. Μπορείτε να το χρησιμοποιήσετε για να υποστηρίξετε σελίδες τεκμηρίωσης, σελίδες μάρκετινγκ, ιστολόγια, κέντρα βοήθειας ή οποιαδήποτε άλλη εμπειρία με έμφαση στο περιεχόμενο.

Η συνήθης ενσωμάτωση έχει τρία τμήματα:

1. Διαμορφώστε τη σύνδεση του CMS σας
2. Ανακτήστε δημοσιευμένο περιεχόμενο
3. Αποδώστε το περιεχόμενο στην εφαρμογή σας

Διαμόρφωση

Για να συνδέσετε την εφαρμογή σας με το CMS, δώστε τη διεύθυνση URL του API του CMS, το αναγνωριστικό του ιστότοπου και το κλειδί API.

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

Χρησιμοποιήστε μεταβλητές περιβάλλοντος για τις τιμές που αλλάζουν μεταξύ περιβαλλόντων:

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

Μην αποκαλύπτετε ιδιωτικά κλειδιά API στον κώδικα που εκτελείται στην πλευρά του πελάτη. Τα κλειδιά API πρέπει να χρησιμοποιούνται στον διακομιστή σας, στη διαδικασία κατασκευής ή στις διαδρομές του backend.

Ανάκτηση Περιεχομένου

Το περιεχόμενο στο CMS οργανώνεται ανά σχήμα. Για παράδειγμα, το έργο σας μπορεί να έχει σχήματα όπως post, category, page ή section.

Χρησιμοποιήστε το όνομα του σχήματος για να ανακτήσετε περιεχόμενο:

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

Για να ανακτήσετε ένα μόνο έγγραφο με βάση το ID:

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

Για να ανακτήσετε τοπικοποιημένο περιεχόμενο, ζητήστε τη μεταφρασμένη έκδοση του σχήματος:

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

Απόδοση Διαδρομών

Για ιστότοπους που χρησιμοποιούν σελίδες διαχειριζόμενες από το CMS, μπορείτε να ανακτήσετε περιεχόμενο με βάση την τρέχουσα διαδρομή URL.

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

Η απόκριση της διαδρομής εντοπίζει τη σελίδα και τα blocks που πρέπει να αποδοθούν. Η εφαρμογή σας μπορεί στη συνέχεια να ανακτήσει τα blocks και να τα αποδώσει με τα δικά της components.

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

Παράδειγμα: Απόδοση Σελίδας Τεκμηρίωσης

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

Μπορείτε να χρησιμοποιήσετε τα blocks που επιστρέφονται για να αποδώσετε τη σελίδα χρησιμοποιώντας το σύστημα components της εφαρμογής σας.

Προσωρινή Αποθήκευση

Το δημοσιευμένο περιεχόμενο του CMS είναι ασφαλές για προσωρινή αποθήκευση. Για τους περισσότερους ιστότοπους, αποθηκεύστε προσωρινά τις αποκρίσεις του API για μικρό χρονικό διάστημα και επαληθεύστε τις εκ νέου όταν αλλάζει το περιεχόμενο.

Μια συνηθισμένη ρύθμιση είναι:

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

Προτεινόμενη συμπεριφορά cache:

• Κάντε cache τα δημοσιευμένα αιτήματα ανάγνωσης.
• Χρησιμοποιήστε μικρότερα χρονικά παράθυρα cache για περιεχόμενο που ενημερώνεται συχνά.
• Χρησιμοποιήστε ετικέτες cache εάν το framework σας υποστηρίζει άμεση ακύρωση.
• Αποφύγετε το cache περιεχομένου προεπισκόπησης ή προσχεδίου.

Λειτουργία Προεπισκόπησης

Η λειτουργία προεπισκόπησης επιτρέπει στους συντάκτες να δουν μη δημοσιευμένες αλλαγές πριν δημοσιευτούν.

Ένα συνηθισμένο μοτίβο είναι η χρήση ξεχωριστής διαδρομής προεπισκόπησης, για παράδειγμα:

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

Οι σελίδες παραγωγής πρέπει να ανακτούν μόνο δημοσιευμένο περιεχόμενο. Οι σελίδες προεπισκόπησης μπορούν να δέχονται παραμέτρους προεπισκόπησης, όπως:

?edit_mode=true

Οι διαδρομές προεπισκόπησης συνήθως πρέπει να είναι δυναμικές και να μην αποθηκεύονται στατικά.

Διαχείριση Σφαλμάτων

Το περιεχόμενο του CMS ενδέχεται να μην είναι διαθέσιμο κατά τη διάρκεια μιας κατασκευής ή ενός αιτήματος. Η εφαρμογή σας θα πρέπει να το χειρίζεται αυτό ομαλά.

Προτεινόμενη συμπεριφορά:

• Επιστρέψτε 404 όταν μια διαδρομή δεν υπάρχει.
• Επιστρέψτε μια κενή λίστα όταν δεν είναι δυνατή η φόρτωση προαιρετικού περιεχομένου πλοήγησης.
• Καταγράψτε τα σφάλματα ανάκτησης στην πλευρά του διακομιστή.
• Αποφύγετε την έκθεση εσωτερικών σφαλμάτων API στους επισκέπτες.

Παράδειγμα:

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

Ασφάλεια

Κρατήστε ιδιωτικά τα κλειδιά API και χρησιμοποιήστε τα μόνο στον διακομιστή. Μην συμπεριλαμβάνετε ιδιωτικά διαπιστευτήρια σε πακέτα JavaScript του προγράμματος περιήγησης ή σε δημόσιο JavaScript.

Χρησιμοποιήστε δημόσιες μεταβλητές περιβάλλοντος μόνο για μη ευαίσθητες τιμές όπως:

• Δημόσια διεύθυνση URL του CMS
• Αναγνωριστικό ιστότοπου
• Διαμόρφωση τοπικών ρυθμίσεων

Χρησιμοποιήστε ιδιωτικές μεταβλητές περιβάλλοντος για:

• Κλειδιά API
• Διακριτικά προεπισκόπησης
• Διαπιστευτήρια διαχειριστή
• Μυστικά ανάπτυξης

Περίληψη

Χρησιμοποιήστε το API του CMS όταν ο ιστότοπός σας χρειάζεται να ανακτήσει δομημένο περιεχόμενο, να αποδώσει διαδρομές που διαχειρίζεται το CMS ή να υποστηρίξει ροές εργασίας προεπισκόπησης για τους συντάκτες.

Μια τυπική ενσωμάτωση πρέπει να:

• Διαμορφώσει τη διεύθυνση URL του CMS, το αναγνωριστικό ιστότοπου και το κλειδί API.
• Ανακτήσει έγγραφα ανά σχήμα.
• Ανακτήσει σελίδες ανά διαδρομή.
• Αποδώσει τα blocks του CMS με τα δικά σας components.
• Κάνει cache το δημοσιευμένο περιεχόμενο.
• Διατηρεί το περιεχόμενο προεπισκόπησης δυναμικό.
• Διατηρεί τα ιδιωτικά διαπιστευτήρια στον διακομιστή.