Marketplace & Mini App

💡 Cho cả người dùng & developer

Phần cài Mini App từ Marketplace ai cũng dùng được. Phần tự xây Mini App (cuối trang) dành cho lập trình viên.

Marketplace là kho ứng dụng mở rộng (Mini App) của CNV Work. Workspace có thể cài Mini App từ catalog có sẵn để bổ sung tính năng — báo cáo chuyên biệt, đồng bộ với hệ thống bên ngoài, form khảo sát, dashboard tuỳ chỉnh — mà không cần code FE riêng.

Developer cũng có thể tự xây Mini App private (chỉ workspace mình) hoặc submit lên Marketplace public cho mọi workspace cài.

Truy cập

Vào menu Marketplace trên thanh sidebar, hoặc truy cập trực tiếp https://hub.cnvwork.com/marketplace.

Cài đặt và quản lý Mini App đã cài: Cài đặt > Mini App của tôi.

Mini App là gì

Mini App = một tập hợp page + widget chạy nhúng trong CNV Work, render bằng server-driven UI từ catalog widget có sẵn. Bạn định nghĩa cấu hình JSON — CNV Work render UI tương ứng.

Ưu điểm so với app stand-alone:

• Không cần code FE: chỉ JSON config + API endpoint trả data
• Tự động responsive: chạy trên web + mobile, dark mode, theme
• SSO sẵn: kế thừa đăng nhập của workspace, không cần OAuth riêng
• Cài đặt 1 click: user vào Marketplace nhấn Cài là dùng được
• Cập nhật tức thì: developer push config mới, mọi workspace cài thấy ngay

Nhược điểm: bị giới hạn trong catalog 8 widget — không phù hợp UI quá tuỳ biến (game, animation phức tạp).

Tổng quan kiến trúc

User mở Mini App → CNV Work đọc config (widget nào, fetch URL nào) → gọi endpoint của bạn → render data theo widget.

Cài Mini App từ Marketplace

Bước 1: Duyệt catalog

Vào Marketplace, lọc theo:

• Danh mục: CRM Add-on / Báo cáo / Tích hợp / Form & Survey / Năng suất
• Mới nhất / Phổ biến / Của CNV
• Tìm kiếm theo tên

Mỗi Mini App hiển thị:

• Icon, tên, mô tả ngắn
• Tác giả (CNV / Partner / Community)
• Số workspace đã cài
• Đánh giá (1-5 sao)
• Giá: Free / Trả phí (theo tháng)

Bước 2: Xem chi tiết

Nhấn vào Mini App để xem:

• Screenshot, video demo
• Tính năng chi tiết
• Permissions yêu cầu: list scope app cần (giống OAuth)
• Pricing detail
• Review từ workspace khác
• Changelog phiên bản

Bước 3: Cài đặt

1. Nhấn Cài
2. Hệ thống hiện màn xác nhận permissions:

"Báo cáo gameSPS" yêu cầu các quyền sau:
  - Đọc dữ liệu CRM (crm.read)
  - Đọc dữ liệu Inbox (inbox.read)
  - Đọc thông tin nhân viên (hr.employees.read)

App KHÔNG được phép: ghi/xoá dữ liệu, quản trị, mời user mới.

3. Nhấn Đồng ý & Cài
4. App xuất hiện ngay trong sidebar (icon + tên Mini App)
5. Nhấn vào để mở

Lưu ý

Chỉ vai trò Owner mới cài được Mini App. Member yêu cầu Owner cài giúp.

Một số Mini App phổ biến

Mini App	Mô tả
Báo cáo gameSPS	Dashboard chỉ số game của partner CNV
Đồng bộ Haravan	Sync đơn hàng Haravan ↔ CNV Work CRM
Kết nối Misa	Đẩy hoá đơn duyệt sang phần mềm kế toán Misa
Form khảo sát NPS	Gửi NPS survey sau ticket close, dashboard kết quả
Báo cáo OKR	Theo dõi OKR phòng ban, gắn với deal/task
Tracking shipping VTP	Tra cứu vận đơn Viettel Post
Chatbot AI assistant	Gắn AI vào hộp thoại Inbox, suggest reply

Quản lý Mini App đã cài

Vào Cài đặt > Mini App của tôi:

Cột	Mô tả
Tên	Tên + icon
Phiên bản	Version đang chạy
Trạng thái	Active / Disabled / Update available
Người cài	Ai đã cài
Ngày cài	Khi nào cài

Hành động:

• Mở — vào Mini App
• Cấu hình — đổi setting (nếu Mini App có)
• Disable — tạm ẩn không xoá data
• Update — cập nhật lên version mới
• Gỡ cài — xoá hoàn toàn, mất config

Catalog 8 widget

Khi tự xây Mini App, bạn dùng các widget có sẵn:

Widget	Mục đích	Ví dụ
list	Danh sách item với cột tuỳ chỉnh	Danh sách đơn từ hệ thống ngoài
form	Form nhập liệu validate	Form đăng ký event nội bộ
chart	Biểu đồ (line/bar/pie/area)	Doanh thu theo ngày
kanban	Board kéo thả	Backlog task của bạn
calendar	Lịch tháng/tuần	Lịch chiến dịch marketing
timeline	Trục thời gian	Activity log cross-app
kpi-card	Số liệu lớn + so sánh kỳ trước	Tổng doanh thu hôm nay
html-block	HTML thuần (sandbox iframe)	Embed dashboard ngoài

Mỗi widget khai báo dataSource — URL endpoint của bạn (hoặc internal table) trả JSON theo schema widget yêu cầu.

Tự tạo Mini App private

Mini App private chỉ workspace bạn thấy — phù hợp dashboard nội bộ, integration riêng.

Bước 1: Chuẩn bị endpoint data

Endpoint của bạn phải:

• HTTPS
• Nhận GET hoặc POST tuỳ widget
• Verify header X-CNV-Workspace + X-CNV-Signature (tương tự webhook)
• Trả JSON đúng schema widget

Ví dụ endpoint trả data cho chart:

{
  "data": [
    { "date": "2026-05-20", "revenue": 12000000 },
    { "date": "2026-05-21", "revenue": 15500000 },
    { "date": "2026-05-22", "revenue": 9800000 }
  ]
}

Bước 2: Đăng ký Mini App qua API

Dùng API Keys gọi POST /api/v1/dyn-apps:

curl -X POST 'https://api.cnvwork.com/api/v1/dyn-apps' \
  -H 'Authorization: Bearer cnvw_live_xxx' \
  -H 'Content-Type: application/json' \
  -d @miniapp.json

Bước 3: Cấu hình miniapp.json (ví dụ tối giản)

Mini App "Báo cáo doanh thu" với 1 page và 1 chart widget:

{
  "slug": "revenue-report",
  "name": "Báo cáo doanh thu",
  "icon": "trending-up",
  "version": "1.0.0",
  "scopes": ["crm.read"],
  "sidebar": {
    "label": "Báo cáo DT",
    "position": "after:reports"
  },
  "pages": [
    {
      "slug": "main",
      "title": "Doanh thu 30 ngày",
      "layout": "single-column",
      "widgets": [
        {
          "id": "kpi-total",
          "type": "kpi-card",
          "title": "Tổng doanh thu tháng",
          "dataSource": {
            "method": "GET",
            "url": "https://yourapp.com/api/cnv/kpi-total",
            "cacheSeconds": 300
          },
          "format": {
            "valueKey": "total",
            "unit": "VND",
            "comparePreviousKey": "previous_total"
          }
        },
        {
          "id": "chart-daily",
          "type": "chart",
          "title": "Doanh thu theo ngày",
          "chartType": "line",
          "dataSource": {
            "method": "GET",
            "url": "https://yourapp.com/api/cnv/daily-revenue",
            "cacheSeconds": 600
          },
          "xKey": "date",
          "yKeys": [
            { "key": "revenue", "label": "Doanh thu", "color": "#0EA5E9" }
          ]
        }
      ]
    }
  ]
}

Sau khi POST thành công, app xuất hiện trong sidebar workspace với tên "Báo cáo DT".

Bước 4: Update Mini App

Mỗi lần đổi config, PATCH /api/v1/dyn-apps/:slug — version mới live ngay. Hoặc dùng MCP tool nếu bạn dùng cnv-vibe MCP server (tooling devloop nhanh hơn).

Bước 5: Flush cache

Khi đổi config nhưng UI chưa cập nhật, flush cache:

curl -X POST 'https://api.cnvwork.com/api/v1/dyn-apps/revenue-report/flush' \
  -H 'Authorization: Bearer cnvw_live_xxx'

Submit Mini App lên Marketplace public

Để Mini App khả dụng cho mọi workspace, submit qua quy trình review:

Yêu cầu

• Mini App đã chạy ổn định trên 1+ workspace ít nhất 2 tuần
• Có icon vuông 512x512 PNG
• Có ít nhất 3 screenshot 1920x1080
• Có README mô tả tính năng + setup
• Privacy policy URL (bắt buộc nếu thu thập data user)
• Terms of service URL

Quy trình

1. Vào https://hub.cnvwork.com/developer/submit
2. Upload Mini App config + assets
3. Chọn category, pricing model
4. Submit review

CNV team review trong 3-5 ngày làm việc, kiểm tra:

• Tính năng hoạt động đúng mô tả
• Permissions hợp lý (không over-request)
• UI/UX đạt chuẩn
• Privacy/security (endpoint HTTPS, signature verify, không leak data cross-tenant)
• Pricing minh bạch

Sau khi approved, app lên Marketplace trong 24h.

Pricing model

Model	Mô tả
Free	Miễn phí, không thu tiền
Free + Paid features	Free core, charge add-on
Subscription	$X/workspace/tháng, CNV thu hộ, chia 70/30
One-time	Trả 1 lần, dùng vĩnh viễn
BYO (Bring Your Own)	Free trên Marketplace, user trả bạn trực tiếp

CNV charge fee 30% với model Subscription/One-time (giống App Store). Model BYO không thu fee nhưng phải hiển thị rõ giá ở description.

Phân biệt private vs public

Khía cạnh	Private	Public
Ai thấy	Chỉ workspace tạo	Mọi workspace browse Marketplace
Submit review	Không	Có (3-5 ngày)
Update	Live ngay	Phải bump version + review lại nếu thay đổi lớn
Pricing	Free	Free hoặc trả phí
Số config tối đa	50 page / workspace	200 page / app
Phù hợp	Dashboard nội bộ, integration riêng	Sản phẩm bán cho nhiều workspace

Best practice xây Mini App

Khuyến nghị

1. Endpoint phải nhanh: <2s response time, hoặc bật cacheSeconds
2. Verify X-CNV-Workspace + X-CNV-Signature — không leak data cross-tenant
3. Scope tối thiểu: chỉ request quyền thực sự cần (crm.read thay vì crm.*)
4. Graceful degradation: nếu endpoint down, widget show empty state thân thiện thay vì crash
5. Loading state: trả loading: true nhanh, fetch detail sau
6. i18n: hỗ trợ tiếng Việt + tiếng Anh cho label, title
7. Version semver: 1.0.0 → 1.1.0 (minor), 2.0.0 (breaking)
8. Changelog: ghi rõ thay đổi mỗi phiên bản
9. Test trên private trước khi submit public

Quản lý phiên bản

Cập nhật Mini App đã publish:

• Patch (1.0.0 → 1.0.1): bug fix → auto-roll out cho mọi workspace cài
• Minor (1.0.0 → 1.1.0): thêm tính năng không breaking → auto-roll out, hiện badge "New" trong sidebar
• Major (1.0.0 → 2.0.0): breaking change → workspace phải accept lại permissions mới

Lỗi thường gặp

Lỗi	Nguyên nhân	Xử lý
Widget hiển thị "Failed to load"	Endpoint trả 5xx hoặc timeout	Kiểm tra endpoint, xem log Mini App
Permission denied	Mini App config scope không khớp với API key gọi	Đổi scope hoặc dùng API key đủ quyền
Mini App không xuất hiện	Cache chưa flush	Gọi /dyn-apps/:slug/flush
Data sai workspace	Endpoint không filter theo X-CNV-Workspace	Sửa BE filter theo workspace ID
Cài thất bại "permission required"	User không phải Owner	Nhờ Owner cài giúp

Liên kết liên quan

• API Keys — gọi REST API CNV Work từ Mini App
• Webhooks — push event realtime vào Mini App
• Developer Portal — hub tài liệu, ví dụ, sandbox