k.privacy
Cookie 同意配置读取与第三方脚本 Cookie 检测
| 适用上下文 | 前置条件 | 典型用途 |
|---|---|---|
Api / <script env="server"> / CodeBlock | 已在后台 Cookie 管理 配置横幅(getJSCookies 需出站网络) | 读取当前请求语言下的同意弹窗配置、分类文案与脚本 Cookie 分析 |
快速上手
k.api.get("cookie-consent", () => {
const setting = k.privacy.cookieConsent.setting
return {
enable: setting.enable,
title: setting.cookieText.title,
theme: setting.uI.theme,
closeActionUS: setting.closeButton.getAction("US")
}
})方法速查
| 方法 / 属性 | 说明 | 返回值 |
|---|---|---|
k.privacy.cookieConsent.setting | 获取按当前请求语言本地化后的 Cookie 同意弹窗配置 | CookieConsentSettingViewModel |
setting.closeButton.getAction(countryCode) | 按两位国家/地区代码计算关闭按钮默认动作 | "accept" | "reject" |
k.privacy.cookieConsent.getJSCookies(JSUrl, LoadingUrl?, tag?) | 调用外部无头扫描服务分析第三方脚本写入的 Cookie | CookieItem[] |
概述
k.privacy 提供站点隐私与 Cookie 合规相关的服务端读取能力。通过 k.privacy.cookieConsent,开发者可以在自定义 Cookie 同意横幅模板中读取已按当前请求语言本地化的站点 Cookie 管理配置,或按地区计算关闭按钮的默认隐私行为。
| API | 用途 |
|---|---|
k.privacy.cookieConsent | 读取当前站点的 Cookie 同意弹窗配置、分类文案、关闭动作与第三方脚本 Cookie 分析 |
k.cookie | 读写当前 HTTP 请求/响应中的单个客户端 Cookie(见 k.cookie) |
cookieConsent.setting
获取当前站点在 Kooboo 后台Cookie 管理中配置的 Cookie 同意视图模型,文案、分类名称及 Cookie 描述均已自动解析为当前请求语言文化(culture)。
属性大小写说明
智能提示中,全大写缩写开头的属性首字母为小写(uI、hTML、uRL)。在服务端脚本运行时,setting.uI 与 setting.UI、hTML 与 HTML、uRL 与 URL 访问的是同一属性,而全小写的 setting.ui、html、url 为 undefined。对于多词属性(如 cookieText.title、cookieText.buttons.allowAll、themeOption.primaryColor),可直接使用小驼峰写法。
返回值: CookieConsentSettingViewModel。
k.api.get("cookie-consent-config", () => {
const setting = k.privacy.cookieConsent.setting
return {
enable: setting.enable,
displayRule: setting.displayRule,
categories: setting.category.map((cat) => ({
id: cat.id,
name: cat.name,
required: cat.required,
defaultChecked: cat.defaultChecked
})),
title: setting.cookieText.title,
buttons: {
allowAll: setting.cookieText.buttons.allowAll,
allowSelection: setting.cookieText.buttons.allowSelection,
rejectAll: setting.cookieText.buttons.rejectAll
},
ui: {
typeAndPosition: setting.uI.typeAndPosition,
theme: setting.uI.theme,
floatBall: setting.uI.floatBall,
primaryColor: setting.uI.themeOption.primaryColor
}
}
})closeButton.getAction()
根据访客国家/地区代码返回关闭按钮未作显式选择时的最终生效动作。
- 当
closeButton.action为"default"时,"US"返回"accept",其余国家/地区代码返回"reject"。 - 当
closeButton.action已显式配置为"accept"或"reject"时,直接返回该配置值。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
countryCode | string | 是 | 两位国家/地区代码(如 "US"、"DE"、"CN") |
返回值: string("accept" 或 "reject")。
k.api.get("close-action", () => {
const closeBtn = k.privacy.cookieConsent.setting.closeButton
return {
show: closeBtn.show,
configuredAction: closeBtn.action,
usAction: closeBtn.getAction("US"),
deAction: closeBtn.getAction("DE")
}
})cookieConsent.getJSCookies()
调用外部 Cookie 扫描服务分析指定脚本或外部资源在页面加载时写入的 Cookie 列表。
外部服务依赖与超时说明
该方法通过外部无头浏览器扫描服务执行检测(单次请求超时上限 120 秒),依赖站点所在服务器的出站网络访问以及外部扫描服务的可用性。建议在生产代码中始终使用 try / catch 处理外部服务不可达或启动失败的情况。
参数:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
JSUrl | string | 是 | - | 需要检测的外部脚本或资源 URL |
LoadingUrl | string | 否 | 当前站点 BaseUrl | 模拟加载该资源的宿主页面 URL;当站点未配置 BaseUrl 时默认回退为 "https://www.kooboo.com" |
tag | string | 否 | "script" | 资源加载标签类型(如 "script"、"iframe"、"img"、"link") |
返回值: CookieItem[]。
k.api.get("scan-js-cookies", () => {
const jsUrl = k.request.queryString.get("jsUrl")
if (!jsUrl) {
return { ok: false, message: "jsUrl is required" }
}
try {
const items = k.privacy.cookieConsent.getJSCookies(
jsUrl,
k.site.info.baseUrl,
"script"
)
return { ok: true, items: items }
} catch (error) {
return { ok: false, message: String(error) }
}
})TypeScript 定义
展开完整 TypeScript 定义
interface KPrivacy {
cookieConsent: KCookieConsent;
}
interface KCookieConsent {
setting: CookieConsentSettingViewModel;
getJSCookies(JSUrl: string, LoadingUrl?: string, tag?: string): CookieItem[];
}
interface CookieConsentSettingViewModel {
enable: boolean;
displayRule: DisplayRule;
category: CookieCategoryViewModel[];
cookieText: CookieText;
resource: CategoryResourceViewModel[];
closeButton: closeButtonAction;
uI: CookieUI;
}
interface CookieCategoryViewModel {
id: string;
name: string;
description: string;
required: boolean;
defaultChecked: boolean;
resource: CategoryResourceViewModel[];
}
interface CategoryResourceViewModel {
cookieCategory: string;
uRL: string;
cookieItems: CookieItemViewModel[];
}
interface CookieItemViewModel {
name: string;
description: string;
expireMinutes: number;
}
interface DisplayRule {
isInclude: boolean;
type: string; // "All" | "EU" | "Custom"
countries: any; // 国家代码集合
}
interface closeButtonAction {
show: boolean;
action: string; // "default" | "accept" | "reject"
getAction(countryCode: string): string;
}
interface CookieUI {
customTemplate: boolean;
hTML: string;
typeAndPosition: string; // "banner-bottom" | "banner-top" | "modal-center" | "inline-top" | "inline-bottom"
floatBall: boolean;
theme: string; // "light" | "dark" | "custom"
themeOption: CustomTheme;
}
interface CustomTheme {
primaryColor: string;
backgroundColor: string;
textColor: string;
buttonColor: string;
buttonTextColor: string;
}
interface CookieText {
title: string;
description: string;
introduction: string;
iframeFallback: string;
buttons: ButtonText;
links: LinkText;
}
interface ButtonText {
allowAll: string;
allowSelection: string;
rejectAll: string;
}
interface LinkText {
privacyPolicy: LinkObject;
cookiePolicy: LinkObject;
settings: LinkObject;
}
interface LinkObject {
url: string;
anchorText: string;
}
interface CookieItem {
name: string;
value: string;
domain: string;
path: string;
description: string;
privacyLink: string;
vendor: string;
category: string;
expiresMinutes?: number;
}相关文档
- k.cookie — 读写当前请求与响应的客户端 Cookie
- Cookie 管理(后台设置) — 配置同意横幅、分类、多语言文案与自定义模板