Cookie
菜单:站点设置 → Cookie 管理
深链:/_Admin/system/cookie?SiteId={站点GUID}
Tab 深链:tab=basic/categories/content/scripts/reports
Cookie 管理用于配置访客前台看到的 Cookie 同意弹窗:启用范围、显示样式、多语言文案、Cookie 分类、外部资源归类与同意统计。后台保存的是站点级 CookieConsentSetting;前台读写单个 Cookie 的脚本能力请看 k.cookie。
权限
| 操作 | 权限 |
|---|---|
| 打开 Cookie 管理 页面 | site·edit |
| 底部 保存、保存并预览 | site·edit |
| 添加 / 编辑分类、内容、资源与 Cookie 项 | site·edit(先写入当前表单,仍需底部保存) |
| 资源管理列表 多选删除 | 页面仍需 site·edit,删除按钮额外检查 cookie·delete |
保存机制
分类、资源、Cookie 项弹窗里的 保存 / 创建 只把改动写回当前页面表单。离开页面前,请再点底部 保存;要立即检查前台效果,点 保存并预览,系统会保存后用站点 Base URL 打开新标签页。
如何打开
- 在 编辑菜单 中勾选 站点设置 → Cookie 管理。
- 左侧 站点设置 → Cookie 管理。

页面结构
Cookie 管理按 Tab 组织,切换时 URL 会写入 tab 参数。

| Tab | 用途 | 是否显示底部保存 |
|---|---|---|
| 基础设置 | 启用开关、关闭按钮、重新打开方式、显示地区、Banner 模板 | 是 |
| Cookie 分类 | 维护必要 / 可选 Cookie 分类与默认勾选 | 是 |
| 内容配置 | 维护同意弹窗的多语言文案、按钮与政策链接 | 是 |
| 资源管理 | 将外部资源绑定到分类,并登记该资源产生的 Cookie | 是 |
| 数据报表 | 按日期查看同意决策与分类趋势 | 否 |
基础设置
基础设置建议最后确认:先配好分类、文案与资源,再开启并预览。

启用与关闭按钮
| 项 | 说明 |
|---|---|
| 启用 Cookie 管理 | 开启后前台输出 Cookie 同意弹窗;关闭时不显示 |
| 显示关闭按钮 | 控制弹窗右上角是否显示关闭入口 |
| 关闭行为 | 用户未明确选择时关闭弹窗的处理:同意、拒绝、或 根据地区法律规定(默认) |
面板重启方式
| 方式 | 说明 |
|---|---|
| 自定义 | 前台页面自行放置带 kc-reopen-btn class 的元素,访客点击后重新打开 Cookie 设置面板 |
| 悬浮小球 | 前台右下角自动显示一个悬浮按钮,用于重新打开面板 |
若需要让运营在后台维护自定义按钮的文字或链接,可将按钮所在 HTML 做成 元素属性 或模板资源,再由前台模板输出。
显示规则
| 规则 | 说明 |
|---|---|
| 全部地区 | 所有访客都显示同意弹窗 |
| 欧盟地区 | 只在欧盟地区显示 |
| 自定义地区 | 选择 包含规则 或 排除规则,再从国家列表中勾选国家 |
自定义国家列表来自后台国家接口,按大洲分组展示。
Banner 模板
| 模板 | 配置项 |
|---|---|
| 默认模板 | 选择 弹窗类型和位置,并在 浅色 / 深色 / 自定义 主题中选择样式;自定义主题可设置主色、背景色、文字色、按钮色与按钮文字色 |
| 自定义模板 | 使用 HTML 编辑器维护完整模板片段;建议从系统生成的精简模板改起,保留必要 ID 与 data-* 属性 |
自定义模板的目标
自定义模板主要解决 视觉、布局、文案组织与品牌化:例如把底部 Banner 改成侧边浮层、调整按钮顺序、增加品牌说明、重排 Cookie 分类与详情区域。它不需要重新实现 Cookie 同意逻辑;保存状态、按钮事件、分类同步、外部资源恢复与统计上报都由系统内置前台脚本处理。
前台加载顺序如下:
| 步骤 | 系统行为 | 开发者需要做什么 |
|---|---|---|
| 1 | 后台保存 CookieConsentSetting | 在本页配置分类、文案、资源和模板 |
| 2 | 前台请求 /_api/cj/client | 系统把自定义模板先按 Kooboo 模板语法 渲染成 HTML |
| 3 | 内置脚本把模板注入页面 | 模板中保留必要容器、按钮 ID 与分类 checkbox |
| 4 | 访客点击同意按钮 | 内置脚本写入同意 Cookie、恢复允许的资源并记录统计 |
模板可依赖的数据
模板渲染时可读取当前站点 Cookie 配置,常用信息来自后台这几个区域:
| 后台区域 | 模板中通常用于 |
|---|---|
| Cookie 分类 | 渲染分类名称、描述、必需状态、默认勾选状态 |
| 内容配置 | 渲染标题、描述、介绍、按钮文案、隐私政策与 Cookie 政策链接 |
| 资源管理 | 在详情页展示某分类关联的资源与 Cookie 项 |
| 基础设置 | 判断关闭按钮、悬浮小球、弹窗类型与位置 |
不建议在模板里硬编码分类 ID 以外的业务文案;多语言站点应优先使用 内容配置 与 Cookie 分类 中的多语言字段。
必须保留的 DOM 约定
内置脚本通过下列 ID 或属性绑定事件。开发者可以调整标签类型、层级和样式,但这些标识要保留,且同一 ID 不要重复。
| 标识 | 作用 |
|---|---|
kb-cookie-banner | Banner 容器;系统控制显示 / 隐藏 |
kb-cookie-accept-all | Banner 中 接受全部 |
kb-cookie-save | Banner 中 保存当前选择 |
kb-cookie-reject | Banner 中 拒绝非必要 Cookie |
kb-cookie-settings | 从 Banner 打开设置弹窗 |
kb-cookie-close | Banner 关闭按钮;行为受 关闭行为 配置影响 |
kb-cookie-modal | 设置弹窗容器 |
kb-cookie-modal-overlay | 弹窗遮罩 |
kb-cookie-modal-close | 关闭设置弹窗 |
kb-cookie-modal-accept-all | 弹窗中 接受全部 |
kb-cookie-modal-save | 弹窗中 保存当前选择 |
kb-cookie-modal-reject | 弹窗中 拒绝非必要 Cookie |
data-category-id="{分类ID}" | 分类 checkbox;系统同步勾选状态并读取访客选择 |
data-tab / data-tab-content | 设置弹窗内 Tab 切换 |
data-expand-category / data-resources-category | 分类详情展开与资源列表区域 |
kc-reopen-btn | 自定义重新打开按钮的 class;当不用悬浮小球时放在前台页面任意位置 |
若只做轻度品牌化,优先改 CSS、文案布局和按钮顺序;若重构 DOM,请先保留上表所有关键标识,再逐项删减验证。
内置脚本会接管的行为
| 行为 | 说明 |
|---|---|
| 首次访问展示 | 根据 typeAndPosition 决定显示 Banner、弹窗或内联区域 |
| 分类勾选同步 | 同一分类可能同时出现在 Banner 与弹窗,系统按 data-category-id 同步状态 |
| 必要分类保护 | 必需分类固定启用,访客不能取消 |
| 同意状态保存 | 系统写入 kb_cookie_consent,再次访问按已保存状态决定是否展示 |
| 资源恢复 | 未同意前被改写为 kc-src / kc-href 的资源,会在分类同意后恢复为真实 src / href |
| Iframe 占位 | 未同意时 iframe 显示 Iframe 占位内容,同意后恢复原始地址 |
| 统计上报 | 访客提交同意结果后写入 Cookie 同意统计,供 数据报表 使用 |
因此,自定义模板一般不要自行写入同意 Cookie、主动加载受控第三方资源,或绕过 资源管理 的分类配置。
开发检查清单
| 检查项 | 说明 |
|---|---|
| 按钮 ID | 接受全部、保存选择、拒绝、设置、关闭按钮都能触发 |
| 分类 checkbox | 每个可选分类都有 data-category-id,必要分类显示为不可取消 |
| 重新打开入口 | 悬浮小球或 kc-reopen-btn 至少保留一种 |
| 移动端 | Banner、弹窗、按钮组在手机宽度下不遮挡正文 |
| 资源恢复 | 拒绝后第三方资源不加载;同意对应分类后资源恢复 |
| 多语言 | 切换站点语言后标题、按钮、分类与政策链接正确 |
Cookie 分类
分类决定访客可以选择哪些 Cookie 类型,也会被资源管理和数据报表引用。

| 区域 | 说明 |
|---|---|
| 添加分类 | 打开添加分类弹窗,按站点支持语言填写名称与描述 |
| 多语言选择器 | 切换当前编辑语言;语言列表来自站点多语言配置 |
| 分类卡片 | 必要分类排在前面,可选分类排在后面 |
| 必需 / 可选 | 必要分类不可取消默认选中;可选分类可删除 |
| 默认选中 | 访客首次打开弹窗时该分类是否预先勾选;必要分类固定选中 |

新增分类默认是 可选 且未默认选中。创建后仍在当前表单内,需点页面底部 保存 才写入站点。
内容配置
内容配置维护访客看到的文字。若站点开启多语言,请逐个语言检查。

| 字段 | 显示位置 |
|---|---|
| 标题 | Cookie 弹窗标题 |
| 描述 | 弹窗主说明 |
| 介绍 | Cookie 设置面板的介绍区域 |
| 接受全部 | 同意全部 Cookie 的按钮文案 |
| 接受所选 | 仅保存当前勾选分类的按钮文案 |
| 拒绝全部 | 拒绝非必要 Cookie 的按钮文案 |
| 隐私政策链接 | 隐私政策 URL 与链接文本 |
| Cookie 政策链接 | Cookie 政策 URL 与链接文本 |
| Iframe 占位内容 | 访客尚未同意对应分类时,iframe 位置显示的占位 HTML |
资源管理
资源管理用于告诉系统:某个外部 script、img、iframe 或 link 属于哪个 Cookie 分类,以及它可能写入哪些 Cookie。

资源列表
| 列 / 操作 | 说明 |
|---|---|
| URL | 外部资源地址 |
| 分类 | 资源所属 Cookie 分类 |
| 展开行 | 查看该资源下登记的 Cookie;可 添加 Cookie、编辑或删除 Cookie 项 |
| 编辑 | 打开资源弹窗,调整 URL、资源类型、分类与 Cookie 列表 |
| 删除 / 多选删除 | 从当前 Cookie 配置中移除资源;仍需底部保存 |
添加资源

| 字段 | 说明 |
|---|---|
| URL | 可从下拉选择站点页面、布局、视图、HTML 代码块中发现的外部资源,也可手动输入 |
| 资源类型 | script、img、iframe、link;界面显示为脚本、图片、Iframe、链接,从下拉选择已有 URL 时会自动带出类型 |
| 分析 | 调用后台分析所选资源可能写入的 Cookie,并合并到 Cookie 列表;已存在同名 Cookie 不重复添加 |
| 分类 | 必填,从 Cookie 分类 中选择 |
| Cookie 列表 | 记录该资源产生的 Cookie 名称、说明与过期时间 |
Cookie 项字段:
| 字段 | 说明 |
|---|---|
| Cookie 名称 | 必填,写浏览器实际 Cookie 名称 |
| 描述 | 多语言用途说明,展示给访客 |
| 过期时间 | 单位为分钟;例如 60 表示 1 小时,1440 表示 1 天 |
数据报表
数据报表只读,不显示底部保存栏。进入 Tab 后选择日期范围查看趋势:
| 维度 | 说明 |
|---|---|
| 决策趋势 | 按 接受全部、拒绝全部、自定义选择 汇总 |
| 分类趋势 | 按 Cookie 分类汇总访客同意情况,分类名称使用当前语言 |
默认日期范围为最近 7 天。若所选日期暂无统计,页面显示空态;数据来自前台访客实际提交的 Cookie 同意结果。
典型工作流
- 先确认 Base URL 与 多语言。
- 在 Cookie 分类 中维护必要分类与可选分类。
- 在 内容配置 中补齐每个语言的标题、说明、按钮与政策链接。
- 在 资源管理 中添加外部脚本、iframe、图片或 link,并绑定到对应分类。
- 回到 基础设置,选择显示地区、重启方式、Banner 模板并开启 Cookie 管理。
- 点 保存并预览,用无痕窗口或清除 Cookie 后检查首次访问、拒绝、接受所选与重新打开面板。
- 上线后一段时间再看 数据报表,确认访客同意趋势。
CMS 与 API / 模板引擎分工
| 场景 | 看 CMS | 看 API / 模板引擎 |
|---|---|---|
| 配置 Cookie 同意弹窗、分类、文案、资源归类 | 本篇 | 无 |
| 在 KScript 中读取、设置、删除浏览器 Cookie | 只说明后台已配置 Cookie 管理 | k.cookie |
| 在模板数据流中读取请求 Cookie | 后台不展开模板语法 | k-data 标签语法 |
| 给前台添加可重新打开面板的自定义按钮 | 本篇说明 kc-reopen-btn 入口 | 元素属性、模板资源 |
相关
| 文档 | 说明 |
|---|---|
| 站点设置概述 | 站点设置菜单与建议配置顺序 |
| 基础设置 | Base URL、多语言、站点基础开关 |
| 域名管理 | 多域名与语言绑定 |
| k.cookie | KScript Cookie 读写 |
| k-data 标签语法 | 模板中从 Cookie 等请求来源读取值 |