Connect your website

L'API del CMS consente al tuo sito web di recuperare e renderizzare i contenuti pubblicati da Profound CMS. Puoi usarla per alimentare pagine di documentazione, pagine di marketing, blog, help center o qualsiasi altra esperienza basata sui contenuti.

L'integrazione tipica comprende tre parti:

1. Configura la connessione al tuo CMS
2. Recupera i contenuti pubblicati
3. Renderizza i contenuti nella tua applicazione

Configurazione

Per collegare la tua applicazione al CMS, fornisci l'URL dell'API del CMS, l'ID del sito web e la chiave API.

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

Utilizza variabili di ambiente per i valori che cambiano tra gli ambienti:

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

Non esporre le chiavi API private nel codice lato client. Le chiavi API dovrebbero essere usate sul tuo server, nel processo di build o nelle tue rotte backend.

Recupero dei contenuti

I contenuti nel CMS sono organizzati per schema. Ad esempio, il tuo progetto può avere schemi come post, category, page o section.

Utilizza il nome dello schema per recuperare i contenuti:

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

Per recuperare un singolo documento in base all'ID:

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

Per recuperare contenuti localizzati, richiedi la versione tradotta dello schema:

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

Rendering delle route

Per i siti web che utilizzano pagine gestite dal CMS, puoi recuperare i contenuti in base al percorso URL corrente.

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

La risposta della route identifica la pagina e i blocchi da renderizzare. La tua applicazione può quindi recuperare i blocchi e renderizzarli con i propri componenti.

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

Esempio: rendering di una pagina di documentazione

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

Puoi utilizzare i blocchi restituiti per renderizzare la pagina usando il sistema di componenti della tua applicazione.

Cache

I contenuti pubblicati del CMS possono essere memorizzati nella cache in modo sicuro. Per la maggior parte dei siti web, metti in cache le risposte dell'API per un breve periodo e rivalidale quando i contenuti cambiano.

Una configurazione comune è:

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

Comportamento di cache consigliato:

• Memorizza nella cache le letture dei contenuti pubblicati.
• Utilizza finestre di cache più brevi per i contenuti aggiornati di frequente.
• Usa i tag di cache se il tuo framework supporta l'invalidazione on-demand.
• Evita di mettere in cache contenuti in anteprima o in bozza.

Modalità anteprima

La modalità anteprima consente agli editor di visualizzare le modifiche non pubblicate prima della loro pubblicazione.

Uno schema comune consiste nell'utilizzare una route di anteprima separata, ad esempio:

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

Le pagine di produzione dovrebbero recuperare solo contenuti pubblicati. Le pagine di anteprima possono accettare parametri di anteprima, ad esempio:

?edit_mode=true

Le route di anteprima dovrebbero solitamente essere dinamiche e non dovrebbero essere memorizzate nella cache in modo statico.

Gestione degli errori

I contenuti del CMS potrebbero non essere disponibili durante una build o una richiesta. La tua applicazione dovrebbe gestire la situazione in modo corretto.

Comportamento consigliato:

• Restituisci 404 quando una route non esiste.
• Restituisci un elenco vuoto quando non è possibile caricare contenuti di navigazione opzionali.
• Registra gli errori di recupero lato server.
• Evita di esporre gli errori interni dell'API ai visitatori.

Esempio:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Impossibile recuperare il post del CMS', error);
    return null;
  }
}

Sicurezza

Mantieni private le chiavi API e utilizzale solo sul server. Non includere credenziali private nei bundle del browser o in JavaScript pubblico.

Utilizza variabili di ambiente pubbliche solo per valori non sensibili come:

• URL pubblico del CMS
• ID del sito web
• Configurazione della lingua

Utilizza variabili di ambiente private per:

• Chiavi API
• token di anteprima
• credenziali amministrative
• segreti di distribuzione

Riepilogo

Utilizza l'API del CMS quando il tuo sito web deve recuperare contenuti strutturati, renderizzare route gestite dal CMS o supportare flussi di lavoro di anteprima per gli editor.

Un'integrazione standard dovrebbe:

• Configurare l'URL del CMS, l'ID del sito web e la chiave API.
• Recuperare i documenti per schema.
• Recuperare le pagine in base al percorso della route.
• Renderizzare i blocchi del CMS con i propri componenti.
• Memorizzare nella cache i contenuti pubblicati.
• Mantenere dinamici i contenuti di anteprima.
• Mantenere le credenziali private sul server.