Conectar um site à API do CMS
A API do CMS permite que seu site busque e renderize conteúdo publicado do Profound CMS. Você pode usá-la para alimentar páginas de documentação, páginas de marketing, blogs, centrais de ajuda ou qualquer outra experiência orientada a conteúdo.
A integração típica possui três partes:
Para conectar sua aplicação ao CMS, forneça a URL da API do CMS, o ID do site e a chave da API.
const cmsConfig = {
cmsUrl: 'https://cms.dev.tryprofoun.com',
websiteId: 'your-website-id',
apiKey: process.env.PROFOUND_API_KEY,
};
Use variáveis de ambiente para valores que mudam entre ambientes:
NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=your-website-id
PROFOUND_API_KEY=your-api-key
Não exponha chaves de API privadas no código do lado do cliente. As chaves de API devem ser usadas no seu servidor, no processo de build ou nas rotas de backend.
O conteúdo no CMS é organizado por esquemas. Por exemplo, seu projeto pode ter esquemas como post, category, page ou section.
Use o nome do esquema para buscar conteúdo:
const posts = await cms.schema('post').fetchAll();
Para buscar um único documento pelo ID:
const post = await cms.schema('post').fetchSingleById('document-id');
Para buscar conteúdo localizado, solicite a versão traduzida do esquema:
const frenchPost = await cms
.schema('post')
.translation('fr')
.fetchSingleById('document-id');
Para sites que usam páginas gerenciadas pelo CMS, você pode buscar conteúdo com base no caminho atual da URL.
const route = await cms.route.getByPath({
websiteId: 'your-website-id',
path: '/docs/getting-started',
});
A resposta da rota identifica a página e os blocos a serem renderizados. Sua aplicação pode então buscar os blocos e renderizá-los com seus próprios componentes.
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,
};
}
Você pode usar os blocos retornados para renderizar a página utilizando o sistema de componentes da sua aplicação.
O conteúdo publicado do CMS é seguro para colocar em cache. Para a maioria dos sites, faça cache das respostas da API por um curto período e revalide-as quando o conteúdo mudar.
Uma configuração comum é:
const content = await cache(
() => cms.schema('post').fetchAll(),
{
revalidate: 60,
tags: ['cms-posts'],
}
);
Comportamento de cache recomendado:
O modo de pré-visualização permite que editores vejam alterações não publicadas antes de serem publicadas.
Um padrão comum é usar uma rota de pré-visualização separada, por exemplo:
/docs/getting-started
/cms-preview/docs/getting-started
As páginas de produção devem buscar apenas conteúdo publicado. As páginas de pré-visualização podem aceitar parâmetros de pré-visualização, como:
?edit_mode=true
Rotas de pré-visualização geralmente devem ser dinâmicas e não devem ser armazenadas em cache de forma estática.
O conteúdo do CMS pode ficar indisponível durante um build ou uma requisição. Sua aplicação deve lidar com isso de forma elegante.
Comportamento recomendado:
404 quando uma rota não existir.async function getPost(id: string) {
try {
return await cms.schema('post').fetchSingleById(id);
} catch (error) {
console.error('Falha ao buscar post do CMS', error);
return null;
}
}
Mantenha as chaves de API privadas e use-as apenas no servidor. Não inclua credenciais privadas em bundles do navegador ou em JavaScript público.
Use variáveis de ambiente públicas apenas para valores não sensíveis, como:
Use variáveis de ambiente privadas para:
Use a API do CMS quando seu site precisar buscar conteúdo estruturado, renderizar rotas gerenciadas pelo CMS ou oferecer fluxos de pré-visualização para editores.
Uma integração padrão deve: