# @contentful/optimization-core 中文文档

规范地址：https://npmcn.com/package/%40contentful/optimization-core/

版本：2\.2\.1
npm 元数据更新时间：2026-11-06T12:30:31.113Z
中文译文更新时间：2026-11-10T16:57:21.830Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.5 MB，71 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2026-02-03T12:37:38.613Z
- 最新版本发布：2026-11-06T12:30:30.915Z
- 近 30 天下载量：6292（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

内容优化平台不可识别核心 SDK

## 安装

```sh
npm install @contentful/optimization-core
```

也可以使用：`pnpm add @contentful/optimization-core`、`yarn add @contentful/optimization-core`、`bun add @contentful/optimization-core`

## README

[![Contentful Logo](https://raw.githubusercontent.com/contentful/optimization/optimization-core-v2.2.1/contentful-icon.png "Contentful")](https://www.contentful.com/developers/docs/personalization/)

# 内容个性化分析

### 优化核心 SDK

[指南](https://contentful.github.io/optimization/documents/Documentation.Guides.html) • 妇女 [参考文献](https://contentful.github.io/optimization) • 妇女 [捐款](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/CONTRIBUTING.md)

优化核心SDK拥有平台-可知优化状态机器,事件构建器, sDKs使用的排队、解析器和截取器。 Web, 反应 Web, 节点, 反应 原生地和原生地的桥梁地层以这个包为基础.

我们建议用一个SDK平台而不是Core直接开始应用代码. 使用这个 在建立或维护 SDK 层时读取 EADME, 并使用 [选择正确的 SDK](https://contentful.github.io/optimization/documents/Documentation.Guides.choosing-the-right-sdk.html) 在决定集成中属于哪个应用软件包时。 已生成 [参考文件](https://contentful.github.io/optimization) 仍然是真相的来源 导出 API 签名.

> \[大
> 
> 从v1升级? 跟着 [v1-v2 迁移指南](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) 在更改软件包版本之前.

目录

-   [开始](https://npmcn.com/package/%40contentful/optimization-core/#readme-getting-started)
-   [何时使用此软件包](https://npmcn.com/package/%40contentful/optimization-core/#readme-when-to-use-this-package)
-   [核心变体](https://npmcn.com/package/%40contentful/optimization-core/#readme-core-variants)
    -   [状态核心](https://npmcn.com/package/%40contentful/optimization-core/#readme-stateful-core)
    -   [无国籍核心](https://npmcn.com/package/%40contentful/optimization-core/#readme-stateless-core)
-   [通用配置](https://npmcn.com/package/%40contentful/optimization-core/#readme-common-configuration)
-   [运动归属](https://npmcn.com/package/%40contentful/optimization-core/#readme-campaign-attribution)
-   [软件包表面](https://npmcn.com/package/%40contentful/optimization-core/#readme-package-surface)
    -   [Schema 切入点](https://npmcn.com/package/%40contentful/optimization-core/#readme-schema-entry-point)
    -   [自定义条目源适配器](https://npmcn.com/package/%40contentful/optimization-core/#readme-custom-entry-source-adapters)
-   [预览支持](https://npmcn.com/package/%40contentful/optimization-core/#readme-preview-support)
-   [相关](https://npmcn.com/package/%40contentful/optimization-core/#readme-related)

## 开始

使用与国家预防机制兼容的软件包管理器安装,例如:

```sh
pnpm install @contentful/optimization-core
```

根据您正在构建的运行时间层选择状态或无国籍的核心类 :

```ts
import { CoreStateful, CoreStateless } from '@contentful/optimization-core'

const statefulOptimization = new CoreStateful({
  spaceId: 'your-space-id',
})
const statelessOptimization = new CoreStateless({
  spaceId: 'your-space-id',
})
```

国有运行时间拥有持久的SDK状态. 无国籍的运行时间约束了请求范围的同意, 调用事件方法前的配置状态、事件上下文和经验 API 选项:

```ts
const requestOptimization = statelessOptimization.forRequest({
  consent: true,
  locale: 'en-US',
  eventContext: { locale: 'en-US' },
  experienceOptions: { preflight: false },
  profileId: 'f0837d7dc6344c36a3a0a06c4cde754b',
})

const { accepted, data } = await requestOptimization.page()
```

## 何时使用此软件包

使用 `@contentful/optimization-core` 当您正在建造或维护一个 SDK 层时,需要 共享优化状态机器,事件构建器,队列,解析器,或截取器. 多数 应用程序代码使用 SDK 平台, 如 Web, React Web, Node, 或 React Intext 而不是 直接取决于核心.

## 核心变体

### 状态核心

`CoreStateful` 是SDK在状态 JavaScript 运行的基础,例如浏览器, 移动 JavaScript 容器,和本土桥跑时. 它维持同意,配置,选择 优化,旗帜,事件流,被屏蔽的事件,以及预览-板块状态作为只读可观察.

`reset()` 丢弃队列事件, 并取消状态更新 。 撤销事件同意 在用户运行前完成清理. `destroy()` 尝试最后排队交付和释放 在另一个实例启动前进行内部订阅;应用程序订阅仍保留 呼叫者拥有。 见 [核心国家管理](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/documentation/concepts/core-state-management.md) 对于生命周期和可观察的行为.

> \[大
> 
> `CoreStateful` 设计时使用模块-全局状态。 初始化 : JavaScript 运行时间并重用.

### 无国籍核心

`CoreStateless` 是在诸如节点服务器和 服务器侧函数 。 它不存储请求之间的同意或配置状态。 消费者打电话 `forRequest()` 将同意、事件背景和经验选项约束在收到的一项请求中. 过 `profileId` 经验连续性或全经验 `Profile` 结束 `profile` 为入想. 经验答复更新了请求-地方概况,以便日后发出呼吁.

请求客户端还显示只读 `eventBuilder` 用于构建标识的外表,页, 屏幕,并跟踪带有请求上下文和语言默认的有效载荷。 建筑使用共享 构建器的元数据和提供商未经申请同意,运行提交截取器, 或更新请求状态。 对正常提交使用直接请求事件方法; 低级 API 已建事件的电话不会自动应用此处理。 SDK的根头 `eventBuilder` 是无约束的。 见 [节点请求范围事件示例](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/packages/node/node-sdk/README.md#request-scoped-events)。 。 。 .

## 通用配置

共享核心配置 :

| 选项 | 需要吗? | 默认 | 说明 |
| --- | --- | --- | --- |
| `spaceId` | 对 | 不详 | 经验和透视 API 请求的空间标识符 |
| `environment` | 没有 | `'master'` | 体验和透视 API 具有内容的空间环境标识符 |
| `api` | 没有 | 参见下面的 API 选项 | API 和 Insights API 端点选项 |
| `contentful` | 没有 | `undefined` | 注册 `contentful.js` 客户端、 默认查询和缓存 |
| `eventBuilder` | 没有 | SDK 层默认值 | 平台 SDK 作者的事件元数据覆盖 |
| `fetchOptions` | 没有 | SDK 默认 | 获取超时并重试行为 |
| `logLevel` | 没有 | `'error'` | 默认控制台槽的最低日志级别 |

同意和事件配置 :

| 选项 | 需要吗? | 默认 | 说明 |
| --- | --- | --- | --- |
| `allowedEventTypes` | 没有 | `[]` | 在明确规定同意前允许的活动类型 |
| `onEventBlocked` | 没有 | `undefined` | 当同意或守护逻辑阻挡事件时, 引用回调 |

核心本身未能在同意前关闭。 平台 SDKs 为事件设定运行时间的默认值 在该运行时间中有意义的类型,例如浏览器 `identify`编号 :`page`,服务器 `identify`编号 :`page`, (中文(简体) ), 移动 `identify`编号 :`screen`。 。 。 .

只有状态配置 :

| 选项 | 需要吗? | 默认 | 说明 |
| --- | --- | --- | --- |
| `defaults` | 没有 | `undefined` | 初始状态,通常包括同意、持久性同意或剖面值 |
| `getAnonymousId` | 没有 | `undefined` | 用于提供来自应用程序所属身份状态的匿名身份的功能 |
| `queuePolicy` | 没有 | SDK 默认 | Fush 重试行为和下行队列界限 |

持久性同意控制具有运行时间存储的 SDK 的持久配置-连续存储 : 配置文件、匿名ID、更改和选定的优化缓存。 事件同意,存储同意 决定和调试状态分别跟踪.

常见 `api` 选项:

| 选项 | 适用于 | 默认 | 说明 |
| --- | --- | --- | --- |
| `experienceBaseUrl` | 全体 | `'https://experience.ninetailed.co/'` | 经验 API 的基础 URL |
| `insightsBaseUrl` | 全体 | `'https://ingest.insights.ninetailed.co/'` | 透视 API 的基础 URL |
| `enabledFeatures` | 全体 | `['ip-enrichment', 'location']` | 每个请求的经验 API 特性 |
| `location` | 全体 | API 倒计时 | 单向显示的默认请求位置 |
| `ip` | 状态 | `undefined` | 经验 API 分析的 IP 地址覆盖 |
| `plainText` | 状态 | `true` 单发突变 | 发送单图显示的经验变异为文本 |
| `preflight` | 状态 | `false` | 汇总一个配置状态而不存储它 |

两个核心构建器都接受 `api.location`; 平台 SDKs继承了该配置. 无国籍请求客户通过它覆盖 `forRequest({ experienceOptions: { location } })`数字 :

```ts
const optimization = new CoreStateless({
  spaceId: 'your-space-id',
  api: { location: { countryCode: 'DE' } },
})
const requestOptimization = optimization.forRequest({
  consent: true,
  experienceOptions: { location: {} },
})
await requestOptimization.page()
```

请求位置取代整个构造器默认值,包括明确 `{}`活动 `context.location` 继续分开,并优先于 API 的匹配请求字段. 空请求位置提供空默认, 而不是 API 地理定位; 它不清晰 现有配置文件位置。 这是请求评价输入, 而不是永久配置文件锁定 。 对于 后端优先级和配置连续性,参见 [位置输入和简介更新](https://contentful.github.io/optimization/documents/Documentation.Concepts.Profile_synchronization_between_client_and_server.html#location-inputs-and-profile-updates)。 。 。 .

何时 `plainText` 被省略,使用单相标注的经验突变/事件请求 `text/plain`。 。 。 . 过 `plainText: false` 派JSON来 经验批量剖面更新仍然默认为JSON.

在无国籍环境中,通过 `ip`, (中文(简体) ), `locale`, (中文(简体) ), `plainText`,以及 `preflight` 作为 `experienceOptions` 当创建请求绑定的客户端而不是构建器配置时。 传递特定请求的透视 API 选项, 如最后的尝试 `beacon` 发送者, 如 `insightsOptions`。 。 。 .

核心支持状态的 SDK 可以接受初始顶级 `locale` 和运行时间 `setLocale(locale)` 打电话 他们揭露了SDK体验 API和默认事件 locale通过直播 `locale` 获取器 财务报告和审定财务报表 `states.locale` 可见. 无国籍服务器 SDKs 应当通过请求扫描的 SDK 语言 `forRequest({ locale })`; 高级呼叫者仍然可以通过 `experienceOptions.locale` 没有请求时 `locale` 提供.

应用程序拥有Contentful CDA 语言选择,并将该语言直接传递到其内容 客户端。 完整的语言模式见: [优化 SDK 套件中的位置处理](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html)。 。 。 .

常见 `fetchOptions` 为: `fetchMethod`, (中文(简体) ), `requestTimeout`, (中文(简体) ), `retries`, (中文(简体) ), `intervalTimeout`, (中文(简体) ), `onFailedAttempt`,以及 `onRequestTimeout`。默认重试仅对 HTTP 适用 `503` 回应.

对于每个选项,回调有效载荷和输出类型,使用生成的 [核心 SDK 参考](https://contentful.github.io/optimization/modules/_contentful_optimization-core.html)。 。 。 .

## 运动归属

事件构建者明确使用 `campaign` 提供数据时。 否则,他们推断 `context.campaign` 从 `utm_campaign`, (中文(简体) ), `utm_source`, (中文(简体) ), `utm_medium`, (中文(简体) ), `utm_term`,以及 `utm_content` 参数 `page.url`。它们不检查 `page.referrer`。 。 。 .

对于一个页面活动, `properties.url` 提供至少包含一个运动的推断运动 支持 UTM 参数。 否则,建造者使用已解决的 `context.page.url`解决 URL来自一个明确 `page.url`,或从 `getPageProperties()` 当事件输入不 超过它。 如果两个符合条件的 URL 解析一个支持的 UTM 参数,则推断的战役是 空无相.

## 软件包表面

核心曝光 SDK 层的可再用原始:

| 表面 | 目的 |
| --- | --- |
| `CoreStateful` | 浏览器、移动和桥接SDK的状态优化运行时间 |
| `CoreStateless` | 服务器 SDKs 的无端优化运行时间 |
| 活动方法 | `identify`, (中文(简体) ), `page`, (中文(简体) ), `screen`, (中文(简体) ), `track`, (中文(简体) ), `trackView`, (中文(简体) ), `trackClick`等 (中文(简体) ). |
| 解析和获取助手 | `resolveOptimizedEntry`, (中文(简体) ), `fetchContentfulEntry`, (中文(简体) ), `fetchContentfulEntries`, (中文(简体) ), `fetchOptimizedEntry`, (中文(简体) ), `prefetchManagedEntries`, (中文(简体) ), `getMergeTagValue`,以及 `getFlag` |
| 选择交接助手 | 框架中性选择状态、缓存密钥、缓存安全警告、批量输入分辨率以及 `createHandoffFromSelections` |
| 当前状态跟踪 | `AcceptedCurrentStateTracker` 用于 SDK 拥有的页面或屏幕适配器 |
| `states` | 状态可观测状态流 |
| 截取器 | 事件和州生命周期定制的第一当事方钩 |
| 队列策略并获取帮助 | 共享重试、冲出、超时和下线缓冲行为 |
| 信号和可观测公用事业 | SDK层内部使用的轻量级活性原始物 |
| `api-schemas` 进入点 | 由 Core 拥有的 CDA 计划, 加上经验 API 和 Insights API 计划 通道 |

### Schema 切入点

`@contentful/optimization-core/api-schemas` 拥有Contentful CDA计划,推断类型,以及 core 所用的助手 。 它还通过经验API和Insights API验证表面 从 `@contentful/optimization-api-client/api-schemas`,因此 SDK 层可以保留单个集合 有用时导入方案 :

```ts
import { OptimizationConfig, ExperienceResponse } from '@contentful/optimization-core/api-schemas'
```

对于直接经验API或Insights API的工作,从 `@contentful/optimization-api-client/api-schemas` 使用他们自己的包。 不添加导入 从被掠夺的 `@contentful/optimization-api-schemas` 兼容软件包.

当a `contentful.js` 客户端是可用的, 更喜欢 SDK 管理的获取 。 配置 `contentful: { client, defaultQuery?, cache? }`,然后通过ID或内容类型识别每个条目 和弹片 :

```ts
await sdk.fetchOptimizedEntry({
  contentType: 'page',
  slug: 'home',
  slugField: 'slug',
  entryQuery: { locale: 'en-US' },
})
```

`slugField` 默认为 `slug`。管理电话合并 `defaultQuery`, (中文(简体) ), `entryQuery`,SDK或请求 `locale` 倒计时 `include: 10`。然后强制检查 `content_type`, (中文(简体) ), `fields.<slugField>`,以及 `limit: 2`,因此,这些选择者将超过相冲突的查询值。 这个 当结果不独有时, 丢出这些错误 :

```text
Contentful entry not found for content type "<contentType>" where "fields.<slugField>" equals "<slug>".
Multiple Contentful entries found for content type "<contentType>" where "fields.<slugField>" equals "<slug>".
```

ID 检查保留相同平滑未标记条目的分批处理,并将大批分为 100 ID 块. 结果保持描述顺序和重复。 每个 SDK 管理取取缓存条目 默认实例; 设置 `contentful.cache: false` 以禁用缓存或调用 `clearContentfulEntryCache()` 来清理它。 粘住先发制人 固定的描述符 下级 `managedEntry` 并保留取入的条目 `sys.id` 内 `entryId`。 。 。 . `resolveOptimizedEntry()` 仍然是已获取的应用程序条目的手工路径 。 状态核心 在省略时使用当前选择, 受请求的无国籍客户使用最近接受的 选择和请求地方回落,而根无国籍者通过明确的选择.

解析器类型接受一个骨架或每个可能的基线和变异骨架的结合. 见 [条目优化和变量分辨率](https://contentful.github.io/optimization/documents/Documentation.Concepts.Entry_personalization_and_variant_resolution.html) 用于不同条目的打字和收缩.

框架 SDK 在服务器、 静态或边缘渲染时使用 Core 选择手动帮助 了解选中的优化 . `createHandoffFromSelections()` 明确选择的记录 状态和缓存元数据而不选择浏览器水合行为。 可缓存的公共布局 可使用 `createPublicPermutationCacheMetadata()` 确定性键和可选的呼叫者 无效标记 . `resolveEntriesForSelections()` 解决一组输入中的基线条目 服务器上加号的命令,以及 `createSelectionFingerprint()`, (中文(简体) ), `createOptimizationCacheKey()`, (中文(简体) ), `getOptimizationCacheSafetyWarnings()`,以及 `assertOptimizationCacheSafety()` 支持客户拥有的缓存密钥和诊断.

不要通过全本地 CDA 回复 `withAllLocales` 或者说 `locale=*`; 优化字段 作为 `fields.nt_experiences` 财务报告和审定财务报表 `fields.nt_variants` 必须是直接的单地字段值。 见 [条目优化和变量分辨率](https://contentful.github.io/optimization/documents/Documentation.Concepts.Entry_personalization_and_variant_resolution.html#single-locale-cda-entry-contract) 进入合同和 [优化 SDK 套件中的位置处理](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html) 为更广泛的地方模式.

### 自定义条目源适配器

`@contentful/optimization-core/entry-source` 自定义 JavaScript 运行时间的高级子路径 或 框架适配器不能使用正式的 Web, React Web, React 原生,节点,或原生SDK 表面。 它不是根核心 API 态势的一部分, 也不是优先应用的路径 一体化.

导入 `OptimizedEntrySourceController` 当适配器接受直接 `baselineEntry`,管理 条目ID,或管理的内容类型/污名源。 控制器拥有源生命周期和查询 键入、SDK准备/装入/反射快照、Stale请求保护,以及 `disconnect()` 清净相. 在取出弹片后,快照和下游追踪使用取取入的条目 `sys.id`。 。 。 . `createOptimizedEntryLoadingEntry(entryId)` 创建稳定的占位符 装入状态.

输入源控制器不拥有渲染,变异分辨率,跟踪,同意, 体验 API 调用,或 内容丰富的客户端创建 。 在一个快照后 `baselineEntry`,则 适配器仍然调用 `resolveOptimizedEntry()`,生成结果,并给任何运行时间指定线条 追踪.

生成的引用拥有方法参数、返回类型、召回有效载荷形状并继承 成员。 保持这个README专注于包角色和维护者取向.

## 预览支持

Preview-panel 助手在内部居住 [`preview-support`](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/packages/universal/core-sdk/src/preview-support/README.md) 输入。 它们被第一当事方预览表面用来注册预览状态桥,应用 优化本地作者工作流程的功能, 并绘制内容条目 .

应用程序代码不能直接使用预览支持, 除非它正在构建先行预览 表面.

## 相关

-   [选择正确的 SDK](https://contentful.github.io/optimization/documents/Documentation.Guides.choosing-the-right-sdk.html) - 说吧 应用程序集成软件包选择指南
-   [核心 SDK 生成参考](https://contentful.github.io/optimization/modules/_contentful_optimization-core.html) - 说吧 导出 API 引用
-   [优化 Web SDK](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/packages/web/web-sdk/README.md) - 浏览器SDK `CoreStateful`
-   [优化节点 SDK](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/packages/node/node-sdk/README.md) - 服务器SDK基于 `CoreStateless`
-   [优化反应原生 SDK](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/packages/react-native-sdk/README.md) - 移动式SDK `CoreStateful`
-   [API 客户端](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/packages/universal/api-client/README.md) - API直接运输和经验 API和Insights API 计划所有权
-   [API 斯克马斯](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/packages/universal/api-schemas/README.md) - 贬值的相容外观和进口迁移 指导
-   [核心预览支持](https://github.com/contentful/optimization/blob/optimization-core-v2.2.1/packages/universal/core-sdk/src/preview-support/README.md) - 内部预览帮助条目

## 常见问题

### @contentful/optimization-core 是什么？

内容优化平台不可识别核心 SDK

### 如何安装 @contentful/optimization-core？

在项目目录运行 npm install @contentful/optimization-core，或使用 pnpm add / yarn add / bun add。

### @contentful/optimization-core 支持 TypeScript 吗？

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

### @contentful/optimization-core 支持 ESM 还是 CommonJS？

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

### @contentful/optimization-core 可以商用吗？

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

### @contentful/optimization-core 的下载量有多少？

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

### @contentful/optimization-core 还在维护吗？

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