Phân biệt hai hình thức nhúng

Chuẩn bị hồ sơ chat

• Các kênh được hiển thị.
• Thành viên được phép trực chat.
• Dịch vụ chatbot.
• Cấu hình hội thoại.
• Nguồn website được phép tải màn hình.
• Khóa nhúng dùng để xác định phạm vi dữ liệu.

• URL mở màn hình hỗ trợ.
• Đoạn iframe hoàn chỉnh.
• Nút sao chép.
• Nút mở thử trong tab mới.

Thêm nhân viên hỗ trợ vào hồ sơ

1. Tạo tài khoản người dùng cho nhân viên.
2. Mở trang chi tiết hồ sơ chat.
3. Thêm người dùng đó vào danh sách thành viên.
4. Chọn vai trò nhân viên chăm sóc khách hàng.
5. Đặt trạng thái thành viên là ACTIVATED.

• Tư cách thành viên kênh.
• Hồ sơ được truyền vào URL.
• Trạng thái của kênh.

Lấy đoạn iframe

<iframe
    src="https://chat.example.com/ezychat/support?profile=YOUR_EMBED_KEY&lang=vi"
    title="Support Chat"
    width="100%"
    height="700"
    frameborder="0"
    allow="clipboard-write">
</iframe>

• https://chat.example.com bằng địa chỉ máy chủ chat.
• YOUR_EMBED_KEY bằng khóa nhúng của hồ sơ.
• vi bằng ngôn ngữ muốn sử dụng.

Nhúng vào trang quản trị

<!DOCTYPE html>
<html lang="vi">
<head>
    <meta charset="UTF-8">
    <meta
        name="viewport"
        content="width=device-width, initial-scale=1">

    <title>Quản trị hỗ trợ khách hàng</title>

    <style>
        html,
        body {
            height: 100%;
            margin: 0;
        }

        .admin-layout {
            display: grid;
            grid-template-rows: 64px minmax(0, 1fr);
            height: 100vh;
        }

        .admin-header {
            display: flex;
            align-items: center;
            padding: 0 24px;
            border-bottom: 1px solid #ddd;
        }

        .chat-frame {
            display: block;
            width: 100%;
            height: 100%;
            border: 0;
        }
    </style>
</head>
<body>
    <div class="admin-layout">
        <header class="admin-header">
            <strong>Trung tâm hỗ trợ</strong>
        </header>

        <iframe
            class="chat-frame"
            src="https://chat.example.com/ezychat/support?profile=YOUR_EMBED_KEY&lang=vi"
            title="Màn hình hỗ trợ chat"
            allow="clipboard-write">
        </iframe>
    </div>
</body>
</html>

Cấu trúc URL

https://chat.example.com/ezychat/support
    ?profile=YOUR_EMBED_KEY
    &lang=vi
    &style=

Tham số profile

profile=YOUR_EMBED_KEY

1. Tìm hồ sơ tương ứng.
2. Kiểm tra hồ sơ đang hoạt động.
3. Kiểm tra nguồn mở iframe.
4. Truyền ID hồ sơ xuống ứng dụng.
5. Lọc danh sách hội thoại theo hồ sơ đó.

Tham số lang

lang=vi

<iframe
    src="https://chat.example.com/ezychat/support?profile=YOUR_EMBED_KEY&lang=vi"
    title="Màn hình hỗ trợ chat">
</iframe>

Tham số style

style=CSS_DA_MA_HOA_URL

• data-style thay đổi iframe bên ngoài.
• Tham số style thay đổi giao diện bên trong iframe.

.ezychat-support-page {
    padding: 0;
}

#chatSection {
    height: 100vh;
    border-radius: 0;
}

const profileKey = 'YOUR_EMBED_KEY';

const customStyle = `
    .ezychat-support-page {
        padding: 0;
    }

    #chatSection {
        height: 100vh;
        border-radius: 0;
    }
`;

const supportUrl =
    'https://chat.example.com/ezychat/support'
    + '?profile=' + encodeURIComponent(profileKey)
    + '&lang=' + encodeURIComponent('vi')
    + '&style=' + encodeURIComponent(customStyle);

document.getElementById('supportChatFrame').src = supportUrl;

<iframe
    id="supportChatFrame"
    title="Màn hình hỗ trợ chat"
    class="chat-frame"
    allow="clipboard-write">
</iframe>

Kích thước mặc định

• Chiếm toàn bộ chiều cao viewport của iframe.
• Có khoảng đệm 24px.
• Căn giữa vùng chat.
• Đặt chiều cao vùng chat là 100vh - 48px.
• Bo góc vùng làm việc.
• Ẩn phần nội dung tràn ra ngoài.

.ezychat-support-page {
    padding: 0;
}

#chatSection {
    height: 100vh;
    border-radius: 0;
}

Ví dụ nhúng vào bố cục có thanh bên

<div class="admin-shell">
    <aside class="admin-sidebar">
        <a href="/dashboard">Tổng quan</a>
        <a href="/support">Hỗ trợ khách hàng</a>
    </aside>

    <main class="admin-content">
        <iframe
            src="https://chat.example.com/ezychat/support?profile=YOUR_EMBED_KEY&lang=vi"
            title="Hỗ trợ khách hàng"
            class="support-frame"
            allow="clipboard-write">
        </iframe>
    </main>
</div>

html,
body {
    height: 100%;
    margin: 0;
}

.admin-shell {
    display: grid;
    grid-template-columns: 240px minmax(0, 1fr);
    height: 100vh;
}

.admin-sidebar {
    overflow-y: auto;
    border-right: 1px solid #ddd;
}

.admin-content {
    min-width: 0;
    min-height: 0;
}

.support-frame {
    display: block;
    width: 100%;
    height: 100%;
    border: 0;
}

Luồng xác thực

sequenceDiagram
    participant A as Trang quản trị
    participant F as Support iframe
    participant Auth as Dịch vụ đăng nhập
    participant Chat as Dịch vụ chat

    A->>F: Tải màn hình theo khóa hồ sơ

    alt Chưa đăng nhập
        F-->>A: Hiển thị form đăng nhập trong iframe
        F->>Auth: Gửi tên đăng nhập và mật khẩu
        Auth-->>F: Thiết lập cookie phiên
        F->>F: Tải lại trang
    end

    F->>Chat: Kiểm tra tư cách thành viên hồ sơ
    alt Có quyền
        Chat-->>F: Cho phép vào màn hình chat
        F->>Chat: Tải danh sách hội thoại
        F->>Chat: Kết nối socket
    else Không có quyền
        Chat-->>F: Từ chối truy cập
        F-->>A: Hiển thị màn hình không có quyền
    end

• Tên đăng nhập hoặc email.
• Mật khẩu.
• Nút hiện hoặc ẩn mật khẩu.
• Nút đăng nhập.
• Thông báo khi đăng nhập thất bại.

Kiểm tra quyền

• Chưa đăng nhập: hiển thị biểu mẫu đăng nhập.
• Đã đăng nhập nhưng không có quyền: hiển thị thông báo từ chối.
• Đủ quyền: hiển thị màn hình hỗ trợ.

Tài khoản sử dụng

• Đăng nhập qua API dành cho người dùng.
• Lấy access token socket dành cho người dùng.
• Kiểm tra quan hệ thành viên hồ sơ theo loại người dùng.
• Truy cập các kênh mà người đó là thành viên.

• Phiên quản trị của trang /chat.
• Admin access token.
• Vai trò nhân viên hỗ trợ toàn cục dành cho tài khoản quản trị.

Kết nối realtime

1. Lấy socket access token.
2. Kết nối tới WebSocket của hệ thống chat.
3. Đăng nhập socket bằng access token của người dùng.
4. Tải các kênh thuộc hồ sơ.
5. Nhận tin nhắn và trạng thái nhập realtime.

• Đang kết nối.
• Trực tuyến.
• Ngoại tuyến.

Các chức năng trong iframe

• Danh sách hội thoại đang hoạt động.
• Danh sách hội thoại đã lưu trữ.
• Cuộn tải thêm hội thoại.
• Tin nhắn cuối và số chưa đọc.
• Nhận và gửi tin realtime.
• Gửi văn bản, liên kết và media.
• Kéo thả tệp.
• Trả lời tin nhắn.
• Ghim và bỏ ghim.
• Nhảy tới tin đã ghim.
• Tải lịch sử cũ.
• Trạng thái đang nhập.
• Bật hoặc tắt chatbot.
• Quan sát chatbot đang sinh câu trả lời.
• Xem thông tin khách hàng.
• Đánh dấu hoặc bỏ đánh dấu spam.
• Lưu trữ và khôi phục hội thoại.
• Chuyển giao diện sáng hoặc tối.
• Chọn màu chủ đạo.
• Đăng xuất.

Khác biệt với màn hình /chat

Cookie và nhúng khác origin

Trang quản trị: https://admin.example.com
Máy chủ chat:   https://chat.example.net

• Đăng nhập thành công nhưng tải lại vẫn quay về form đăng nhập.
• Cookie không được lưu.
• API kiểm tra quyền trả về chưa xác thực.
• Socket access token không lấy được.

SameSite=None; Secure

• Đặt trang quản trị và dịch vụ chat dưới cùng một site.
• Dùng reverse proxy để xuất màn hình chat dưới tên miền quản trị.
• Triển khai đăng nhập liên thông.
• Mở màn hình hỗ trợ trong tab riêng nếu cookie iframe bị chặn.

https://admin.example.com/
https://chat.example.com/

Cấu hình máy chủ cho phép iframe

Content-Security-Policy: frame-ancestors https://admin.example.com

X-Frame-Options: DENY

Content Security Policy của trang quản trị

Content-Security-Policy:
  default-src 'self';
  frame-src https://chat.example.com;

Kiểm tra origin

scheme://host[:port]

https://admin.example.com

https://admin.example.com
https://staging-admin.example.com
http://localhost:3000

Sử dụng sandbox

<iframe
    src="https://chat.example.com/ezychat/support?profile=YOUR_EMBED_KEY&lang=vi"
    title="Màn hình hỗ trợ chat"
    class="support-frame"
    allow="clipboard-write"
    sandbox="
        allow-forms
        allow-scripts
        allow-same-origin
        allow-popups">
</iframe>

• allow-forms: cho phép đăng nhập và gửi form.
• allow-scripts: cho phép ứng dụng chat chạy.
• allow-same-origin: cần cho cookie, localStorage và request cùng origin của iframe.
• allow-popups: cho phép mở liên kết ngoài nếu giao diện có sử dụng.

Cho phép clipboard

allow="clipboard-write"

Điều chỉnh chiều cao

Chiều cao cố định

<iframe
    src="..."
    width="100%"
    height="700"
    style="border: 0;">
</iframe>

Chiếm phần còn lại của màn hình

.admin-page {
    display: flex;
    flex-direction: column;
    height: 100vh;
}

.admin-header {
    flex: 0 0 64px;
}

.support-frame {
    flex: 1 1 auto;
    width: 100%;
    min-height: 0;
    border: 0;
}

Chiếm toàn màn hình

.support-frame {
    position: fixed;
    inset: 0;
    width: 100vw;
    height: 100vh;
    border: 0;
}

Tích hợp vào React

function SupportChatPage() {
  const chatOrigin = 'https://chat.example.com';
  const profileKey = 'YOUR_EMBED_KEY';

  const params = new URLSearchParams({
    profile: profileKey,
    lang: 'vi',
  });

  return (
    <iframe
      src={`/ezychat/support?`}
      title="Màn hình hỗ trợ chat"
      allow="clipboard-write"
      style={{
        display: 'block',
        width: '100%',
        height: 'calc(100vh - 64px)',
        border: 0,
      }}
    />
  );
}

Tích hợp vào Vue

<template>
  <iframe
    :src="supportUrl"
    title="Màn hình hỗ trợ chat"
    allow="clipboard-write"
    class="support-frame"
  />
</template>

<script setup>
const chatOrigin = 'https://chat.example.com';
const profileKey = 'YOUR_EMBED_KEY';

const params = new URLSearchParams({
  profile: profileKey,
  lang: 'vi',
});

const supportUrl =
  `/ezychat/support?`;
</script>

<style scoped>
.support-frame {
  display: block;
  width: 100%;
  height: calc(100vh - 64px);
  border: 0;
}
</style>

Tích hợp vào Angular

import { Component } from '@angular/core';
import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';

@Component({
  selector: 'app-support-chat',
  template: `
    <iframe
      [src]="supportUrl"
      title="Màn hình hỗ trợ chat"
      allow="clipboard-write"
      class="support-frame">
    </iframe>
  `,
  styles: [`
    .support-frame {
      display: block;
      width: 100%;
      height: calc(100vh - 64px);
      border: 0;
    }
  `],
})
export class SupportChatComponent {
  supportUrl: SafeResourceUrl;

  constructor(sanitizer: DomSanitizer) {
    const params = new URLSearchParams({
      profile: 'YOUR_EMBED_KEY',
      lang: 'vi',
    });

    this.supportUrl = sanitizer.bypassSecurityTrustResourceUrl(
      `https://chat.example.com/ezychat/support?`
    );
  }
}

Đăng xuất

1. Client yêu cầu xóa access token.
2. Cookie phiên bị thu hồi.
3. Iframe tải lại.
4. Form đăng nhập xuất hiện.

Giao diện cá nhân

• Bật hoặc tắt chế độ tối.
• Chọn màu chủ đạo.
• Trở về màu mặc định.

• Tùy chọn được giữ khi tải lại iframe.
• Hai trang quản trị cùng nhúng một máy chủ chat có thể dùng chung lựa chọn.
• Xóa dữ liệu website của máy chủ chat sẽ đặt lại giao diện.
• Trang cha không thể đọc trực tiếp giá trị này khi khác origin.

Kiểm tra sau khi tích hợp

• Iframe tải thành công.
• Không bị CSP hoặc X-Frame-Options chặn.
• Hồ sơ đúng và đang hoạt động.
• Origin trang quản trị được cho phép.
• Form đăng nhập xuất hiện khi chưa có phiên.
• Cookie được giữ sau khi tải lại.
• Tài khoản không có quyền bị từ chối.
• Tài khoản được phân công xem đúng danh sách kênh.
• Danh sách chỉ chứa kênh của hồ sơ.
• Socket chuyển sang trạng thái trực tuyến.
• Có thể nhận và gửi tin.
• Upload tệp hoạt động.
• Lưu trữ và khôi phục hội thoại hoạt động.
• Chế độ tối và màu chủ đạo được lưu.
• Đăng xuất đưa về form đăng nhập.
• Bố cục hoạt động trên màn hình nhỏ.

Xử lý lỗi thường gặp

Iframe trắng hoặc bị từ chối tải

• frame-src không cho phép máy chủ chat.
• Máy chủ trả X-Frame-Options: DENY.
• frame-ancestors không chứa origin trang quản trị.
• URL iframe sai.
• Máy chủ chat không hoạt động.

Báo không tìm thấy hồ sơ

• Khóa nhúng.
• Trạng thái hồ sơ.
• Khoảng trắng thừa trong URL.
• Hồ sơ có bị xóa hay không.

Báo không được phép truy cập

• Có tồn tại trong hệ thống người dùng không.
• Đã được thêm vào hồ sơ chưa.
• Loại thành viên có phải người dùng không.
• Trạng thái thành viên có phải ACTIVATED không.
• Đã được thêm vào các kênh cần xử lý chưa.

Đăng nhập xong lại quay về màn hình đăng nhập

• Cookie thiếu SameSite=None.
• Cookie thiếu Secure.
• Website đang dùng HTTP.
• Trình duyệt chặn third-party cookies.
• iframe thiếu allow-same-origin khi dùng sandbox.

Đăng nhập được nhưng không có hội thoại

• URL có đúng profile không.
• Các kênh có được gắn với hồ sơ đó không.
• Người dùng có phải thành viên kênh không.
• Kênh có đang ở trạng thái phù hợp không.
• Thành viên hồ sơ có được thêm trước khi các kênh được tạo không.

Socket luôn ở trạng thái đang kết nối

• URL WebSocket.
• Chứng chỉ TLS.
• Reverse proxy có hỗ trợ WebSocket upgrade không.
• Access token socket có lấy được không.
• Trình duyệt có chặn ws:// trên trang HTTPS không.

CSS tùy chỉnh không có tác dụng

• Được đặt trong tham số style.
• Đã được URL-encode.
• Chọn đúng selector bên trong màn hình.
• Không bị stylesheet mặc định ghi đè bởi selector mạnh hơn.

Giới hạn hiện tại

• Chưa hỗ trợ nhận phiên đăng nhập từ trang cha qua postMessage.
• Chưa có API SSO riêng dành cho iframe.
• Không tự động dùng phiên quản trị của hệ thống chứa iframe.
• Không có sự kiện công khai báo cho trang cha khi đăng nhập thành công.
• Không có sự kiện thông báo số hội thoại chưa đọc cho trang cha.
• Không có API công khai để trang cha chọn một kênh.
• Không có API công khai để thay đổi hồ sơ sau khi iframe đã tải.
• Không tự thay đổi chiều cao theo vùng chứa.
• CSS tùy chỉnh được truyền qua query string nên không phù hợp với cấu hình quá dài.
• Quyền ban đầu chỉ kiểm tra tài khoản thuộc ít nhất một hồ sơ hoạt động, chưa xác nhận trực tiếp tài khoản thuộc đúng hồ sơ trong URL.
• Người dùng mới thêm vào hồ sơ không tự động được thêm vào các kênh cũ.
• Đăng xuất có thể ảnh hưởng đến các ứng dụng khác dùng chung phiên trên máy chủ chat.

Khuyến nghị triển khai

1. Tạo một hồ sơ riêng cho từng nhóm hỗ trợ.
2. Thêm đúng tài khoản người dùng vào hồ sơ.
3. Dùng một route riêng trong trang quản trị cho iframe.
4. Cấu hình allowlist origin.
5. Dùng HTTPS cho cả hai hệ thống.
6. Cấu hình cookie phù hợp nếu khác origin.
7. Cho phép iframe bằng CSP frame-ancestors.
8. Cho phép máy chủ chat trong frame-src của trang quản trị.
9. Dùng chiều cao theo viewport.
10. Kiểm thử trên các trình duyệt có chính sách cookie nghiêm ngặt.

Kết luận

1. Tạo và kích hoạt hồ sơ chat.
2. Thêm nhân viên dưới dạng thành viên người dùng đang hoạt động.
3. Sao chép support iframe từ trang chi tiết hồ sơ.
4. Đặt iframe vào route quản trị.
5. Cấu hình kích thước phù hợp.
6. Cho phép origin và iframe ở cả hai phía.
7. Kiểm tra cookie đăng nhập và kết nối socket.
8. Xác nhận nhân viên chỉ nhìn thấy các kênh thuộc phạm vi được giao.