@guardian/consent-manager

中文文档
2.3.1发布于 2026/11/12TypeScriptESM + CJS构建来源已验证近 30 天下载 2.1万

监护人的同意管理器

中文使用文档
文档目录20 节
  1. 安装
  2. 捆绑
  3. 目录
  4. 管理同意
  5. cmp.init(options)
  6. cmp.hasInitialised()
  7. cmp.willShowPrivacyMessage()
  8. cmp.willShowPrivacyMessageSync()
  9. cmp.showPrivacyManager()
  10. 使用同意办法
  11. onConsentChange(callback, final?)
  12. onConsent()
  13. getConsentFor(vendor, consentState)
  14. 允许同意
  15. cmp.__disable()
  16. cmp.__enable()
  17. cmp.__isDisabled()
  18. 手动
  19. 使用 Cypress
  20. 发展

同意管理平台

卫报同意管理平台.

npm (scoped) ES version Types Coverage Status

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

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

安装

Generic badge

yarn add @guardian/consent-manager

或者说

npm install @guardian/consent-manager

接下来

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

捆绑

此软件包使用 ES2020。 。 。 .

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

目录

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 如果可能,应通过页面查看表提供.

示例

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

cmp.hasInitialised()

返回 : boolean

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

cmp.willShowPrivacyMessage()

返回 : Promise<Boolean>

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

示例

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 否则.

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

示例

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

cmp.showPrivacyManager()

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

示例

cmp.showPrivacyManager();
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,所有十个同意会有一个集 布尔值,默认为 false 未经明确同意.

{
    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。 。 。 .

{
    doNotSell: Boolean;
    signalStatus: 'ready';
}
consentState.aus

类型 : Object 或者说 undefined

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

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

{
    personalisedAdvertising: Boolean, // True by default
}
consentState.canTarget

类型 : boolean

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

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

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

类型 : string 无效

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

示例

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 调用.

示例

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

示例

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

cmp.__enable()

返回 : void

示例

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

cmp.__isDisabled()

返回 : boolean

示例

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

手动

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

示例

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

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

示例

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

使用 Cypress

要在 Cypress 测试中禁用同意,请查看 setCookie 文档。 。 。 .

发展

见 开发者文件

版本与发布记录

@guardian/consent-manager 共发布 32 个版本,首次发布于 2026/04/30;过去 12 个月发布了 32 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.3.1latest2026/11/124 天前
0.0.0-canary-20261112084807canary2026/11/124 天前
0.0.0-canary-202611120845102026/11/124 天前
0.0.0-canary-202611120836372026/11/124 天前
0.0.0-canary-202611120828472026/11/124 天前
0.0.0-canary-202611120821002026/11/124 天前

关于 @guardian/consent-manager 的常见问题

@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 和提交记录判断。