Citely Connect — Tổng quan
Giao thức Citely Publish Protocol (CPP v1) để đẩy bài viết đã hoàn thiện từ Citely ra website của bạn.
Citely Connect là cách Citely đẩy bài viết đã hoàn thiện ra website của bạn. Citely Publish Protocol v1 (CPP v1) là hợp đồng kỹ thuật mà website xây theo để nhận bài — Citely đặt chuẩn, website conform.
Citely đóng vai CMS/bộ não nội dung. Nhiều landing page hiện đại (Astro, Next.js, Hugo, React thuần, Laravel…) không có CMS quản trị blog. Citely Connect lấp đúng chỗ đó: website chỉ cần dựng một endpoint theo CPP v1 là sẵn sàng nhận bài — không phải tự viết admin, editor, auth, storage.
Kết nối bằng một dòng (copy cho AI)
Admin website không cần tự code. Copy đúng một dòng và dán cho AI của bạn (Claude Code / Cursor / Copilot):
Fetch https://citely-seo.com/connect/v1/agent.md — rồi nối repo này với Citely.AI đó sẽ Fetch spec, tự nhận diện stack, chọn adapter, dựng endpoint, map field theo schema repo của bạn, và in ra hướng dẫn đặt CITELY_WEBHOOK_SECRET.
Ba tầng của chuẩn
| Tầng | Ai định nghĩa | Nội dung |
|---|---|---|
| 1. Envelope | Citely phát | 1 bài = 1 JSON canonical (html + markdown + jsonLd + meta + i18n + media) |
| 2. Receiver | Website xây | 1 endpoint: GET handshake năng lực + POST nhận bài |
| 3. Vocabulary | Cả hai nói chung | status + mã lỗi CPP_* |
Chọn adapter theo "bạn muốn SỞ HỮU dữ liệu tới đâu"
| Adapter | Ai lưu bài | Website xây | Lên sóng |
|---|---|---|---|
citely-api 🥇 | Citely (bạn 0 backend) | chỉ 1 reader (fetch + render), KHÔNG cần receiver | ngay |
db | DB của bạn | receiver upsert row → render động | ngay |
fs-build | đĩa/repo của bạn | receiver ghi file + trigger build | sau rebuild |
citely-api= mặc định khuyến nghị: bạn KHÔNG dựng endpoint — chỉ đăng ký site trong Citely, nhận read-key, rồi đọc read-API. Đây là adapter DUY NHẤT không cần receiver.dbcho bên muốn dữ liệu nằm trong DB của mình (Cloudflare D1 › Neon / Turso › Supabase).fs-buildcho site tĩnh self-host (ghi file + rebuild).
Adapter git (commit mỗi bài) và citely-git (GitHub App) đã bỏ/gác lại — ngàn commit + rebuild mỗi lần publish không scale.
Cây quyết định
Bạn muốn SỞ HỮU dữ liệu tới đâu?
├─ "Chỉ cần có bài, khỏi backend" → citely-api (Citely host + read-API) ⭐ mặc định
├─ "Muốn bài trong DB của tôi" → db (D1/Neon/Turso › Supabase)
└─ "Khăng khăng self-host tĩnh" → fs-build (ghi file + rebuild)Tiếp theo
Envelope (CPP v1)
Cấu trúc JSON của một bài viết Citely gửi ra.
Receiver endpoint
GET handshake + POST nhận bài.
Ký webhook
Standard Webhooks: header, HMAC, chống replay.
Mã lỗi CPP_*
Từ vựng lỗi & trạng thái publish.
Read-API
Đọc bài với adapter citely-api (endpoint, auth, phân trang).
Adapters
citely-api · db · fs-build.