Connect your website

CMS API:n avulla verkkosivustosi voi hakea ja renderöidä julkaistua sisältöä Profound CMS:stä. Voit käyttää sitä dokumentaatiosivujen, markkinointisivujen, blogien, ohjekeskusten tai minkä tahansa muun sisältövetoisen kokemuksen tukemiseen.

Tyypillisessä integraatiossa on kolme osaa:

1. Määritä CMS-yhteytesi
2. Hae julkaistu sisältö
3. Renderöi sisältö sovelluksessasi

Konfigurointi

Yhdistääksesi sovelluksesi CMS:ään, anna CMS API -URL-osoitteesi, verkkosivuston tunnus ja API-avain.

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

Käytä ympäristömuuttujia arvoille, jotka muuttuvat ympäristöjen välillä:

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

Älä paljasta yksityisiä API-avaimia asiakaspuolen koodissa. API-avaimia tulisi käyttää palvelimellasi, rakennusprosessissa tai taustapalvelun reiteillä.

Sisällön haku

CMS:n sisältö on järjestetty skeemoittain. Esimerkiksi hankkeessasi voi olla skeemoja kuten post, category, page tai section.

Käytä skeeman nimeä sisällön hakemiseen:

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

Hae yksittäinen dokumentti tunnuksen perusteella:

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

Paikallistetun sisällön hakemiseksi pyydä skeeman käännetty versio:

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

Reittien renderöinti

Verkkosivustoilla, jotka käyttävät CMS:n hallinnoimia sivuja, voit hakea sisältöä nykyisen URL-polun perusteella.

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

Reittivastaus tunnistaa sivun ja renderöitävät lohkot. Sovelluksesi voi sitten hakea lohkot ja renderöidä ne omilla komponenteillasi.

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

Esimerkki: Dokumentaatiosivun renderöinti

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

Voit käyttää palautettuja lohkoja renderöidäksesi sivun sovelluksesi komponenttijärjestelmällä.

Välimuisti

Julkaistun CMS-sisällön välimuistittaminen on turvallista. Useimmilla verkkosivustoilla API-vastaukset kannattaa välimuistittaa lyhyeksi ajaksi ja uudelleenvalidoida, kun sisältö muuttuu.

Yleinen asetus on:

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

Suositeltu välimuistin käyttö:

• Tallenna julkaistut haut välimuistiin.
• Käytä lyhyempiä välimuistiaikoja usein päivittyvälle sisällölle.
• Käytä välimuistitageja, jos kehys tukee tarpeen mukaista mitätöintiä.
• Vältä esikatselu- tai luonnossisällön välimuistittamista.

Esikatselutila

Esikatselutila antaa toimittajien nähdä julkaisemattomat muutokset ennen julkaisua.

Yleinen tapa on käyttää erillistä esikatselureittiä, esimerkiksi:

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

Produktion sivujen tulisi hakea vain julkaistua sisältöä. Esikatselusivut voivat hyväksyä esikatseluparametreja, kuten:

?edit_mode=true

Esikatselureittien tulisi yleensä olla dynaamisia eikä niitä tulisi välimuistittaa staattisesti.

Virheenkäsittely

CMS-sisältö ei välttämättä ole saatavilla rakennuksen tai pyynnön aikana. Sovelluksesi tulisi käsitellä tämä hallitusti.

Suositeltu toiminta:

• Palauta 404, kun reittiä ei ole olemassa.
• Palauta tyhjä lista, kun valinnaista navigaatiosisältöä ei voida ladata.
• Kirjaa palvelinpuolen hakujen virheet.
• Vältä sisäisten API-virheiden paljastamista kävijöille.

Esimerkki:

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

Tietoturva

Pidä API-avaimet yksityisinä ja käytä niitä vain palvelimella. Älä sisällytä yksityisiä tunnistetietoja selaimen bundleihin tai julkiseen JavaScriptiin.

Käytä julkisia ympäristömuuttujia vain ei-arkaluontoisille arvoille, kuten:

• CMS:n julkinen URL-osoite
• Verkkosivuston tunnus
• Kieliasetukset

Käytä yksityisiä ympäristömuuttujia seuraaville:

• API-avaimet
• esikatselutokenit
• ylläpitäjän tunnistetiedot
• käyttöönoton salaisuudet

Yhteenveto

Käytä CMS API:ta, kun verkkosivustosi tarvitsee hakea rakenteista sisältöä, renderöidä CMS:n hallinnoimia reittejä tai tukea toimittajan esikatseluprosesseja.

Tavanomaisen integraation tulisi:

• Konfiguroida CMS-URL, verkkosivuston tunnus ja API-avain.
• Hakea dokumentit skeeman perusteella.
• Hakea sivut reittipolun perusteella.
• Renderöidä CMS-lohkot omilla komponenteillasi.
• Välimuistittaa julkaistu sisältö.
• Pitää esikatselusisällön dynaamisena.
• Pitää yksityiset tunnistetiedot palvelimella.