# @contentful/experiences-runtime 中文文档 规范地址：https://npmcn.com/package/%40contentful/experiences-runtime/ 版本：0\.3\.9 npm 元数据更新时间：2026-11-06T17:15:08.899Z 中文译文更新时间：2026-11-10T17:08:24.614Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40contentful/experiences-runtime 原文对照：https://npmcn.com/package/%40contentful/experiences-runtime/?lang=original 项目主页：https://github.com/contentful/experiences#readme 源码仓库：https://github.com/contentful/experiences ## 关键信息（来自 npm 元数据） - 包体积（解压后）：597 kB，20 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：5 个 - 首次发布：2026-10-09T19:11:15.754Z - 最新版本发布：2026-11-06T17:15:08.665Z - 近 30 天下载量：5361（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：25（近 12 个月 25 个） ## 中文简介 共享运行时间和活动构建 ## 安装 ```sh npm install @contentful/experiences-runtime ``` 也可以使用：`pnpm add @contentful/experiences-runtime`、`yarn add @contentful/experiences-runtime`、`bun add @contentful/experiences-runtime` ## README # @ contentful/ 经验运行时间 > **内部包裹.** 公共节点和Web SDK消耗了这个共享运行时间. 框架适配器再出口 `EventBuilder` API 但不构建运行时间 . 运行时间拥有共享 `ContentfulExperiences` 基础, 完整 `EventBuilder` 执行和论证计划,事件元数据,只运行时间的交付和预览客户端构建,直接优化传输,事件方法,以及当前的节点到网络交接合同. 节点绑定请求- 本地状态; Web 拥有浏览器语言、 上下文和坚持配置状态 。 运行时本身并不保留这些按请求或浏览器的值. 网络曝光 其浏览器状态通过 `states` 观察和拥有模块信号和 持久性、同意性和连通性效应;节点保留其请求-局部 剖面图获取器。 运行时间供应 `ExperienceRequestState` 运输结果 类型,而 Web 叶拥有其可观测值. 共享基和节点不强制单通限制. 多个节点实例可以共存,每个 `forRequest()` 表面属于它的创建实例. 网络拥有 a `globalThis` 锁定允许每个 JavaScript 运行时间一次现场体验 Web SDK 。 内容 `destroy()` 在解锁前停止浏览器拥有的工作. 客户仍然是低级交付和免费服务。 运行时间导入 `ContentfulViewDeliveryClient`, (中文(简体) ), `fetchExperience`,主机常数,以及 XDA 生成的请求类型 `@contentful/experiences-client`。客户端不依赖运行时间。 核心仍然是无依赖的. ## 共享基数 构造 `ContentfulExperiences` 具有空间、环境、交付配置和 `eventBuilder` 带有明确平台的配置 `channel`。预览和优化配置是可选的。 该基础创建并拥有其交付,可选预览,和优化客户端. 获取和解决操作需要 `{ config: resolverConfig }` 作为逐个调用解析选项,所以一个SDK可以独立地解释不同的体验. 仅涉及事件的施工和交接准备不需要解决者登记册。 元数据与调试默认值仍可能在 SDK 上配置 。 位码 `preview: true` 需要配置预览客户端; 目的操作仍然只提供. 只读 `api` 属性是实际优化 API 客户端(`api.experience` 财务报告和审定财务报表 `api.insights`; 只读 `config` 保留所提供的类型配置 由公所叶出. 发送和预览客户端仍为内部到运行时间. 交付和预览选项接受一个代号或代号供应商. 无符号信任的代理需要一个明确的 `host` 并禁用生成的无记名认证。 终点优先是明确的 `host`,然后生成客户端的 `environment`,然后是发送或预览默认值. `environmentId` 是被ID请求所使用的内容环境标识符,而不是生成的客户端值 `environment` 选项. 基地拥有一个 `EventBuilder`,以默认库身份配置 `@contentful/experiences-runtime` 当一叶不提供一。 节点和Web提供自己的库元数据. 建造者的计划,默认,ID,时间戳,上下文组装,同意元数据,事件构造都在这里合用. `identify`, (中文(简体) ), `page`,以及 `track` 使用个性化;取景,点击,徘徊,旗景事件使用Analytics. 节点准备一个不承诺的请求交接批次。 网络使用运行时拥有 `PersonalizationDelivery` 普通在线/下行事件的发送者 和紧急准备的批次录入. 事件方法在同意承认或 丢失的相片. `trackView` 遵守优化的早期同意守卫 (c) 在针对特定观点的审定之前。 节点和Web 活动截取器在原同意门后及之前 电线事件再验证. 有效的转换事件通过第二个门 使用它们 在公布、运输或排队录取之前,最后类型和当前同意. 无效输出是计划失败,而不是拒绝同意. 后钩 块报告转换的方法/类型;每个事件方法返回 `{ accepted: false }`节点发送 直接说. `BlockedEvent.method` 输入为 `string`匹配 优化公众事件有效载荷合同. 所产生的经验交付依赖仅由客户申报。 运行时间直接宣布其优化 API 客户端, `es-toolkit`,以及 `zod` 依赖性。 它的软件包元数据被注入 `sdk-info` 建造时检查 `verify-release-artifact`。 。 。 . 直接经验与经验 `default` 何时 `variantId` 或为空。 分块构造器也使用 `default` 何时 `parentVariantId` 被省略或为空; 提供的根体验变体与分块本身的变体仍然分开。 经验积累者离开时省略了母字段未设置. 见 [节点](https://npmcn.com/package/%40contentful/node/README.md), (中文(简体) ), [网页](https://npmcn.com/package/%40contentful/web/README.md),以及 [根对齐的回放指南](https://npmcn.com/package/README.md#paired-server-to-browser-replay) 用于当前公共运营和交接处理. ## 共享事件截取器 运行时间拥有 `InterceptorManager`, (中文(简体) ), `Interceptor`, (中文(简体) ), `InterceptorMerge`, (中文(简体) ), `MaybePromise`,则 `OptimizationEventStreamEvent` 工会及其出口 从它的根。 节点和Web再出口相同的公用名. 经理的快照 每次运行的处理器、克隆输入、按插入顺序等待处理器,以及 传播处理器错误。 节点拥有其请求共享的一个事件登记册 外观; 请求状态仍为外观- 局部 。 Web 保留其现有事件 州登记。 运行时没有浏览器信号或状态受访者注册. 每一份被承认的呈文或准备的活动,一个链条运行一次。 XDA 用途 `Promise.all` 跨事件链同时保留结果顺序; 准备运行 事件依次发生。 目的地验证先于最终类型的同意检查. 省略了有效的同意锁定的XDA事件,而不取消内容获取; 悬钩/悬钩故障在运输前拒绝。 已制备的钩/螺旋失效或 无效/ 锁定的终页生成现有的无事件倒计时, 而稍后 飞行前运输故障保留了评估的重放。 检索和浏览器 已准备的重放从不重运行事件钩钩; 浏览器仍然应用了浏览器 同意及其元数据。 虎克保留现有的运输边界 无国籍者的免费获取功能没有获得全球登记。 最终型号的大门是 本地校正“优化参考”的原类型唯一闸口 `70dfa7f`。 。 。 . ## 共享的原始物 运行时间也输出 `ExperiencesHandoff`, (中文(简体) ), `createExperiencesHandoff`, (中文(简体) ), `parseExperiencesHandoff`, (中文(简体) ), `buildPreparedEvents`, (中文(简体) ), `validatePreparedEvents`,缓存安全诊断,以及 `createRequestHandoffFromData`。节点使用这些原始的 `prepareRequestHandoff()`,Web在状态水合或事件承认前验证由此产生的交接. 新的交接方式带有其内容空间和环境,缓存范围,可选评价配置,可选续作ID,以及可选准备的个人化回放. `buildPreparedEvents` 抓取事件ID,时间戳,请求上下文,地语,和当前事件认可的元数据一次而不发送;浏览器同意仍然是许可门. 准备的回放已识别/跟踪事件,然后是准确的一页,SDK限制为100个总事件和50个识别事件. 这些是交接限制,不是单张API端点的断言限制. 服务器准备在构建交接器并添加续作身份时再使用已验证的批次. 导出创建/ 保存操作验证每批事件一次 。 被导出严格的解析器验证了未信任的数据,可选的接收运行时间范围,缓存安全性,以及重放命令. 浏览器 `hydrateAndTrackCurrentPage` 消费首先验证信封,然后将已准备的事件验证推迟到承认,因此拒绝可以回落到普通的当前页面跟踪. 解析不会发送事件或改变SDK状态. Web 共享的状态应用程序助手也为公众服务 `@contentful/experiences-web/bridge-support` 输入。 它应用配置状态 通过Web的状态截取器和 解剖标记请求状态成功, 包括无剖面水分; 无剖面的交接出当前剖面 连续性不变。 此帮助不作为 XDA 内容获取的一部分运行 . 缓存警告是一种建议; `assertExperiencesCacheSafety` 而创建/保存操作拒绝包含配置文件、续接ID或重放的公开或静态交接. `public-permutation` 需要一个非空的应用程序拥有的密钥,包括经验特性和内容修订、环境、地方以及变化产生输出的每个维度。 无剖面图 `static` 交接不需要钥匙 运行时不设置响应头,也不证明应用程序发送的内容是安全的缓存. 运行时间为内部 `createRequestHandoffFromData({ handoff, data? })` 添加 评估了 API 配置到现有的私人交接器,并可以保留其回放. 它的现有形状和行为保持不变. 独立的公共节点自由 函数 `createRequestHandoffFromData({ spaceId, environmentId, data?, cache? })` 通过 Runtime 验证构建一个只属于国家的私人请求信封; 它不发出重放或顶级续作ID。 它只接受一个身份描述文件, 省略 `state` 没有提供配置文件,没有执行事件或网络工作. 无剖面水合保存了已存在的浏览器状态. 帮手都没有犯过错 。 此信封或版本字段不应用特定日记 64 KiB 上限或版本字段 `PortableRenderPlan`;呼叫者拥有安全序列化和响应大小政策. 生成的XDA请求目前没有飞行前选项. 普通代号 经验获取仍然通过客户端的传送传递配置 ID 和事件 边框,在提供时使用其含有事件的 POST 。 运行时间显示没有 XDA 支持的不承诺内容准备分块或重复事件 工作的时候 一旦XDA和生成的客户端支持在飞行前映射真实 在添加内容和处理操作前,通过客户端请求字段. ## 个人化服务 `PersonalizationDelivery` 共享一个带有直接事件方法的低级个性化传输. 普通的在线呼叫直接发送并返回回复数据;普通的离线呼叫被接受入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入入 在能力上,拒绝举行新的离线普通活动,而不是驱逐接受的工作。 已制作的批次再次验证,并默认以100个事件计数能力全部确认。 准备的批量限制仍为100分,即使有更大的已配置的队列;排出更小的队列或者剩余容量不足可以拒绝本来有效的批量. HTTP 结算前的录取返回 。 所准备的批次保留其活动体,ID,被捕获的运输地块,并通过重试选定目标身份. 普通的队列事件保留它们的事件正文,在发送时使用当前SDK请求的地块;明确的事件地块从不选择运输地块. 直接在线通话不会在他们后面等。 同时 `flush()` 电话,包括强制电话, 加入主动排水,直到这一尝试得到解决。 竣工不能保证交货或等待预定的未来复试;强迫绕过连接/后退/电路闸口,但绝不开始第二次同时排水. 重试政策遵循了Optimization的回放和没有定期个性化定时器的电路默认. `reset()` 取消排队工作和迟发出版物,包括主动销毁排出物; `destroy()` 拒绝新的工作,然后做出一次最佳尝试 排出排队的批次, 以便不发布延迟状态或排程重试。 请求失败会阻止排水 这既不是持久的持久性,也不是完全的保证。 运行时事件方法在自己的叶子上强制执行事件同意和持久性政策;在支持的情况下,同意也作为事件元数据列入. 所有者捆绑可以提供固定的 `getIsPreview` 意图。 共享事件方法检查它之前 新建或配置搜索并返回 `{ accepted: false, reason: 'preview' }`; 请求/浏览器 状态仍在节点/网状叶中. ## 常见问题 ### @contentful/experiences-runtime 是什么？ 共享运行时间和活动构建 ### 如何安装 @contentful/experiences-runtime？ 在项目目录运行 npm install @contentful/experiences-runtime，或使用 pnpm add / yarn add / bun add。 ### @contentful/experiences-runtime 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @contentful/experiences-runtime 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @contentful/experiences-runtime 可以商用吗？ @contentful/experiences-runtime 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @contentful/experiences-runtime 的下载量有多少？ 根据 npm 官方下载统计，@contentful/experiences-runtime 在 2026/10/11 – 2026/11/09 这 30 天内被下载 5,361 次，日均约 179 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @contentful/experiences-runtime 还在维护吗？ 最新版本 0\.3\.9 发布于 2026/11/07（4 天前）；至今共发布 25 个版本，其中过去 12 个月发布了 25 个；首次发布于 2026/10/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。