Connect your website

API CMS memungkinkan situs web Anda mengambil dan merender konten yang telah diterbitkan dari Profound CMS. Anda dapat menggunakannya untuk mendukung halaman dokumentasi, halaman pemasaran, blog, pusat bantuan, atau pengalaman lain yang berfokus pada konten.

Integrasi khas memiliki tiga bagian:

1. Konfigurasikan koneksi CMS Anda
2. Ambil konten yang telah diterbitkan
3. Render konten tersebut di aplikasi Anda

Konfigurasi

Untuk menghubungkan aplikasi Anda ke CMS, sediakan URL API CMS Anda, ID situs web, dan kunci API.

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

Gunakan variabel lingkungan untuk nilai yang berubah antar lingkungan:

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

Jangan mengekspos kunci API pribadi dalam kode sisi klien. Kunci API harus digunakan di server Anda, dalam proses build, atau di rute backend Anda.

Mengambil Konten

Konten di CMS diatur berdasarkan skema. Misalnya, proyek Anda mungkin memiliki skema seperti post, category, page, atau section.

Gunakan nama skema untuk mengambil konten:

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

Untuk mengambil satu dokumen berdasarkan ID:

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

Untuk mengambil konten yang dilokalkan, mintalah versi terjemahan dari skema tersebut:

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

Merender Rute

Untuk situs web yang menggunakan halaman yang dikelola CMS, Anda dapat mengambil konten berdasarkan jalur URL saat ini.

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

Respons rute mengidentifikasi halaman dan blok yang harus dirender. Aplikasi Anda kemudian dapat mengambil blok-blok tersebut dan merendernya dengan komponen Anda sendiri.

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

Contoh: Merender Halaman Dokumentasi

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

Anda dapat menggunakan blok yang dikembalikan untuk merender halaman menggunakan sistem komponen aplikasi Anda.

Penyimpanan Cache

Konten CMS yang telah diterbitkan aman untuk di-cache. Untuk sebagian besar situs web, cache respons API untuk periode singkat dan lakukan validasi ulang ketika konten berubah.

Penyiapan umum adalah:

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

Perilaku cache yang direkomendasikan:

• Cache pembacaan yang telah diterbitkan.
• Gunakan jendela cache yang lebih pendek untuk konten yang sering diperbarui.
• Gunakan tag cache jika kerangka kerja Anda mendukung invalidasi sesuai permintaan.
• Hindari melakukan cache pada konten pratinjau atau draf.

Mode Pratinjau

Mode pratinjau memungkinkan editor melihat perubahan yang belum diterbitkan sebelum diterbitkan.

Pola umum adalah menggunakan rute pratinjau terpisah, misalnya:

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

Halaman produksi harus hanya mengambil konten yang telah diterbitkan. Halaman pratinjau dapat menerima parameter pratinjau, seperti:

?edit_mode=true

Rute pratinjau biasanya harus dinamis dan tidak boleh di-cache secara statis.

Penanganan Kesalahan

Konten CMS mungkin tidak tersedia selama proses build atau permintaan. Aplikasi Anda harus menanganinya dengan baik.

Perilaku yang direkomendasikan:

• Kembalikan 404 ketika sebuah rute tidak ada.
• Kembalikan daftar kosong ketika konten navigasi opsional tidak dapat dimuat.
• Catat kesalahan pengambilan sisi server.
• Hindari mengekspos kesalahan API internal kepada pengunjung.

Contoh:

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

Keamanan

Jaga kerahasiaan kunci API dan gunakan hanya di server. Jangan menyertakan kredensial pribadi dalam bundel browser atau JavaScript publik.

Gunakan variabel lingkungan publik hanya untuk nilai non-sensitif seperti:

• URL publik CMS
• ID situs web
• Konfigurasi lokal

Gunakan variabel lingkungan privat untuk:

• Kunci API
• Token pratinjau
• Kredensial admin
• Rahasia deployment

Ringkasan

Gunakan API CMS ketika situs web Anda perlu mengambil konten terstruktur, merender rute yang dikelola CMS, atau mendukung alur kerja pratinjau editor.

Integrasi standar sebaiknya:

• Mengonfigurasi URL CMS, ID situs web, dan kunci API.
• Mengambil dokumen berdasarkan skema.
• Mengambil halaman berdasarkan jalur rute.
• Merender blok CMS dengan komponen Anda sendiri.
• Menyimpan konten yang telah diterbitkan dalam cache.
• Membiarkan konten pratinjau tetap dinamis.
• Menyimpan kredensial pribadi di server.