Connect your website

La API del CMS permite que tu sitio web obtenga y renderice contenido publicado desde Profound CMS. Puedes usarla para impulsar páginas de documentación, páginas de marketing, blogs, centros de ayuda o cualquier otra experiencia impulsada por contenido.

La integración típica tiene tres partes:

1. Configura tu conexión con el CMS
2. Obtén el contenido publicado
3. Renderiza el contenido en tu aplicación

Configuración

Para conectar tu aplicación con el CMS, proporciona la URL de la API del CMS, el ID del sitio web y la clave API.

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

Usa variables de entorno para valores que cambian entre entornos:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=tu-id-de-sitio-web
PROFOUND_API_KEY=tu-clave-api

No expongas claves API privadas en el código del lado del cliente. Las claves API deben usarse en tu servidor, en tu proceso de compilación o en tus rutas de backend.

Obtener contenido

El contenido en el CMS se organiza por esquema. Por ejemplo, tu proyecto puede tener esquemas como publicacion, categoria, pagina o seccion.

Utiliza el nombre del esquema para obtener contenido:

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

Para obtener un solo documento por ID:

const post = await cms.schema('publicacion').fetchSingleById('id-del-documento');

Para obtener contenido localizado, solicita la versión traducida del esquema:

const frenchPost = await cms
  .schema('publicacion')
  .translation('fr')
  .fetchSingleById('id-del-documento');

Renderizar rutas

Para los sitios web que usan páginas administradas por el CMS, puedes obtener contenido basado en la ruta URL actual.

const route = await cms.route.getByPath({
  websiteId: 'tu-id-de-sitio-web',
  path: '/docs/primeros-pasos',
});

La respuesta de la ruta identifica la página y los bloques que se deben renderizar. Tu aplicación puede entonces obtener los bloques y renderizarlos con tus propios componentes.

const blocks = await cms.block.getByIds({
  websiteId: 'tu-id-de-sitio-web',
  ids: route.blockIds,
});

Ejemplo: renderizar una página de documentación

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

Puedes usar los bloques devueltos para renderizar la página con el sistema de componentes de tu aplicación.

Almacenamiento en caché

El contenido publicado del CMS es seguro para almacenar en caché. Para la mayoría de los sitios web, almacena en caché las respuestas de la API por un breve periodo y revalídalas cuando el contenido cambie.

Una configuración común es:

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

Comportamiento de caché recomendado:

• Almacena en caché las lecturas publicadas.
• Usa ventanas de caché más cortas para contenido que se actualiza con frecuencia.
• Usa etiquetas de caché si tu framework admite invalidación bajo demanda.
• Evita almacenar en caché el contenido de vista previa o borrador.

Modo de vista previa

El modo de vista previa permite que los editores vean los cambios no publicados antes de publicarlos.

Un patrón común es usar una ruta de vista previa separada, por ejemplo:

/docs/primeros-pasos
/cms-preview/docs/primeros-pasos

Las páginas de producción deben obtener solo contenido publicado. Las páginas de vista previa pueden aceptar parámetros de vista previa, como:

?modo_edicion=true

Las rutas de vista previa generalmente deben ser dinámicas y no deben almacenarse en caché de manera estática.

Manejo de errores

El contenido del CMS puede no estar disponible durante una compilación o una solicitud. Tu aplicación debe manejar esto de manera adecuada.

Comportamiento recomendado:

• Devuelve 404 cuando una ruta no existe.
• Devuelve una lista vacía cuando no se puede cargar contenido de navegación opcional.
• Registra los errores de obtención en el lado del servidor.
• Evita exponer errores internos de la API a los visitantes.

Ejemplo:

async function getPost(id: string) {
  try {
    return await cms.schema('publicacion').fetchSingleById(id);
  } catch (error) {
    console.error('No se pudo obtener la publicación del CMS', error);
    return null;
  }
}

Seguridad

Mantén las claves API privadas y úsalas solo en el servidor. No incluyas credenciales privadas en paquetes del navegador ni en JavaScript público.

Usa variables de entorno públicas solo para valores no sensibles como:

• URL pública del CMS
• ID del sitio web
• Configuración regional

Usa variables de entorno privadas para:

• Claves API
• Tokens de vista previa
• Credenciales de administrador
• Secretos de implementación

Resumen

Usa la API del CMS cuando tu sitio web necesite obtener contenido estructurado, renderizar rutas administradas por el CMS o admitir flujos de trabajo de vista previa para editores.

Una integración estándar debe:

• Configurar la URL del CMS, el ID del sitio web y la clave API.
• Obtener documentos por esquema.
• Obtener páginas por ruta.
• Renderizar bloques del CMS con tus propios componentes.
• Almacenar en caché el contenido publicado.
• Mantener el contenido de vista previa dinámico.
• Mantener las credenciales privadas en el servidor.