List icon 目录

Cookies

本文档介绍了如何使用 Cookies。

概述

JxBrowser 将处理 cookies 的工作委托给 Chromium Engine。Chromium 负责决定如何从 Web 服务器下载 cookies,从 HTTP 标头中提取它们,并将它们存储在用户数据目录(持久 cookies)中或内存(会话 cookies)中。

CookieStore 类允许您获得,修改和删除 cookies。Cookie 类提供有关特定 cookie 的信息。

要获取特定 ProfileCookieStore,请使用 Profile.cookieStore() 方法。Engine.cookieStore() 方法返回与默认配置文件关联的 CookieStore

要访问 cookie 存储,请使用以下方式:

Java
Kotlin
CookieStore cookieStore = profile.cookieStore();
val cookieStore = profile.cookieStore()

支持的协议

JxBrowser 支持使用以下协议发送的 cookies:

  • HTTP
  • HTTPS
  • WS (WebSocket)
  • WSS (Secured WebSocket)

如果使用不在列表中的协议发送 cookie,例如 ftp://,它将不会被存储在 cookie 存储中。

使用 Cookies

JxBrowser 支持以下几种 cookies:

  • 持久 cookies — 存储在 Chromium 用户数据目录中。如果您删除了 Chromium 用户数据目录,所有持久 cookies 将被移除。
  • 会话 cookies — 存储在应用程序内存中。当应用程序终止时,这些 cookies 将自动删除。
  • 安全 cookies — 只能通过加密连接(即 HTTPS)传输。这样可以减少 cookie 通过窃听被盗取的风险。
  • HttpOnly cookies — 无法通过客户端 API(如 JavaScript)访问。此限制消除了通过跨站脚本 (XSS) 窃取 cookie 的威胁。然而,cookie 仍然易受跨站跟踪 (XST) 和跨站请求伪造 (XSRF) 攻击的影响。

当您修改 cookie 时,请使用 CookieStore.persist() 方法来保存更改。

获取 Cookies

要获取所有 сookies,请使用 cookies() 方法:

Java
Kotlin
cookieStore.cookies().forEach(cookie -> 
        System.out.println("cookie = " + cookie));
cookieStore.cookies().forEach { println("cookie = $it") }

要通过 URL 获取所有 cookies,请使用接受字符串参数的 сookies() 方法:

Java
Kotlin
cookieStore.cookies("https://www.google.com").forEach(cookie -> 
        System.out.println("cookie = " + cookie));
cookieStore.cookies("https://www.google.com").forEach { println("cookie = $it") }

创建 Cookies

持久 Cookies

要创建具有过期时间的持久 cookie,请使用以下代码:

Java
Kotlin
cookieStore.set(Cookie.newBuilder(".google.com")
        .creationTime(creationTime)
        .expirationTime(expirationTime)
        .name("name")
        .value("value")
        .path("/")
        .build());
cookieStore.persist();
cookieStore.set(Cookie.newBuilder(".google.com")
        .creationTime(creationTime)
        .expirationTime(expirationTime)
        .name("name")
        .value("value")
        .path("/")
        .build())
cookieStore.persist()

会话 Cookies

要创建会话 cookie,请使用以下代码:

Java
Kotlin
cookieStore.set(Cookie.newBuilder(".google.com")
        .name("name")
        .value("value")
        .path("/")
        .build());
cookieStore.persist();
cookieStore.set(Cookie.newBuilder(".google.com")
        .name("name")
        .value("value")
        .path("/")
        .build())
cookieStore.persist()

删除 Cookies

要删除所有 cookies,请使用 deleteAll() 方法:

Java
Kotlin
int numberOfDeletedCookies = cookieStore.deleteAll();
cookieStore.persist();
val numberOfDeletedCookies = cookieStore.deleteAll()
cookieStore.persist()

要删除一个 cookie,请使用 delete(Cookie) 方法。以下代码逐个删除所有 cookies:

Java
Kotlin
cookieStore.cookies().forEach(cookieStore::delete);
cookieStore.persist();
cookieStore.cookies().forEach(cookieStore::delete)
cookieStore.persist()

抑制 Cookies

您可以使用 NetworkCanSetCookieCallbackCanGetCookiesCallback 回调来控制所有传入和传出的 cookies。

要抑制传入的 cookies,请使用以下代码:

Java
Kotlin
network.set(CanSetCookieCallback.class, params -> Response.cannot());
network.set(CanSetCookieCallback::class.java, CanSetCookieCallback { Response.cannot() })

要抑制传出的 cookies,请使用以下代码:

Java
Kotlin
network.set(CanGetCookiesCallback.class, params -> Response.cannot());
network.set(CanGetCookiesCallback::class.java, CanGetCookiesCallback { Response.cannot() })

加密

JxBrowser 默认支持 cookie 加密。它使用 Chromium 的 cookies 加密例程,因此 cookies 的存储方式与 Chromium 中的完全相同。

Linux

在 Linux 上,JxBrowser 使用 GNOME Keyring 或 KWallet 来加密 cookies。库会自动选择使用哪个存储。您可以在构建 Engine 时通过适当的选项手动指定要使用的存储。例如:

Java
Kotlin
Engine engine = Engine.newInstance(EngineOptions.newBuilder(...)
        .passwordStore(PasswordStore.GNOME_KEYRING)
        .build());
val engine = Engine.newInstance(EngineOptions.newBuilder(...)
        .passwordStore(PasswordStore.GNOME_KEYRING)
        .build())

Windows

在 Windows 上,JxBrowser 仅使用 DPAPI 来加密 cookies。目前没有其他替代方案。

macOS

在 macOS 上,JxBrowser 使用存储在 Keychain 应用程序中的私钥,通过 AES(高级加密标准)进行加密 cookies。

分区状态

JxBrowser 支持具有分区状态的 cookie。分区 cookie 是具有 Partitioned 属性的 Secure cookie,可在另一个嵌入的 Frame 上下文中设置:

Java
Kotlin
Cookie cookie = cookieStore.cookies().get(0);
cookie.partitionKey().ifPresent(partitionKey -> {
    String topLevelSite = partitionKey.site();
    boolean thirdParty = partitionKey.isThirdParty();
});
val cookie = cookieStore.cookies()[0]
cookie.partitionKey().ifPresent { partitionKey ->
    val topLevelSite = partitionKey.site()
    val thirdParty = partitionKey.isThirdParty
}

与常规的第三方 Cookie 不同,分区 Cookie 无法跟踪用户并整合来自众多不相关的顶级网站的用户信息。