Skip to content

k.privacy ​

Cookie 同意配置读取与第三方脚本 Cookie 检测

适用上下文前置条件典型用途
Api / <script env="server"> / CodeBlock已在后台 Cookie 管理 配置横幅(getJSCookies 需出站网络)读取当前请求语言下的同意弹窗配置、分类文案与脚本 Cookie 分析

快速上手 ​

js
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?)调用外部无头扫描服务分析第三方脚本写入的 CookieCookieItem[]

概述 ​

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。

js
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" 时,直接返回该配置值。

参数:

参数类型必填说明
countryCodestring是两位国家/地区代码(如 "US"、"DE"、"CN")

返回值: string("accept" 或 "reject")。

js
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 处理外部服务不可达或启动失败的情况。

参数:

参数类型必填默认值说明
JSUrlstring是-需要检测的外部脚本或资源 URL
LoadingUrlstring否当前站点 BaseUrl模拟加载该资源的宿主页面 URL;当站点未配置 BaseUrl 时默认回退为 "https://www.kooboo.com"
tagstring否"script"资源加载标签类型(如 "script"、"iframe"、"img"、"link")

返回值: CookieItem[]。

js
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 定义
ts
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;
}

相关文档 ​