Connect your website

CMS API'si, web sitenizin Profound CMS'den yayımlanmış içeriği almasına ve görüntülemesine olanak tanır. Bunu dokümantasyon sayfalarını, pazarlama sayfalarını, blogları, yardım merkezlerini veya içerik odaklı diğer deneyimleri desteklemek için kullanabilirsiniz.

Tipik entegrasyon üç bölümden oluşur:

1. CMS bağlantınızı yapılandırın
2. Yayınlanmış içeriği alın
3. İçeriği uygulamanızda oluşturun

Yapılandırma

Uygulamanızı CMS'ye bağlamak için CMS API URL'nizi, web sitesi kimliğinizi ve API anahtarınızı girin.

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

Ortamlar arasında değişen değerler için ortam değişkenlerini kullanın:

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

Özel API anahtarlarını istemci tarafı kodunda açığa çıkarmayın. API anahtarları sunucunuzda, derleme sürecinizde veya arka uç rotalarınızda kullanılmalıdır.

İçerik Getirme

CMS'deki içerik şemalara göre düzenlenmiştir. Örneğin projenizde post, category, page veya section gibi şemalar bulunabilir.

İçerik almak için şema adını kullanın:

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

Tek bir belgeyi kimliğine göre almak için:

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

Yerelleştirilmiş içeriği almak için şemanın çevrilmiş sürümünü isteyin:

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

Rotaları Oluşturma

CMS tarafından yönetilen sayfaları kullanan web siteleri için, geçerli URL yoluna göre içerik alabilirsiniz.

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

Rota yanıtı, sayfayı ve oluşturulacak blokları belirler. Ardından uygulamanız blokları alabilir ve kendi bileşenlerinizle oluşturabilir.

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

Örnek: Bir Dokümantasyon Sayfası Oluşturma

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

Dönen blokları kullanarak sayfayı uygulamanızın bileşen sistemiyle oluşturabilirsiniz.

Önbellekleme

Yayımlanmış CMS içeriğini önbelleğe almak güvenlidir. Çoğu web sitesi için API yanıtlarını kısa bir süre önbelleğe alın ve içerik değiştiğinde yeniden doğrulayın.

Yaygın bir kurulum şöyledir:

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

Önerilen önbellek davranışı:

• Yayımlanmış okumaları önbelleğe alın.
• Sıklıkla güncellenen içerikler için daha kısa önbellek pencereleri kullanın.
• Çerçeveniz isteğe bağlı geçersiz kılmayı destekliyorsa önbellek etiketleri kullanın.
• Önizleme veya taslak içeriği önbelleğe almaktan kaçının.

Önizleme Modu

Önizleme modu, editörlerin yayımlanmadan önce yayımlanmamış değişiklikleri görmesini sağlar.

Yaygın bir model, ayrı bir önizleme rotası kullanmaktır; örneğin:

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

Canlı sayfalar yalnızca yayımlanmış içeriği almalıdır. Önizleme sayfaları aşağıdakiler gibi önizleme parametrelerini kabul edebilir:

?edit_mode=true

Önizleme rotaları genellikle dinamik olmalı ve statik olarak önbelleğe alınmamalıdır.

Hata Yönetimi

Bir derleme veya istek sırasında CMS içeriği kullanılamayabilir. Uygulamanız bu durumu sorunsuzca ele almalıdır.

Önerilen davranış:

• Bir rota mevcut olmadığında 404 döndürün.
• İsteğe bağlı gezinme içeriği yüklenemediğinde boş bir liste döndürün.
• Sunucu tarafı alma hatalarını kaydedin.
• Ziyaretçilere dahili API hatalarını göstermeyin.

Örnek:

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

Güvenlik

API anahtarlarını gizli tutun ve yalnızca sunucuda kullanın. Özel kimlik bilgilerini tarayıcı paketlerine veya herkese açık JavaScript'e dahil etmeyin.

Genel ortam değişkenlerini yalnızca aşağıdakiler gibi hassas olmayan değerler için kullanın:

• CMS genel URL'si
• Web sitesi kimliği
• Yerel ayar yapılandırması

Aşağıdakiler için özel ortam değişkenleri kullanın:

• API anahtarları
• önizleme jetonları
• yönetici kimlik bilgileri
• dağıtım sırları

Özet

Web sitenizin yapılandırılmış içerik alması, CMS tarafından yönetilen rotaları oluşturması veya editör önizleme iş akışlarını desteklemesi gerektiğinde CMS API'sini kullanın.

Standart bir entegrasyon şunları yapmalıdır:

• CMS URL'sini, web sitesi kimliğini ve API anahtarını yapılandırın.
• Belgeleri şemaya göre alın.
• Sayfaları rota yoluna göre alın.
• CMS bloklarını kendi bileşenlerinizle oluşturun.
• Yayınlanmış içeriği önbelleğe alın.
• Önizleme içeriğini dinamik tutun.
• Özel kimlik bilgilerini sunucuda tutun.