# @datavallis/consent 中文文档

规范地址：https://npmcn.com/package/%40datavallis/consent/

版本：0\.5\.1
npm 元数据更新时间：2026-11-05T10:50:11.159Z
中文译文更新时间：2026-11-14T13:16:23.846Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40datavallis/consent
原文对照：https://npmcn.com/package/%40datavallis/consent/?lang=original
项目主页：https://datavallis.com/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，78 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-11-04T09:28:37.944Z
- 最新版本发布：2026-11-05T10:50:10.964Z
- 近 30 天下载量：2037（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

Data Vallis cookie agreement: GDPR / ZEKom-2 ready blag, Google Conserv2, 服务预设和同意日志,由香草-cookieconsed所建.

## 安装

```sh
npm install @datavallis/consent
```

也可以使用：`pnpm add @datavallis/consent`、`yarn add @datavallis/consent`、`bun add @datavallis/consent`

## README

# Kockica — Data Vallis 的饼干同意书

`@datavallis/consent` · 允许欧盟网站投放饼干 [数据 Vallis](https://datavallis.com/)。添加一个脚本标签: 科克卡在页面上找到追踪器 在访客同意之前封锁它们 建立横幅的分类 您的政策页面的 cookie 表格 。 GDPR / ePrivacy / ZEKom-2已就绪,谷歌同意模式 v2已建入. 建在麻省理工学院的牌照上 [香草饼干同意](https://github.com/orestbida/cookieconsent) (见 `NOTICE`) (中文(简体) ).

> **法律通知.** 科克卡是一个技术工具,不是法律咨询,使用它本身并不能建立网站 顺从。 网站运营商作为控制者负责其配置,文本和政策. 默认 文本是模板(未经律师审查);在商业使用之前加以审查。 只要"照原样" 麻省理工学院的执照,没有担保.

## 用 AI 代理安装

给您的编码代理此页面链接和行 : _"在这个站点上安放克克卡"_ 代理: 跟踪 [`AI-INSTALL.md`](https://unpkg.com/@datavallis/consent/AI-INSTALL.md) (也在本包中: `node_modules/@datavallis/consent/AI-INSTALL.md`) ——调查,去掉旧旗子,安装,测试,报告.

## 快开始

进来的第一件事 `<head>`,在任何其他标记之前:

```html
<script
  src="https://cdn.jsdelivr.net/npm/@datavallis/consent@0.5/dist/kockica.min.js"
  data-site-id="my-site"
  data-controller="Example Ltd., Ljubljana"
  data-policy-url="/cookie-policy"
  data-languages="en,de"
></script>
```

就这样 离开你的Google分析器,Meta像素,YouTube嵌入等 完全一样. 在您的 cookie 策略页面上, 添加表格 :

```html
<div data-kockica-cookie-table></div>
```

## 它自己会做什么

-   **查找已知的跟踪器** ——Google Analytics,Google Ads,Google Tag 管理器,Meta Pixel,Hotjar,微软克丽蒂, 链接到 Insight, TikTok 像素, YouTube, Vimeo, Google 地图中 – 在页面的 HTML 和后面添加的标签中 JavaScript (GTM,像素片段).
-   **在同意前封锁他们.** 脚本不运行,嵌入不加载,没有设置饼干. 征得同意后,开始; 在下一页 他们立即开始.
-   **谷歌标签** 继续装入并保持无饼干 **同意模式 v2** 直至同意为止(`googleMode: 'advanced'`,谷歌的游戏 建议设置). 设定 `googleMode: 'basic'` 像其他一切一样挡住他们.
-   **构建其发现的横幅 :** 只有网站真正使用的类别(功能、分析、广告).
-   **饼干表 :** 上面的简称为每类一个表格(cookie、提供者、目的、持续时间) 相同的表格出现在横幅的设置中. 目的和期限是本地化的.
-   **相竞默认 :** 选入,没有预选的盒子, _全部接受( E)_ 编号 : _拒绝全部_ 编号 : _设置_ 第一层 相同的造型(EDPB Cookie Banner Task Force),控制器和在第一层上命名的目的(ZEKOM-2, 第225/1条).
-   **退出** 简单如同意:一个小的单色按钮(Data Vallis cubes)或你自己的页脚链接.
-   **同意日志** (可选的):每个选择发送到您端点的一个记录,没有来自浏览器的IP或其他个人数据.
-   **22种语言:** en, sl, de, hr, it, fr, es, pt, nl, da, pl, cs, sk, hu, bg, uk, ru, el, sq, sv, fi, nb (英语:`no` 编号 : `nn` 页面获取 Bokmål。 只装入页面 其自己的语言(~1.5 KB); 添加任何其他语言 `translations`。 。 。 .

### 自动封锁的限制

浏览器开始装入 `<iframe src>` 在任何脚本能够读取之前,在HTML中写入 反应,其预装扫描仪可能获取 `<script src>` 早点 Kockica 立即中止 iframe 并且永远不要让一个 脚本被冻结运行, 因此没有内容负载, 没有做成, 没有设置 cookie —— 但第一个请求可能已经 已经到达提供者。 如果在同意前没有要求,请自行标记这些内容(下一节)。 追踪器 Kockica不知道不会自动被封锁;用同样的方式标记它们.

饼干表显示Kockica对它运行的页面了解多少. 只在部分页面上出现的标记被列出一次 访客在浏览器里有,或者当你添加到 `services`。 。 。 .

### 不适合个人化的谷歌广告

科克卡语是 **未经谷歌认证的CMP** 未执行 **IAB TCF 自动交换器**。谷歌需要一个个性化 AdSense、Ad Manager和AdMob在欧洲经济区、联合王国和瑞士的访客广告;没有这些广告,他们只能得到 非个性化或有限广告。 当一页装入AdSense或Ad Manager时,Kockica在浏览器控制台上这样说. 谷歌分析, 谷歌 广告转换跟踪和再上市标签通常通过Monse Mode v2.

## 自己粘贴元素( 可选)

```html
<script type="text/plain" data-category="analytics" src="https://example.com/stats.js"></script>
<iframe data-kockica-category="marketing" data-src="https://www.youtube-nocookie.com/embed/VIDEO_ID" title="Video"></iframe>
```

未经同意,有门框的iframe 显示一个占位符 带有"Allow and show"按钮.

## 当科克卡再次问起

科克卡记起每个访客被显示的类别. 当页后提供类别时,它们没有 见-市场营销通过Google Tag管理器添加了Meta像素,一个页面获得YouTube视频——横幅再次出现: 他们之前的选择保持不变,新类别开始。 没有人可以撞倒 `revision`。 。 。 .

随着Google Tag 管理器在页面上出现,横幅从一开始就提供所有三类,所以"接受所有"已经 稍后添加到容器上的封面标记——包括GTM本身所保存的标记,直到同意模式信号出现为止 授权, 无法提前看到脚本 .

未覆盖: 脚本 Kockica 不识别, 直接粘入 HTML 。 标记(见上文). `revision` 还是 重新询问每个人,比如在您更改文本或政策之后.

## 稍后改变同意

一个带有 Data Vallis 立方体的小单色按钮坐落在左下角(`revisitPosition: 'right'` 移动它. 喜欢链接吗? 设定 `revisitButton: false` (中文(简体) ) `data-revisit-button="false"`)并添加,通常在页脚中:

```html
<a href="#" data-kockica-preferences>Cookie settings</a>
```

法律必须总是可以使用,而且与同意一样容易;每一页的页脚链接都符合这一点.

## npm (反应, Next.js, 任意捆绑)

```bash
npm i @datavallis/consent
```

```ts
import { initConsent } from '@datavallis/consent';
import '@datavallis/consent/style.css';

initConsent({
  siteId: 'my-site',
  controller: { name: 'Example Ltd., Ljubljana' },
  policyUrl: '/cookie-policy',
  languages: ['en', 'de'],
});
```

说一次,客户端, 尽早.

### Next.js (App路由器) (英语)

```tsx
// app/kockica.tsx
'use client';
import { initConsent } from '@datavallis/consent';
import '@datavallis/consent/style.css';

// One cookie policy page per language. The first entry is the fallback language.
const COOKIE_POLICY: Record<string, string> = {
  en: '/en/cookie-policy',
  de: '/de/cookie-richtlinie',
};

// Runs when the client bundle loads — before next/script tags (afterInteractive) are added.
if (typeof window !== 'undefined') {
  const lang = document.documentElement.lang.slice(0, 2);
  initConsent({
    siteId: 'my-site',
    controller: { name: 'Example Ltd., Ljubljana' },
    policyUrl: COOKIE_POLICY[lang] ?? COOKIE_POLICY.en!,
    languages: Object.keys(COOKIE_POLICY),
  });
}

export default function Kockica() {
  return null;
}
```

```tsx
// app/[locale]/layout.tsx
import { consentModeDefaultsSnippet } from '@datavallis/consent';
import Kockica from '../kockica';

export default async function Layout({ children, params }: { children: React.ReactNode; params: Promise<{ locale: string }> }) {
  const { locale } = await params;
  return (
    <html lang={locale}>
      <head>
        {/* Consent Mode defaults before Google tags */}
        <script dangerouslySetInnerHTML={{ __html: consentModeDefaultsSnippet() }} />
      </head>
      <body>
        <Kockica />
        {children}
      </body>
    </html>
  );
}
```

在饼干政策页面: `<div data-kockica-cookie-table suppressHydrationWarning />`表、门框和 在客户端导航后出现的标记也被处理。 旗子上保留着它最先使用的语言 显示到下一页满载.

## 选项

| 选项 | 默认 |  |
| --- | --- | --- |
| `siteId` | ——(需要) | 随日志记录一起发送 |
| `controller.name` | ——(需要) | 在横幅和饼干桌上显示 |
| `policyUrl` | ——(需要) | 从横幅链接 |
| `languages` | `['sl', 'en']` | 您的网站语言; 横幅如下 `<html lang>`。第一个=倒计时 |
| `autoDetectLanguage` | `'document'` | 或者说 `'browser'` |
| `autoBlock` | `true` | 探测并屏蔽已知的跟踪器 |
| `googleMode` | `'advanced'` | `'basic'` 块 Google 标记直到同意 |
| `services` | 检测 | 添加跟踪器 Kockica 无法在负载中看到 : `ga4`, (中文(简体) ), `gtm`, (中文(简体) ), `googleAds`, (中文(简体) ), `metaPixel`, (中文(简体) ), `hotjar`, (中文(简体) ), `clarity`, (中文(简体) ), `linkedinInsight`, (中文(简体) ), `tiktokPixel`, (中文(简体) ), `youtube`, (中文(简体) ), `vimeo`, (中文(简体) ), `googleMaps` |
| `categories` | 检测 | 额外 `functional`, (中文(简体) ), `analytics`, (中文(简体) ), `marketing` |
| `consentMode` | `true` | 谷歌同意模式 v2 |
| `logEndpoint` | 无 | HTTPS URL; 没有它就关闭日志 |
| `revision` | `0` | 又来问大家 |
| `reconsentOnNewCategories` | `true` | 再问一问页面何时提供了访客没有看过的分类 |
| `gtmOffersAllCategories` | `true` | 用GTM在页面上,提供功能性,分析性和广告性 |
| `expiresAfterDays` | `182` | 1–395 (中文(简体) ) |
| `cookieDomain` | 当前主机 | `.example.com` 子域间共享同意 |
| `layout` 编号 : `position` | `'box'` 编号 : `'bottom left'` | `'bar'` 编号 : `'bottom'` |
| `revisitButton` | `true` | 小型浮动设置按钮 |
| `revisitPosition` | `'left'` | `'right'` |
| `branding` | `true` | 由Kockica ^ Data Vallis)在旗下脚下授權(无后继) |
| `respectGpc` | `false` | 全球隐私控制荣誉 |
| `translations` | —— 说 | 每种语言的覆盖,与内置文本合并 |
| `onChange` | —— 说 | `(state, trigger) => void` 在所有选择之后; `trigger` 实值 `first`, (中文(简体) ), `change` 或者说 `reconsent` |

脚本标签: 与 `data-*` 属性( e)`data-google-mode="basic"`, (中文(简体) ), `data-auto-block="false"`, (中文(简体) ), `data-services="ga4,vimeo"` (......) (中文(简体) ). 只列出您网站真正拥有的语言: 横幅会说页面的语言( Name`<html lang>`),或第一个 如果页面的语言不在列表中,则列出。 没有内置包的语言(如:. `ja`) 回到英语 任何不覆盖的文本。 自营CDN大楼? 复制 `kockica.min.js`, (中文(简体) ), `style.css` 编辑 `lang/` 文件夹一起.

## 同意日志合同

`POST logEndpoint`尸体是JSON送来的 `text/plain;charset=UTF-8` (没有CORS飞行前):

```json
{
  "siteId": "my-site",
  "consentId": "8c0e…",
  "revision": 0,
  "action": "accept_all | reject_all | custom",
  "trigger": "first | change | reconsent",
  "accepted": ["necessary", "analytics"],
  "rejected": ["marketing"],
  "language": "en",
  "page": "https://example.com/contact",
  "timestamp": "2026-11-04T09:00:00.000Z",
  "sdkVersion": "0.3.0"
}
```

服务器添加了已切换的IP和国别. 接收服务是一项单独的任务(参见: `docs/tasks/README.md`) (中文(简体) ).

## 发展

需求 **节点22.18+** (见 `.nvmrc`· ; `nvm use` 捡起去. 已发布的软件包本身有节点要求——它在浏览器中运行.

```bash
npm ci
npm run check            # lint + typecheck + unit tests + build
npx playwright install chromium && npm run test:e2e
npm run demo             # http://localhost:4321/demo/  ·  auto-detection: /demo/auto.html
```

出版时间: `docs/runbooks/publish-npm.md`项目规则: `docs/DEVELOPMENT-RULES.md`。当前状态: `docs/HANDOFF.md`。 。 。 .

## 许可证

MIT – Data Vallis d.o.o. Kockica和 Data Vallis cubes mark是"Data Vallis d.o.o.o.o."的品牌,包括香草-cookieconsent → Orest Bida(MIT)——参见 `NOTICE`。 。 。 .

## 常见问题

### @datavallis/consent 是什么？

Data Vallis cookie agreement: GDPR / ZEKom-2 ready blag, Google Conserv2, 服务预设和同意日志,由香草-cookieconsed所建\.

### 如何安装 @datavallis/consent？

在项目目录运行 npm install @datavallis/consent，或使用 pnpm add / yarn add / bun add。

### @datavallis/consent 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @datavallis/consent 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @datavallis/consent 可以商用吗？

@datavallis/consent 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @datavallis/consent 的下载量有多少？

根据 npm 官方下载统计，@datavallis/consent 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,037 次，日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @datavallis/consent 还在维护吗？

最新版本 0\.5\.1 发布于 2026/11/05（9 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。