Giao diện

Cài đặt và sử dụng — Embed ​

Tổng quan ​

Plugin plugin-embed cho phép chia sẻ các trang Digiforce dưới dạng nhúng (embed) vào website hoặc ứng dụng bên ngoài thông qua iframe. Trang nhúng hiển thị nội dung đầy đủ nhưng ẩn header và sidebar — tạo trải nghiệm tích hợp liền mạch.

Yêu cầu ​

Thành phầnYêu cầu
Server DigiforcePhiên bản >= 1.0
Trình duyệtHỗ trợ iframe (mọi trình duyệt hiện đại)

Bước 1: Kích hoạt plugin ​

  1. Truy cập Settings → Plugin Manager
  2. Tìm plugin-embed
  3. Bật công tắc Enable

Plugin đăng ký route /embed/:name — cho phép truy cập trang Digiforce qua URL nhúng.

Có hai cách lấy link nhúng:

Cách 1: Từ giao diện trang ​

  1. Mở trang muốn nhúng
  2. Nhấn vào Page Settings (biểu tượng cài đặt)
  3. Chọn Copy embedded link
  4. Link nhúng được sao chép vào clipboard

Cách 2: Tự xây dựng URL ​

Chuyển đổi URL admin thành URL embed:

URL admin: https://your-domain/admin/page-uid
URL embed: https://your-domain/embed/page-uid

Với trang có tabs:

URL admin: https://your-domain/admin/page-uid/tabs/tab-uid
URL embed: https://your-domain/embed/page-uid/tabs/tab-uid

Bước 3: Nhúng vào website ​

Dán embed code vào HTML của website bên ngoài:

html
<iframe
  src="https://your-domain.com/embed/page-uid"
  width="100%"
  height="600"
  frameborder="0"
  style="border: none;"
></iframe>

Tùy chỉnh kích thước ​

Thuộc tínhMô tảVí dụ
widthChiều rộng iframe100%, 800px
heightChiều cao iframe600px, 100vh
styleCSS tùy chỉnhborder: none; border-radius: 8px;

Responsive embed ​

html
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe
    src="https://your-domain.com/embed/page-uid"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;"
    allowfullscreen
  ></iframe>
</div>

Xác thực (Authentication) ​

Embed có xác thực ​

Mặc định, trang nhúng yêu cầu đăng nhập. Nếu user chưa đăng nhập, hiển thị trang lỗi 403 "Not Authorized".

Để truyền token xác thực vào embed, thêm query parameter token:

https://your-domain.com/embed/page-uid?token=<bearer-token>

Khi có token trong URL, plugin sẽ:

  1. Lưu token vào sessionStorage (không phải localStorage) để cách ly session
  2. Sử dụng token để xác thực API request
  3. Tạo storage prefix riêng để tránh xung đột với session chính

Bảo mật

Token trong URL có thể bị lộ qua browser history và server log. Chỉ sử dụng cách này cho môi trường nội bộ hoặc token có thời hạn ngắn.

Embed ẩn danh ​

Nếu muốn cho phép xem không cần đăng nhập, cần:

  1. Cấu hình ACL cho phép anonymous access cho collection tương ứng
  2. Trang phải sử dụng dữ liệu public

Giao diện nhúng ​

Plugin tạo layout đặc biệt cho trang nhúng:

Thành phầnHiển thị
HeaderẨn (--df-header-height: 0px)
SidebarẨn
Nội dung trangHiển thị đầy đủ
KeepAliveGiữ trạng thái trang khi chuyển tab

Cấu hình nâng cao ​

Nhúng tab cụ thể ​

Nếu trang có nhiều tab, bạn có thể nhúng một tab cụ thể:

https://your-domain.com/embed/page-uid/tabs/tab-uid

Cấu hình CORS ​

Nếu website bên ngoài ở domain khác, cần cấu hình CORS trên server Digiforce:

CORS_ORIGIN=https://external-website.com

Lưu ý ​

  • Trang bên ngoài nhúng Digiforce cần đảm bảo server Digiforce cho phép cross-origin request
  • SessionStorage được sử dụng để cách ly embed session khỏi admin session
  • Mỗi embed instance có storage prefix riêng (uid ngẫu nhiên)
  • Plugin không thêm collection hay API mới — hoạt động hoàn toàn ở phía client
  • Trang nhúng vẫn tuân theo ACL — user chỉ xem được dữ liệu mà role cho phép