# @guardian/consent-manager 中文文档

规范地址：https://npmcn.com/package/%40guardian/consent-manager/

版本：2\.3\.1
npm 元数据更新时间：2026-11-12T09:12:50.194Z
中文译文更新时间：2026-11-17T02:45:38.226Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40guardian/consent-manager
原文对照：https://npmcn.com/package/%40guardian/consent-manager/?lang=original
项目主页：https://github.com/guardian/csnx#readme
源码仓库：https://github.com/guardian/csnx

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

- 包体积（解压后）：143 kB，82 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：tslib ^2\.8\.1，@guardian/ophan-tracker-js ^2\.2\.10
- 首次发布：2026-04-30T14:10:15.759Z
- 最新版本发布：2026-11-12T09:12:49.787Z
- 近 30 天下载量：21254（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

监护人的同意管理器

## 安装

```sh
npm install @guardian/consent-manager
```

也可以使用：`pnpm add @guardian/consent-manager`、`yarn add @guardian/consent-manager`、`bun add @guardian/consent-manager`

## README

# 同意管理平台

卫报同意管理平台.

[![npm (scoped)](https://img.shields.io/npm/v/@guardian/consent-manager)](https://www.npmjs.com/package/@guardian/consent-manager) [![ES version](https://badgen.net/badge/ES/2020/cyan)](https://tc39.es/ecma262/2020/) ![Types](https://img.shields.io/npm/types/@guardian/consent-manager) [![Coverage Status](https://coveralls.io/repos/github/guardian/consent-management-platform/badge.svg)](https://coveralls.io/github/guardian/consent-management-platform)

> 同意管理办法 `*.theguardian.com`。 。 。 .

Guardian CMP 处理将 USNAT 应用于美国的用户, Sourcepoint Global Enterprise to Aus 和TCFv2给其他人.

## 安装

[![Generic badge](https://img.shields.io/badge/google-chat-259082.svg)](https://chat.google.com/room/AAAAFdv9gK8)

```bash
yarn add @guardian/consent-manager
```

或者说

```bash
npm install @guardian/consent-manager
```

接下来

```js
import { getConsentFor, ...etc } from '@guardian/consent-manager';
```

### 捆绑

此软件包使用 `ES2020`。 。 。 .

如果目标环境不支持此选项, 请在捆绑您的应用程序时确保您转换此软件包 .

## 目录

-   [管理同意](https://npmcn.com/package/%40guardian/consent-manager/#readme-managing-consent)
    -   [`cmp.init(options)`](https://npmcn.com/package/%40guardian/consent-manager/#readme-cmpinitoptions)
    -   [`cmp.hasInitialised()`](https://npmcn.com/package/%40guardian/consent-manager/#readme-cmphasinitialised)
    -   [`cmp.willShowPrivacyMessage()`](https://npmcn.com/package/%40guardian/consent-manager/#readme-cmpwillshowprivacymessage)
    -   [`cmp.willShowPrivacyMessageSync()`](https://npmcn.com/package/%40guardian/consent-manager/#readme-cmpwillshowprivacymessagesync)
    -   [`cmp.showPrivacyManager()`](https://npmcn.com/package/%40guardian/consent-manager/#readme-cmpshowprivacymanager)
-   [使用同意办法](https://npmcn.com/package/%40guardian/consent-manager/#readme-using-consent)
    -   [`onConsentChange(callback, final?)`](https://npmcn.com/package/%40guardian/consent-manager/#readme-onconsentchangecallback-final)
    -   [`onConsent()`](https://npmcn.com/package/%40guardian/consent-manager/#readme-onconsent)
    -   [`getConsentFor(vendor, consentState)`](https://npmcn.com/package/%40guardian/consent-manager/#readme-getconsentforvendor-consentstate)
-   [允许同意](https://npmcn.com/package/%40guardian/consent-manager/#readme-disabling-consent)
    -   [`cmp.__disable()`](https://npmcn.com/package/%40guardian/consent-manager/#readme-cmp__disable)
    -   [`cmp.__enable()`](https://npmcn.com/package/%40guardian/consent-manager/#readme-cmp__enable)
    -   [`cmp.__isDisabled()`](https://npmcn.com/package/%40guardian/consent-manager/#readme-cmp__isdisabled)
    -   [手动](https://npmcn.com/package/%40guardian/consent-manager/#readme-manually)
    -   [使用 Cypress](https://npmcn.com/package/%40guardian/consent-manager/#readme-using-cypress)
-   [发展](https://npmcn.com/package/%40guardian/consent-manager/#readme-development)

## 管理同意

```js
import { cmp } from '@guardian/consent-manager';
```

### `cmp.init(options)`

返回 : `void`

将隐私框架添加到页面中。 必须召集它才能 隐私管理. 如有必要,还将显示初始隐私信息.

#### `options.country`

类型 : `CountryCode` 从 `@guardian/libs` 数值:例如:. `GB`, (中文(简体) ), `US`, (中文(简体) ), `AU`,, , , , , , , ,

宣布您的用户在哪个国家 。 所需 -- -- _丢出错误,如果 不见了._

#### `options.pubData`

类型 : `Object`

报告的其他备选参数.

##### `pubData.pageViewId`

类型 : `string`

确定与《议定书》/《公约》缔约方会议这一实例相关的独特页面视图的可选值.

将用来链接到 `browserId` 如果可能,应通过页面查看表提供.

#### 示例

```js
cmp.init({
    country: 'GB',
    pubData: {
        pageViewId: 'jkao3u2kcbaqk',
    },
});
```

### `cmp.hasInitialised()`

返回 : `boolean`

回返 `true` 如果《议定书》/《公约》缔约方会议已关闭.

### `cmp.willShowPrivacyMessage()`

返回 : `Promise<Boolean>`

返回一个决心 `true` 如果《议定书》/《公约》缔约方会议将显示初始 隐私信息一旦关闭,或 `false` 如果不是的话.

#### 示例

```js
cmp.willShowPrivacyMessage()
    .then(willShow =>
        if (willShow) {
            console.log("a privacy message will show as soon as it's ready");
            // e.g. don't show any other banners
        } else {
            console.log('a privacy message will not be shown');
            // e.g. show another banner if you like
        }
    );
```

### `cmp.willShowPrivacyMessageSync()`

返回 : `Boolean`

_你几乎总是想使用上面的Aync版本._

回返 `true` 如果《议定书》/《公约》缔约方会议已经显示、正在显示或将显示初始隐私信息。 回返 `false` 否则.

如果未关闭《议定书》/《公约》缔约方会议,则丢出错误.

#### 示例

```js
if (cmp.hasInitialised()) {
    if (cmp.willShowPrivacyMessageSync()) {
        // do something
    }
}
```

### `cmp.showPrivacyManager()`

显示允许用户管理的界面 他们的隐私设置 随时.

#### 示例

```js
cmp.showPrivacyManager();
```

## 使用同意办法

```js
import {
    onConsent,
    onConsentChange,
    getConsentFor,
} from '@guardian/consent-manager';
```

### `onConsentChange(callback, final?)`

返回 : `void`

每当同意状态时

-   被获取(例如初始化后)
-   更改( 如用户更改隐私偏好)

如果已获得同意,则 `onConsentChange` 被称为, 立即调用回话 .

通过 `true` 可选 `final` 参数保证召回 将会在同意状态改变时 所有其他没有在国旗上注册的回调后执行. 如果登记了不止一个回调 `final = true`,将按注册顺序执行 当同意发生变化时.

#### `callback(consentState)`

类型 : `function`

报告用户的隐私偏好.

##### `consentState.tcfv2`

类型 : `Object` 或者说 `undefined`

报告用户对 TCFv2 目的的偏好, 即最后一个 CMP 事件状态、 自定义供应商同意、 如果 GDPR 应用的旗帜、 TC 字符串和 adtl Consent 字符串.

如果用户在美国或澳大利亚,则该用户将 `undefined`。 。 。 .

与 [`__tcfapi`](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#how-does-the-cmp-provide-the-api),所有十个同意会有一个集 布尔值,默认为 `false` 未经明确同意.

```js
{
    gdprApplies: Boolean | undefined, // true - GDPR Applies, false - GDPR Does not apply, undefined - unknown whether GDPR Applies
    tcString: String, // 'base64url-encoded TC string with segments'
    addtlConsent: String, // Google AC string
    eventStatus: String, // 'tcloaded' | 'cmpuishown' | 'useractioncomplete'
    consents: {
        1: Boolean,
        2: Boolean,
        /* … */
        9: Boolean,
        10: Boolean,
    },

    vendorConsents: {
        'abcdefghijklmnopqrstuvwx': Boolean,
        'yz1234567890abcdefghijkl': Boolean,
        'mnopqrstuvwxyz1234567890': Boolean,
        // Sourcepoint IDs, etc.
    }
}
```

##### `consentState.usnat`

类型 : `Object` 或者说 `undefined`

报告用户是否撤回了在美国出售其数据的同意.

如果用户不在美国,则 `undefined`。 。 。 .

```js
{
    doNotSell: Boolean;
    signalStatus: 'ready';
}
```

##### `consentState.aus`

类型 : `Object` 或者说 `undefined`

报告用户是否撤回对个性化广告的同意 在澳大利亚.

如果用户不在澳大利亚,将 `undefined`。 。 。 .

```js
{
    personalisedAdvertising: Boolean, // True by default
}
```

##### `consentState.canTarget`

类型 : `boolean`

如果用户可以按照主动同意框架成为个人化的目标.

举个例子 `canTarget` 这将是 `true` 在下列情况下:

-   如果用户有 USNAT _没有_ 点击"不卖",
-   如果用户有AUS _没有_ 选择退出个性化广告
-   如果用户已同意所有用途,则TCFv2

##### `consentState.framework`

类型 : `string` 无效

积极同意框架,例如:. `"usnat"`, (中文(简体) ), `"aus"`, (中文(简体) ), `"tcfv2"` 或者说 `null`。 。 。 .

#### 示例

```js
import { onConsentChange } from '@guardian/consent-manager';

onConsentChange(({ tcfv2, usnat, aus }) => {
    if (tcfv2) {
        console.log(tcfv2); // { 1: true || false, 1: true || false, ... }
    }

    if (usnat) {
        console.log(usnat); // { doNotSell: true || false }
    }

    if (aus) {
        console.log(aus); // { personalisedAdvertising: true || false }
    }
});
```

### `onConsent()`

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}我答应你 `onConsentChange` 解决初始同意状态.

这只能解决一次 而回电传递给 `onConsentChange` 每次同意状态发生变化时都会执行。 避免在必须听取国家随后同意的情况下使用这一功能.

返回 : `Promise<ConsentState>`

### `getConsentFor(vendor, consentState)`

返回 : `boolean`

获得特定供应商的同意.

#### `vendor`

类型 : `string`

支助供应商

#### TCFV2供应商

-   `"a9"`
-   `"acast"`
-   `"braze"`
-   `"comscore"`
-   `"criteo"`
-   `"google-analytics"`
-   `"google-mobile-ads"`
-   `"google-tag-manager"`
-   `"googletag"`
-   `"ias"`
-   `"inizio"`
-   `"ipsos"`
-   `"magnite"` (在合同签署前不要使用)
-   `"mparticle"`
-   `"nielsen"`
-   `"ophan"`
-   `"permutive"`
-   `"prebid"`
-   `"qm"` (量子计量)
-   `"redplanet"` (仅澳大利亚)
-   `"remarketing"`
-   `"sentry"`
-   `"teads"`
-   `"twitter"`
-   `"youtube-player"`

#### 仅销售商

-   `"redplanet"`

如果缺少所需的供应商,请\[提出一个问题\](https://github.com/guardian/consent-management-platform/issues)(或PR!).

#### `consentState`

类型 : `Object`

将同意书转交给 `onConsentChange` 调用.

#### 示例

```js
import { onConsentChange, getConsentFor } from '@guardian/consent-manager';

onConsentChange((consentState) => {
    const ga = getConsentFor('google-analytics', consentState); // true
    const comscore = getConsentFor('comscore', consentState); // false

    // throws error
    const eowifnwoeifjoweinf = getConsentFor('eowifnwoeifjoweinf', consentState);

    // you can still use the consent state for a more complicated task
    const complexConsentCondition = myComplexConsentTask(consentState);
});
```

## 允许同意

可以在目前的浏览器中完全禁用CMP,这对测试主机应用程序是有用的.

### `cmp.__disable()`

返回 : `void`

#### 示例

```js
cmp.__disable(); // CMP won't run even if you try
```

### `cmp.__enable()`

返回 : `void`

#### 示例

```js
cmp.__enable(); // CMP will work as normal
```

### `cmp.__isDisabled()`

返回 : `boolean`

#### 示例

```js
cmp.__isDisabled(); // => true/false
```

### 手动

设置 a `gu-cmp-disabled=true` 饼干 这跟跑步一样 `cmp.__disable()`。 。 。 .

#### 示例

```js
document.cookie = 'gu-cmp-disabled=true;';
```

删除它与运行相同 `cmp.__enable()`。 。 。 .

#### 示例

```js
document.cookie = 'gu-cmp-disabled=; Max-Age=0;';
```

### 使用 Cypress

要在 Cypress 测试中禁用同意,请查看 [`setCookie` 文档](https://docs.cypress.io/api/commands/setcookie.html)。 。 。 .

## 发展

见 [开发者文件](https://npmcn.com/package/%40guardian/consent-manager/docs/01-development-instructions.md)

## 常见问题

### @guardian/consent-manager 是什么？

监护人的同意管理器

### 如何安装 @guardian/consent-manager？

在项目目录运行 npm install @guardian/consent-manager，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：tslib（^2\.8\.1）、@guardian/ophan-tracker-js（^2\.2\.10）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @guardian/consent-manager 支持 TypeScript 吗？

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

### @guardian/consent-manager 支持 ESM 还是 CommonJS？

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

### @guardian/consent-manager 可以商用吗？

@guardian/consent-manager 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @guardian/consent-manager 的下载量有多少？

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

### @guardian/consent-manager 还在维护吗？

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

