4.6 Khắc Phục Sự Cố & Câu Hỏi Thường Gặp (FAQ)

Trong quá trình tích hợp Chatbot Widget lên hệ thống Web hoặc CRM của doanh nghiệp, quý kỹ sư có thể gặp một số tình huống đặc thù liên quan đến chính sách bảo mật trình duyệt, thứ tự tải script hoặc xung đột giao diện. Tài liệu này cung cấp các giải pháp chuẩn mực để xử lý nhanh chóng.

4.6.1 Sự Cố Content Security Policy (CSP)

Hiện tượng:

Console trình duyệt báo lỗi đỏ:

Refused to frame 'https://...' because it violates the following Content Security Policy directive: "frame-src 'self' ..." hoặc Refused to load the script 'https://...' because it violates the directive: "script-src ..."

Nguyên nhân:

Host App có cài đặt tiêu đề HTTP header Content-Security-Policy chặn việc nạp script từ CDN ngoài hoặc chặn nhúng Iframe từ các tên miền lạ.

Cách khắc phục:

Bổ sung các tên miền của Pango Chat Widget vào chính sách CSP trên Web Server (Nginx, Cloudflare, Apache, hoặc thẻ <meta>):

Content-Security-Policy: 
  default-src 'self';
  script-src 'self' https://pango-chat-widget.pages.dev https://cps-ai-widget.mydatalakes.com https://vus-staging.pango-chat-widget-1aj.pages.dev;
  frame-src 'self' https://pango-chat-widget.pages.dev https://cps-ai-widget.mydatalakes.com https://vus-staging.pango-chat-widget-1aj.pages.dev;
  connect-src 'self' https://*.firebaseio.com wss://*.firebaseio.com https://knowledgebase-svc.mydatalakes.com;

4.6.2 Lỗi window.pcw is undefined

Hiện tượng:

Khi gọi window.pcw.init() hoặc window.pcw.setPayload(...), trình duyệt báo lỗi:

Uncaught TypeError: Cannot read properties of undefined (reading 'init')

Nguyên nhân:

Thẻ script SDK được nạp với thuộc tính async hoặc defer, dẫn đến việc mã JavaScript của Host App thực thi trước khi script widget.js kịp tải về và khai báo biến toàn cục.

Cách khắc phục:

Triển khai cơ chế chờ hoặc lắng nghe sự kiện load của thẻ script:

function ensurePangoWidgetReady(callback) {
  if (window.pcw) {
    callback(window.pcw);
  } else {
    // Thử lại sau mỗi 50ms (tối đa 5 giây)
    let attempts = 0;
    const interval = setInterval(() => {
      attempts++;
      if (window.pcw) {
        clearInterval(interval);
        callback(window.pcw);
      } else if (attempts > 100) {
        clearInterval(interval);
        console.error("Pango Widget script failed to load after 5 seconds.");
      }
    }, 50);
  }
}

// Sử dụng an toàn:
ensurePangoWidgetReady((widget) => {
  widget.init();
  widget.setPayload({ conversation: { conversationId: "123" } });
});

4.6.3 Xung Đột Thứ Tự Lớp Hiển Thị (Z-Index Conflicts)

Hiện tượng:

Bong bóng chat hoặc khung chat bị chìm xuống phía sau các cửa sổ Modal Popup, Menu trượt hoặc thanh Header cố định của Host App.

Nguyên nhân:

Một số framework CSS (như Bootstrap, Ant Design, Material UI) gán z-index rất cao cho các lớp phủ (overlay) hoặc dialog modal.

Cách khắc phục:

• Iframe của Pango Chat Widget mặc định sở hữu z-index: 999999 để đảm bảo luôn hiển thị trên cùng.
• Nếu Host App có Modal cần che phủ toàn màn hình bao gồm cả Widget khi thực hiện thanh toán, bạn chỉ cần gọi window.pcw.hide() khi Modal mở và window.pcw.show() khi Modal đóng.

4.6.4 Xử Lý Bàn Phím Ảo Trên Thiết Bị Di Động

Hiện tượng:

Trên iPhone (iOS Safari) hoặc Android Chrome, khi người dùng chạm vào ô nhập tin nhắn trong Widget, bàn phím ảo đẩy lên làm vỡ khung hình hoặc thanh nhập liệu bị che khuất.

Cách xử lý:

Pango Widget sử dụng đơn vị chiều cao động 100dvh (Dynamic Viewport Height) và tự động lắng nghe sự kiện visualViewport.resize để co giãn chiều cao khung chat chính xác theo khoảng trống thực tế còn lại khi bàn phím ảo xuất hiện. Kỹ sư tích hợp không cần can thiệp bất kỳ dòng mã CSS nào.

4.6.5 Câu Hỏi Thường Gặp (FAQ)

Q: Widget có làm chậm tốc độ tải trang (Page Load Speed / Core Web Vitals) không?

A: Hoàn toàn không. Tệp script khởi tạo ban đầu có kích thước chỉ khoảng 12KB được nén gzip và tải hoàn toàn bất đồng bộ (type="module"). Toàn bộ thư viện giao diện, kết nối Firebase và font chữ chỉ được nạp sau khi người dùng chủ động click mở chat.

Q: Widget có lưu trữ cookie hoặc theo dõi người dùng trái phép không?

A: Không. Widget tuân thủ nghiêm ngặt chuẩn GDPR và bảo mật thông tin cá nhân. Mọi dữ liệu phiên chỉ được lưu trong sessionStorage tạm thời của Iframe và tự động dọn dẹp khi đóng tab trình duyệt hoặc gọi window.pcw.destroy().

Q: Một website có thể tích hợp nhiều Widget khác nhau không?

A: Bạn hoàn toàn có thể khởi tạo lại widget với mã cấu hình hoặc token mới bằng cách gọi window.pcw.destroy() rồi khởi tạo lại với setPayload tương ứng với từng phân hệ.