Nội dung mô tả
Dùng API chrome.cookies
để truy vấn và sửa đổi cookie, cũng như nhận thông báo khi chúng thay đổi.
Quyền
cookies
Để sử dụng API cookie, hãy khai báo quyền "cookies"
trong tệp kê khai cùng với quyền của máy chủ cho mọi máy chủ có cookie mà bạn muốn truy cập. Ví dụ:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
Phân vùng
Cookie phân vùng cho phép trang web đánh dấu rằng một số cookie nhất định cần được khoá dựa trên nguồn gốc của khung cấp cao nhất. Ví dụ: nếu trang web A được nhúng bằng iframe trong trang web B và trang web C, thì các phiên bản được nhúng của cookie được phân vùng từ A có thể có các giá trị khác nhau trên B và C.
Theo mặc định, tất cả phương thức API đều hoạt động trên cookie không được phân vùng. Bạn có thể dùng thuộc tính partitionKey
để ghi đè hành vi này.
Để biết thông tin chi tiết về tác động chung của việc phân vùng tiện ích, hãy xem bài viết Bộ nhớ và cookie.
Ví dụ
Bạn có thể tìm thấy một ví dụ đơn giản về cách sử dụng API cookie trong thư mục examples/api/cookies. Để biết các ví dụ khác và để được trợ giúp khi xem mã nguồn, hãy xem phần Mẫu.
Loại
Cookie
Biểu thị thông tin về cookie HTTP.
Thuộc tính
-
tên miền
string
Miền của cookie (ví dụ: "www.google.com", "example.com").
-
expirationDate
số không bắt buộc
Ngày hết hạn của cookie dưới dạng số giây kể từ thời gian bắt đầu của hệ thống UNIX. Không được cung cấp cho cookie phiên.
-
hostOnly
boolean
Đúng nếu cookie là cookie chỉ dành cho máy chủ lưu trữ (tức là máy chủ lưu trữ yêu cầu phải khớp chính xác với miền của cookie).
-
httpOnly
boolean
Đúng nếu cookie được đánh dấu là HttpOnly (tức là các tập lệnh phía máy khách không thể truy cập cookie).
-
tên
string
Tên của cookie.
-
partitionKey
CookiePartitionKey không bắt buộc
Chrome 119 trở lênKhoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Được phân vùng.
-
path
string
Đường dẫn của cookie.
-
sameSiteChrome 51 trở lên
Trạng thái cùng trang web của cookie (tức là cookie có được gửi cùng với yêu cầu trên nhiều trang web hay không).
-
bảo mật
boolean
Đúng nếu cookie được đánh dấu là Bảo mật (tức là phạm vi của cookie bị giới hạn đối với các kênh bảo mật, thường là HTTPS).
-
phiên hoạt động
boolean
"True" nếu cookie là cookie của phiên, chứ không phải cookie cố định có ngày hết hạn.
-
storeId
string
Mã cửa hàng cookie chứa cookie này, như được cung cấp trong getAllCookieStores().
-
value
string
Giá trị của cookie.
CookieDetails
Thông tin chi tiết để xác định cookie.
Thuộc tính
-
tên
string
Tên của cookie cần truy cập.
-
partitionKey
CookiePartitionKey không bắt buộc
Chrome 119 trở lênKhoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Được phân vùng.
-
storeId
chuỗi không bắt buộc
Mã của kho cookie mà tại đó cần tìm cookie. Theo mặc định, kho cookie của ngữ cảnh thực thi hiện tại sẽ được sử dụng.
-
url
string
URL mà cookie để truy cập được liên kết. Đối số này có thể là một URL đầy đủ, trong trường hợp đó, mọi dữ liệu theo đường dẫn URL (ví dụ: chuỗi truy vấn) sẽ bị bỏ qua. Nếu quyền của máy chủ cho URL này không được chỉ định trong tệp kê khai, lệnh gọi API sẽ không thành công.
CookiePartitionKey
Đại diện cho khoá phân vùng của một cookie được phân vùng.
Thuộc tính
-
topLevelSite
chuỗi không bắt buộc
Trang web cấp cao nhất có cookie được phân vùng.
CookieStore
Đại diện cho kho cookie trong trình duyệt. Ví dụ: cửa sổ chế độ ẩn danh sử dụng kho lưu trữ cookie riêng biệt từ cửa sổ không ẩn danh.
Thuộc tính
-
id
string
Giá trị nhận dạng duy nhất của cửa hàng bánh quy.
-
tabIds
số[]
Giá trị nhận dạng của mọi thẻ trình duyệt có chung kho cookie này.
OnChangedCause
Lý do cơ bản dẫn đến thay đổi của cookie. Nếu cookie đã được chèn hoặc bị xoá thông qua một lệnh gọi rõ ràng đến "chrome.cookie.remove", thì "nguyên nhân" sẽ là "phản cảm". Nếu một cookie tự động bị xoá do hết hạn, thì "nguyên nhân" sẽ là "đã hết hạn". Nếu cookie đã bị xoá do bị ghi đè do ngày hết hạn đã hết hạn, thì "nguyên nhân" sẽ được đặt thành "expiry_overwrite". Nếu một cookie bị xoá tự động do thu gom rác, thì "nguyên nhân" sẽ bị "loại bỏ". Nếu một cookie tự động bị xoá do lệnh gọi "set" ghi đè cookie đó, thì "nguyên nhân" sẽ là "ghi đè". Hãy lên kế hoạch phản hồi cho phù hợp.
Liệt kê
SameSiteStatus
Trạng thái "SameSite" của cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' tương ứng với cookie được đặt với 'SameSite=None', 'lax' thành 'SameSite=Lax' và 'strict' thành 'SameSite=Strict'. "unspecified" tương ứng với tập hợp cookie không có thuộc tính SameSite.
Liệt kê
"no_restriction"
"lax"
Phương thức
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
Truy xuất thông tin về một cookie. Nếu có nhiều cookie cùng tên tồn tại cho URL đã chọn, cookie có đường dẫn dài nhất sẽ được trả về. Đối với những cookie có cùng độ dài đường dẫn, cookie có thời gian tạo sớm nhất sẽ được trả về.
Tham số
Giá trị trả về
-
Promise<Cookie | undefined>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
Truy xuất tất cả cookie từ một kho lưu trữ cookie khớp với thông tin đã cho. Các cookie được trả về sẽ được sắp xếp, trong đó những cookie có đường dẫn dài nhất sẽ được sắp xếp trước. Nếu nhiều cookie có cùng độ dài đường dẫn thì những cookie có thời gian tạo sớm nhất sẽ được ưu tiên trước. Phương thức này chỉ truy xuất cookie cho những miền mà tiện ích có quyền lưu trữ.
Tham số
-
chi tiết
đối tượng
Thông tin để lọc cookie đang được truy xuất.
-
tên miền
chuỗi không bắt buộc
Giới hạn cookie được truy xuất cho những cookie có miền trùng khớp hoặc là miền con của miền này.
-
tên
chuỗi không bắt buộc
Lọc cookie theo tên.
-
partitionKey
CookiePartitionKey không bắt buộc
Chrome 119 trở lênKhoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Được phân vùng.
-
path
chuỗi không bắt buộc
Giới hạn cookie được truy xuất cho những cookie có đường dẫn khớp chính xác với chuỗi này.
-
bảo mật
boolean không bắt buộc
Lọc cookie theo thuộc tính Secure (Bảo mật) tương ứng.
-
phiên hoạt động
boolean không bắt buộc
Lọc ra cookie phiên so với cookie cố định.
-
storeId
chuỗi không bắt buộc
Kho lưu trữ cookie để truy xuất cookie. Nếu bị bỏ qua, kho lưu trữ cookie của ngữ cảnh thực thi hiện tại sẽ được sử dụng.
-
url
chuỗi không bắt buộc
Giới hạn cookie được truy xuất thành những cookie phù hợp với URL đã cho.
-
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(cookies: Cookie[]) => void
-
cookie
Cookie[]
Tất cả cookie hiện có và chưa hết hạn khớp với thông tin về cookie đã cho.
-
Giá trị trả về
-
Promise<Cookie[]>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
Liệt kê tất cả các kho lưu trữ cookie hiện có.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(cookieStores: CookieStore[]) => void
-
cookieStores
Tất cả cửa hàng cookie hiện có.
-
Giá trị trả về
-
Promise<CookieStore[]>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
Xoá cookie theo tên.
Tham số
-
chi tiết
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(details?: object) => void
-
chi tiết
đối tượng không bắt buộc
Chứa thông tin chi tiết về cookie đã bị xoá. Nếu không xoá được vì bất kỳ lý do gì, giá trị này sẽ là "rỗng" và
runtime.lastError
sẽ được đặt.-
tên
string
Tên của cookie đã bị xoá.
-
partitionKey
CookiePartitionKey không bắt buộc
Chrome 119 trở lênKhoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Được phân vùng.
-
storeId
string
Mã của kho lưu trữ cookie mà từ đó cookie bị xoá.
-
url
string
URL được liên kết với cookie đã bị xoá.
-
-
Giá trị trả về
-
Promise<object | undefined>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
set()
chrome.cookies.set(
details: object,
callback?: function,
)
Đặt một cookie có dữ liệu cookie đã cho; có thể ghi đè các cookie tương đương nếu có.
Tham số
-
chi tiết
đối tượng
Thông tin chi tiết về cookie đang được đặt.
-
tên miền
chuỗi không bắt buộc
Miền của cookie. Nếu bị bỏ qua, cookie này sẽ trở thành cookie chỉ lưu trữ.
-
expirationDate
số không bắt buộc
Ngày hết hạn của cookie dưới dạng số giây kể từ thời gian bắt đầu của hệ thống UNIX. Nếu bị bỏ qua, cookie này sẽ trở thành cookie phiên.
-
httpOnly
boolean không bắt buộc
Liệu cookie có được đánh dấu là HttpOnly hay không. Giá trị mặc định là false.
-
tên
chuỗi không bắt buộc
Tên của cookie. Trống theo mặc định nếu bị bỏ qua.
-
partitionKey
CookiePartitionKey không bắt buộc
Chrome 119 trở lênKhoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Được phân vùng.
-
path
chuỗi không bắt buộc
Đường dẫn của cookie. Giá trị mặc định là phần đường dẫn của tham số URL.
-
sameSite
SameSiteStatus không bắt buộc
Chrome 51 trở lênTrạng thái cùng trang web của cookie. Giá trị mặc định là "không được chỉ định", tức là nếu bị bỏ qua, cookie sẽ được đặt mà không chỉ định thuộc tính SameSite.
-
bảo mật
boolean không bắt buộc
Liệu cookie có được đánh dấu là Bảo mật hay không. Giá trị mặc định là false.
-
storeId
chuỗi không bắt buộc
Mã của kho cookie mà bạn muốn đặt cookie. Theo mặc định, cookie được đặt trong kho lưu trữ cookie của ngữ cảnh thực thi hiện tại.
-
url
string
URI yêu cầu để liên kết với chế độ cài đặt cookie. Giá trị này có thể ảnh hưởng đến miền mặc định và các giá trị đường dẫn của cookie đã tạo. Nếu quyền của máy chủ cho URL này không được chỉ định trong tệp kê khai, lệnh gọi API sẽ không thành công.
-
value
chuỗi không bắt buộc
Giá trị của cookie. Trống theo mặc định nếu bị bỏ qua.
-
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(cookie?: Cookie) => void
-
bánh quy
Cookie không bắt buộc
Chứa thông tin chi tiết về cookie đã được đặt. Nếu không thiết lập được vì bất kỳ lý do gì, giá trị này sẽ là "rỗng" và
runtime.lastError
sẽ được đặt.
-
Giá trị trả về
-
Promise<Cookie | undefined>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
Sự kiện
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
Được kích hoạt khi cookie được đặt hoặc bị xoá. Trong một trường hợp đặc biệt, lưu ý rằng việc cập nhật các thuộc tính của cookie được triển khai dưới dạng quy trình hai bước: trước tiên, cookie cần cập nhật sẽ bị xoá hoàn toàn, tạo ra một thông báo kèm theo "nguyên nhân" là "ghi đè" . Sau đó, hệ thống sẽ viết một cookie mới chứa các giá trị đã cập nhật, tạo thông báo thứ hai kèm theo "nguyên nhân" "rõ ràng".
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(changeInfo: object) => void
-
changeInfo
đối tượng
-
cause
Lý do cơ bản dẫn đến thay đổi của cookie.
-
bánh quy
Thông tin về cookie đã được đặt hoặc bị xoá.
-
đã xóa
boolean
Đúng nếu cookie đã bị xoá.
-
-