Bạn có một trang xem trước giao diện, nhưng câu “thẻ này nhìn hơi chật” không cho lập trình viên biết đó là thẻ nào. Với Browser Annotation API, người xem có thể chọn cả thẻ, gửi kèm tên và dữ kiện cần thiết, rồi chọn phương án mong muốn trước khi góp ý trong ChatGPT. Bản thử cần trang HTTPS hoặc localhost, trình duyệt tích hợp trong ứng dụng ChatGPT desktop được hỗ trợ, và khoảng 20 phút. **Trang web chuẩn bị ngữ cảnh, người dùng quyết định có gửi góp ý hay không.** Mở annotation không tự gửi tin nhắn. Bài [ChatGPT Browser, tiện ích và Computer Use](/blog/dung-chatgpt-browser-tien-ich-trinh-duyet-va-computer-use-dung-viec) giúp phân biệt các cách lấy ngữ cảnh; bài này tập trung vào API cho website của bạn. ## 🧰 Chuẩn bị Công cụ là [Browser Annotation API trong ChatGPT Learn](https://learn.chatgpt.com/docs/annotations-extensibility). Theo tài liệu OpenAI cập nhật cho bản phát hành DevDay 2026 trở đi, API được gắn ở `document.oai.annotation` trong **trình duyệt tích hợp của ứng dụng ChatGPT desktop**. Trang phải là trang cấp cao nhất và dùng HTTPS hoặc localhost. Đừng mặc định rằng Chrome bình thường, iframe, hay mọi phiên bản ứng dụng đều có API. Kiểm tra sự tồn tại của từng phương thức trước khi gọi. **Giới hạn quan trọng:** OpenAI nói API hiện chưa có trong workspace ChatGPT Enterprise hoặc Edu. Nếu nhóm chỉ dùng hai loại này, ví dụ dưới đây để tham khảo thiết kế. Hãy xác nhận môi trường trước khi triển khai. Chuẩn bị trang thử có hai thẻ xem trước và một nút góp ý. Dùng dữ liệu giả; đừng đưa bí mật vào HTML. Nếu chỉ cần chụp cửa sổ để soạn nháp, xem [quy trình ChatGPT Desktop và Appshots](/blog/dung-chatgpt-tren-may-tinh-de-thu-thap-ngu-canh-ung-dung-va-soan-ban-cap-nhat-cong-viec-co-kiem-tra). ## 🪜 Làm từng bước ### 1. Biến mỗi thẻ thành một đối tượng có tên Trong Annotation mode, trình duyệt có thể chọn phần tử DOM theo hành vi mặc định. Nhưng với một thẻ gồm tiêu đề, mô tả và nút, người xem thường muốn nhận xét **cả thẻ**. Đặt `oai-annotation-container` trên vùng bao và `oai-annotatable` trên từng thẻ. Giá trị của thuộc tính thứ hai là tên mà người dùng và mô hình nhìn thấy, nên hãy đặt tên phân biệt được hai thẻ. ```html

Tóm tắt

Ba chỉ số quan trọng của tuần này.

``` Trong Annotation mode, trỏ vào tiêu đề hoặc mô tả. Cả thẻ cần được tô sáng. `oai-annotatable` đứng riêng ngoài container không đổi cách chọn. Vùng ngoài container giữ hành vi mặc định. Nếu cần góp ý cho **một câu chữ**, dùng `oai-annotation-container-text` trên vùng văn bản. Người xem kéo chuột chọn chữ; cú nhấp đơn lẻ không tạo annotation. Nếu một phần tử có cả thuộc tính text và DOM, cách chọn văn bản được ưu tiên. ### 2. Gửi thêm ngữ cảnh vừa đủ Tên “Thẻ hồ sơ” chưa nói đây là bản thử ở màn hình nào. Có thể thêm dữ kiện nhỏ, không nhạy cảm, bằng `oai-annotation-metadata` trên đối tượng được đánh dấu: ```html ``` Đoạn này **thay thế** thẻ hồ sơ ở bước 1, không tạo thêm `id` trùng. Metadata đi cùng annotation vào cuộc hội thoại. OpenAI giới hạn JSON phẳng ở sáu thuộc tính, khóa tối đa 64 ký tự, chuỗi tối đa 256 ký tự và tổng dung lượng tối đa 2.048 byte. Không dùng mảng hoặc đối tượng lồng nhau; dữ liệu sai có thể bị bỏ qua. Chỉ dùng dữ kiện người dùng **và** ChatGPT đều được phép thấy. Metadata làm góp ý rõ hơn, không cấp quyền đọc cơ sở dữ liệu hay thực hiện hành động. ### 3. Mở annotation từ nút của trang Trang có thể đặt nút “Góp ý” ngay cạnh nội dung. Sau khi các phần tử đã tồn tại trong DOM, thêm mã sau. Nó ẩn nút nếu trình duyệt không hỗ trợ `request()`, rồi gọi phương thức **trong chính thao tác nhấp của người dùng**: ```js const card = document.getElementById("profile-card"); const button = document.getElementById("discuss-profile"); const annotation = document.oai?.annotation; button.hidden = typeof annotation?.request !== "function"; button.addEventListener("click", () => { if (typeof annotation?.request !== "function") return; const result = annotation.request(card, { initialComment: "Hãy góp ý về độ rõ ràng của thẻ hồ sơ này.", }); if (!result.accepted) { console.info("Annotation request was not accepted."); } }); ``` `result.accepted` cho biết trình duyệt nhận yêu cầu, **không chứng minh** trình biên tập đã mở hoặc tin nhắn đã gửi. `initialComment` có thể sửa và dài tối đa 240 đơn vị UTF-16. Đừng `await` mạng trước `request()`, vì có thể mất ngữ cảnh cú nhấp. Yêu cầu có thể bị từ chối khi trình biên tập đang mở hoặc ChatGPT đang điều khiển trình duyệt. Nếu cần chọn một đoạn văn, `request()` nhận DOM `Range` có chữ nhìn thấy trong tài liệu hiện tại, tối đa 20.000 đơn vị UTF-16. `mode: "advanced"` không dùng cho vùng chữ. Nút góp ý không phải nút gửi ChatGPT; người dùng thực hiện bước gửi cuối. ### 4. Cho người xem chọn phương án trước khi góp ý Khi vấn đề có vài phương án rõ ràng, bạn có thể đăng ký một control kiểu `select`. Ví dụ, nhóm thiết kế muốn người xem chọn mật độ hiển thị của thẻ. Thêm mã này sau khi tạo `card` ở bước 3: ```js let registration; if (typeof annotation?.registerControls === "function") { try { registration = annotation.registerControls({ targets: card, controlsHeading: "Cách trình bày thẻ", controlsMode: "replace", controls: [ { type: "select", label: "Mật độ thông tin", callback: "layoutDensity", options: [ { label: "Thoáng", value: "relaxed" }, { label: "Gọn", value: "compact" }, ], defaultValue: "relaxed", }, ], }); } catch (error) { console.error("Could not register annotation controls.", error); } } function cleanupAnnotationControls() { registration?.dispose(); } ``` `controlsMode: "replace"` hiển thị control do bạn đăng ký cho thẻ này thay cho control tích hợp; `"extend"` hiển thị cả hai. Mẫu trên chỉ **thu thập lựa chọn**, chưa thay đổi giao diện ngay. Vì không có `currentValue`, lựa chọn ban đầu cũng được đưa vào annotation ngay cả khi người xem không đổi nó. ChatGPT và lịch sử annotation nhận nhãn nhìn thấy “Thoáng” hoặc “Gọn”, không nhận `value` nội bộ làm câu chữ lựa chọn. Hãy đặt nhãn sao cho một người chưa đọc mã vẫn hiểu. Muốn xem trước khoảng đệm hoặc màu sắc, dùng control `range` hoặc `color` và xử lý `oaiannotationcontrolchange`. Sự kiện có `preview`, `preview-original`, `reset`; áp dụng giá trị tương ứng cho cả ba và khôi phục giao diện khi hủy. Preview **không tự lưu**. Một registration có tối đa 12 control; định nghĩa sai có thể ném lỗi đồng bộ. Khi gỡ thành phần, gọi `dispose()` và xóa listener hoặc trạng thái preview do trang tạo. ### 5. Kiểm tra như một người dùng thật Mở trang thử trong trình duyệt tích hợp của ChatGPT desktop được hỗ trợ. Bật Annotation mode từ giao diện trình duyệt. Chọn lần lượt hai thẻ và xác nhận tên, vùng tô sáng, metadata. Nhấn nút góp ý, sửa lời nhắc, chọn “Gọn”, lưu annotation rồi mở lại từ phần xem trước tệp đính kèm. Cuối cùng, gửi cùng một tin nhắn thử để xác nhận ChatGPT nhận đúng thẻ, dữ kiện và nhãn lựa chọn. Mở cùng trang bằng trình duyệt không có API. Nút đặc biệt phải ẩn; hai thẻ vẫn hoạt động. Thử gỡ thành phần và gọi hàm dọn dẹp. Nếu thêm preview CSS, đổi lựa chọn rồi hủy để kiểm tra trạng thái ban đầu. **Mẫu mã được đối chiếu tài liệu và kiểm tra cú pháp JavaScript, nhưng chưa thử tương tác trong tài khoản ChatGPT desktop thực.** Cần kiểm tra bước này trước khi đưa vào sản phẩm. ## ✅ Kết quả mẫu Người xem chọn “Thẻ hồ sơ”, chọn “Gọn”, rồi viết: “Vai trò thành viên đang chìm, hãy làm nổi bật hơn”. Cuộc hội thoại nhận tên thẻ, metadata `screen: Trang nhóm`, `variant: Bản xem trước` và nhãn “Gọn”. Người phát triển hiểu đúng biến thể. Đây là **kết quả kỳ vọng theo đặc tả**, chưa phải log chạy thực tế. ## 💡 Mẹo để kết quả tốt hơn Bắt đầu từ một nhóm thẻ và một control. Đặt tên `oai-annotatable` theo ngôn ngữ người dùng, tránh `CardV2`. Metadata giải nghĩa màn hình hoặc biến thể, không chứa toàn bộ hồ sơ. Annotation chỉ cung cấp lựa chọn và góp ý; để AI **thao tác trên website** cần khả năng khác như Site tools. Nếu tích hợp Codex vào công cụ nội bộ, xem [Codex SDK và App Server](/blog/dung-codex-sdk-hay-app-server-de-them-tro-ly-ra-ma-vao-cong-cu-noi-bo). Với ứng dụng dựng lại DOM sau mỗi lần đổi trạng thái, hãy giữ registration handle để cập nhật target hoặc dispose khi thành phần bị gỡ. Danh sách phần tử được lấy tại thời điểm đăng ký, không tự theo các phần tử mới. Đừng đặt `currentValue` bằng trạng thái preview tạm thời; nó phải là giá trị thường của ứng dụng, kể cả chỉnh sửa chưa lưu. Quy tắc này giữ phép so sánh “trước và sau” đúng khi người xem thay đổi control. ## ⚠️ Giới hạn cần biết Tính năng phụ thuộc phiên bản ứng dụng, quyền trang và cài đặt riêng cho website; một số yêu cầu do trang khởi tạo có thể cần người dùng cấp quyền. API được thiết kế cho tài liệu cấp cao nhất, bảo mật, trong trình duyệt tích hợp; iframe không phải nơi để thử mẫu này. Những ràng buộc cụ thể và giao diện cấp quyền có thể thay đổi, nên kiểm tra lại tài liệu OpenAI trước khi triển khai chính thức. Annotation mang nội dung được chọn và metadata vào cuộc hội thoại. Hãy xem đây là một đường chia sẻ dữ liệu, kiểm tra chính sách của tổ chức và tránh đưa bí mật vào thuộc tính HTML. Control trong ví dụ là đề xuất cho cuộc thảo luận, không tự sửa mã, không lưu cài đặt và không gửi email. Nếu góp ý liên quan quyền truy cập, giá, pháp lý hoặc quyết định sản phẩm, người có trách nhiệm vẫn phải rà lại trước khi thực hiện. ## ❓ Câu hỏi thường gặp **Tôi có thể dùng API này trong Chrome thông thường không?** Tài liệu mô tả `document.oai.annotation` trong trình duyệt tích hợp của ứng dụng ChatGPT desktop được hỗ trợ. Luôn kiểm tra tính năng; đừng giả định Chrome thông thường có namespace đó. **ChatGPT Enterprise hoặc Edu có dùng được không?** Theo trang tài liệu OpenAI hiện tại, Browser Annotation API chưa có trong hai loại workspace này. Cần kiểm tra lại khi OpenAI thay đổi phạm vi phát hành. **Bấm nút góp ý có tự gửi tin nhắn cho ChatGPT không?** Không. `request()` xin mở annotation; người dùng vẫn quyết định chỉnh sửa, lưu và gửi. `accepted: true` cũng không phải bằng chứng tin đã gửi. **Có thể chọn một câu thay vì cả thẻ không?** Có. Dùng `oai-annotation-container-text` để kéo chọn chữ trong Annotation mode, hoặc gọi `request()` với một DOM `Range` hợp lệ từ nút của trang. **Control có tự lưu thay đổi lên website không?** Không. Control có thể thu lựa chọn hoặc cho xem trước qua sự kiện. Thay đổi thật cần luồng lưu của ứng dụng và sự kiểm tra của người chịu trách nhiệm. Nguồn chính: [Annotations Extensibility](https://learn.chatgpt.com/docs/annotations-extensibility), tài liệu chính thức OpenAI Learn, đối chiếu ngày 5/10/2026. #ChatGPT #Annotations #Website #AIChoLapTrinh #VibeCoding

Hồ sơ

Tóm tắt

Hồ sơ

#Annotations

Dùng ChatGPT Annotations để nhận góp ý đúng thành phần giao diện và đúng ngữ cảnh