Connect your website

CMS API ļauj jūsu tīmekļa vietnei iegūt un attēlot publicētu saturu no Profound CMS. To var izmantot, lai nodrošinātu dokumentācijas lapas, mārketinga lapas, emuārus, palīdzības centrus vai jebkuru citu uz saturu balstītu pieredzi.

Tipiska integrācija sastāv no trim daļām:

1. Konfigurējiet savu CMS savienojumu
2. Iegūstiet publicēto saturu
3. Attēlojiet saturu savā lietotnē

Konfigurācija

Lai savienotu savu lietotni ar CMS, norādiet CMS API URL, tīmekļa vietnes ID un API atslēgu.

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

Izmantojiet vides mainīgos vērtībām, kas mainās starp vidēm:

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

Neatklājiet privātās API atslēgas klienta puses kodā. API atslēgas jāizmanto jūsu serverī, būvēšanas procesā vai aizmugursistēmas maršrutos.

Satura iegūšana

Saturs CMS tiek organizēts pēc shēmām. Piemēram, jūsu projektā var būt shēmas, piemēram, post, category, page vai section.

Izmantojiet shēmas nosaukumu, lai iegūtu saturu:

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

Lai iegūtu vienu dokumentu pēc ID:

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

Lai iegūtu lokālizētu saturu, pieprasiet shēmas tulkoto versiju:

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

Maršrutu attēlošana

Tīmekļa vietnēm, kas izmanto CMS pārvaldītas lapas, varat iegūt saturu, pamatojoties uz pašreizējo URL ceļu.

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

Maršruta atbilde identificē lapu un blokos attēlojamos elementus. Pēc tam jūsu lietotne var iegūt šos blokus un attēlot tos ar jūsu komponentēm.

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

Piemērs: dokumentācijas lapas attēlošana

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

Varat izmantot atgrieztos blokus, lai attēlotu lapu, izmantojot savas lietotnes komponentu sistēmu.

Kešatmiņa

Publicētu CMS saturu ir droši kešot. Lielākajai daļai tīmekļa vietņu kešojiet API atbildes īsu laika periodu un pārvalidējiet tās, kad saturs mainās.

Ierasts iestatījums ir:

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

Ieteicamā kešatmiņas uzvedība:

• Kešojiet publicētus nolasījumus.
• Bieži atjauninātam saturam izmantojiet īsākus kešatmiņas logus.
• Izmantojiet kešatmiņas tagus, ja jūsu ietvars atbalsta invalidāciju pēc pieprasījuma.
• Izvairieties no priekšskatījumu vai melnrakstu satura kešošanas.

Priekšskatījuma režīms

Priekšskatījuma režīms ļauj redaktoriem redzēt nepublicētās izmaiņas pirms to publicēšanas.

Izplatīts paņēmiens ir izmantot atsevišķu priekšskatījuma maršrutu, piemēram:

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

Produkcijas lapām jāiegūst tikai publicēts saturs. Priekšskatījuma lapas var pieņemt priekšskatījuma parametrus, piemēram:

?edit_mode=true

Priekšskatījuma maršrutiem parasti jābūt dinamiskajiem, un tie nedrīkst tikt statiski kešoti.

Kļūdu apstrāde

CMS saturs būvēšanas vai pieprasījuma laikā var nebūt pieejams. Jūsu lietotnei tas jāapstrādā korekti.

Ieteicamā uzvedība:

• Atgrieziet 404, ja maršruts neeksistē.
• Atgrieziet tukšu sarakstu, ja nav iespējams ielādēt neobligāto navigācijas saturu.
• Reģistrējiet servera puses iegūšanas kļūdas.
• Izvairieties no iekšējo API kļūdu atklāšanas apmeklētājiem.

Piemērs:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Neizdevās iegūt CMS ierakstu', error);
    return null;
  }
}

Drošība

Glabājiet API atslēgas privātas un izmantojiet tās tikai serverī. Neiekļaujiet privātos akreditācijas datus pārlūkprogrammas paketēs vai publiskajā JavaScript.

Izmantojiet publiskos vides mainīgos tikai nesensitīvām vērtībām, piemēram:

• CMS publiskais URL
• Tīmekļa vietnes ID
• Lokalizācijas konfigurācija

Izmantojiet privātos vides mainīgos šādiem mērķiem:

• API atslēgas
• Priekšskatījuma marķieri
• Administratora akreditācijas dati
• Izvietošanas slepenie dati

Kopsavilkums

Izmantojiet CMS API, kad jūsu tīmekļa vietnei ir jāiegūst strukturēts saturs, jāattēlo CMS pārvaldīti maršruti vai jāatbalsta redaktoru priekšskatījuma darba plūsmas.

Standarta integrācijai vajadzētu:

• Konfigurēt CMS URL, tīmekļa vietnes ID un API atslēgu.
• Iegūt dokumentus pēc shēmas.
• Iegūt lapas pēc maršruta ceļa.
• Attēlot CMS blokus ar savām komponentēm.
• Kešot publicētu saturu.
• Saglabāt priekšskatījuma saturu dinamisku.
• Glabāt privātos akreditācijas datus serverī.