# @contentful/optimization-api-client 中文文档 规范地址：https://npmcn.com/package/%40contentful/optimization-api-client/ 版本：2\.2\.3 npm 元数据更新时间：2026-11-06T12:29:17.975Z 中文译文更新时间：2026-11-10T16:52:50.328Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40contentful/optimization-api-client 原文对照：https://npmcn.com/package/%40contentful/optimization-api-client/?lang=original 项目主页：https://github.com/contentful/optimization#readme 源码仓库：https://github.com/contentful/optimization ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.7 MB，33 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2026-02-03T12:42:25.731Z - 最新版本发布：2026-11-06T12:29:17.801Z - 近 30 天下载量：8298（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：27（近 12 个月 27 个） ## 中文简介 API 内容优化服务客户端 ## 安装 ```sh npm install @contentful/optimization-api-client ``` 也可以使用：`pnpm add @contentful/optimization-api-client`、`yarn add @contentful/optimization-api-client`、`bun add @contentful/optimization-api-client` ## README [![Contentful Logo](https://raw.githubusercontent.com/contentful/optimization/optimization-api-client-v2.2.3/contentful-icon.png "Contentful")](https://www.contentful.com/developers/docs/personalization/) # 内容个性化分析 ### API 客户端 [指南](https://contentful.github.io/optimization/documents/Documentation.Guides.html) • 妇女 [参考文献](https://contentful.github.io/optimization) • 妇女 [捐款](https://github.com/contentful/optimization/blob/optimization-api-client-v2.2.3/CONTRIBUTING.md) 内容优化 API 客户端为经验 API 和 API 提供低级传输 透视API. 应用程序化的 SDK 由事件构建器、状态管理器组成, 队列,以及运行时间的默认值. 我们建议用Web、React Web、节点或React Industern SDK开始应用。 使用此软件包 在建立或维护SDK层、测试、工具或第一当事方整合时直接使用 需要原始 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-api-client/#readme-getting-started) - [何时使用此软件包](https://npmcn.com/package/%40contentful/optimization-api-client/#readme-when-to-use-this-package) - [通用配置](https://npmcn.com/package/%40contentful/optimization-api-client/#readme-common-configuration) - [API 表面](https://npmcn.com/package/%40contentful/optimization-api-client/#readme-api-surface) - [经验 API](https://npmcn.com/package/%40contentful/optimization-api-client/#readme-experience-api) - [透视 API](https://npmcn.com/package/%40contentful/optimization-api-client/#readme-insights-api) - [Schema 切入点](https://npmcn.com/package/%40contentful/optimization-api-client/#readme-schema-entry-point) - [获取帮助](https://npmcn.com/package/%40contentful/optimization-api-client/#readme-fetch-helpers) - [相关](https://npmcn.com/package/%40contentful/optimization-api-client/#readme-related) ## 开始 使用与国家预防机制兼容的软件包管理器安装,例如: ```sh pnpm install @contentful/optimization-api-client ``` 进口和初始化统一的API客户端;支持CJS和无害环境管理模块系统,无害环境管理 首选 : ```ts import { ApiClient } from '@contentful/optimization-api-client' const client = new ApiClient({ spaceId: 'your-space-id', environment: 'master', }) ``` ## 何时使用此软件包 使用 `@contentful/optimization-api-client` 当您需要直接的低级访问体验 API或Insights API可运输地表. 当您需要优化时, 使用一个SDK 程序 状态,同意处理,事件构建者,条目解析,跟踪,或平台默认. ## 通用配置 | 选项 | 需要吗? | 默认 | 说明 | | --- | --- | --- | --- | | `spaceId` | 对 | 不详 | 经验和透视 API 请求的空间标识符 | | `environment` | 没有 | `'master'` | 体验和透视 API 具有内容的空间环境标识符 | | `experience` | 没有 | 见下文经验选项 | API 端点和默认请求选项 | | `insights` | 没有 | 见下文“透视”选项 | 透视 API 端点选项 | | `fetchOptions` | 没有 | SDK 默认 | 获取超时并重试行为 | 共同经验 API 选项 : | 选项 | 需要吗? | 默认 | 说明 | | --- | --- | --- | --- | | `baseUrl` | 没有 | `'https://experience.ninetailed.co/'` | 经验 API 的基础 URL | | `enabledFeatures` | 没有 | `['ip-enrichment', 'location']` | 用于突变请求的 API 特性 | | `ip` | 没有 | `undefined` | 经验 API 分析的 IP 地址覆盖 | | `locale` | 没有 | API 默认 | 本地化响应的地方查询参数 | | `location` | 没有 | API 倒计时 | 请求单个可显示突变的位置默认 | | `plainText` | 没有 | 特定终点 | 发送单调突变端点为文本 | | `preflight` | 没有 | `false` | 汇总一个配置状态而不存储它 | 经验突变请求选项 `baseUrl` 每个变异请求也可提供. `getProfile` 是已读请求,仅使用 `locale` 从每个呼叫选项; 仅变异选项 例如 `enabledFeatures`, (中文(简体) ), `ip`, (中文(简体) ), `location`, (中文(简体) ), `plainText`,以及 `preflight` 不适用。 单发突变 请求默认为 `plainText: true` 发送 `text/plain` 除非被推翻。 批次配置文件更新 与 `upsertManyProfiles` 是 JSON 默认例外和使用 `plainText: false` 默认. `locale` 作为经验 API 发送 `locale` 查询参数,并可以将配置字段本地化 作为 `location.city` 财务报告和审定财务报表 `location.country`。高级 SDK 合并工具 profile 值由经验 API 返回, 因此可以使本地化的内容 条目通常通过用于获取 CDA 条目的同一语言。 通过一个有效的地籍标签; 无效 语法可以失败Experience API请求验证. 见 [优化 SDK 套件中的位置处理](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html) 对于此请求的地语关系. 常见的透视 API 选项 : | 选项 | 需要吗? | 默认 | 说明 | | --- | --- | --- | --- | | `baseUrl` | 没有 | `'https://ingest.insights.ninetailed.co/'` | 透视 API 的基础 URL | 常见 `fetchOptions` 为: `fetchMethod`, (中文(简体) ), `requestTimeout`, (中文(简体) ), `retries`, (中文(简体) ), `intervalTimeout`, (中文(简体) ), `onFailedAttempt`,以及 `onRequestTimeout`。默认重试仅对 HTTP 适用 `503` 回应. 对于每个选项,回调有效载荷,请求类型和响应类型,使用生成的 [API 客户端参考](https://contentful.github.io/optimization/modules/_contentful_optimization-api-client.html)。 。 。 . ## API 表面 ### 经验 API API方法的范围包括: `client.experience` 并返回配置和优化数据: ```ts const { profile, selectedOptimizations, changes } = await client.experience.upsertProfile( { profileId: 'f0837d7dc6344c36a3a0a06c4cde754b', events: [pageEvent], }, { locale: 'de-DE' }, ) ``` 通用方法包括: `getProfile`, (中文(简体) ), `createProfile`, (中文(简体) ), `updateProfile`, (中文(简体) ), `upsertProfile`,以及 `upsertManyProfiles`。 。 。 . 应用程序可以通过正常的 SDK 配置请求位置 `api.location` 选项. 无国籍的节点集成可以通过 `forRequest({ experienceOptions: { location } })`; 见 [节点SDK配置](https://github.com/contentful/optimization/blob/optimization-api-client-v2.2.3/packages/node/node-sdk/README.md#common-configuration) 财务报告和审定财务报表 [Web SDK 配置](https://github.com/contentful/optimization/blob/optimization-api-client-v2.2.3/packages/web/web-sdk/README.md#common-configuration)。 。 。 . 下面的直接运输实例是针对SDK级和工具化消费者的. 对于 `createProfile`, (中文(简体) ), `updateProfile`,以及 `upsertProfile`设置 `location` 体验客户端 配置或按请求选项: ```ts import { ExperienceApiClient } from '@contentful/optimization-api-client' const experience = new ExperienceApiClient({ spaceId: 'your-space-id', environment: 'master', location: { countryCode: 'DE', country: 'Germany' }, }) await experience.createProfile({ events: [pageEvent] }) await experience.upsertProfile( { profileId: 'f0837d7dc6344c36a3a0a06c4cde754b', events: [pageEvent] }, { location: { countryCode: 'FR', country: 'France', city: 'Paris', coordinates: { latitude: 48.8566, longitude: 2.3522 }, }, }, ) ``` 与统一 `ApiClient`,将构造器默认值放入 `experience.location`。 。 。 . 按请求位置取代整个构建器默认;客户端不合并它们. 后端将每个事件合并 `context.location` 超过已解决的请求位置, 因此事件 字段覆盖匹配的请求字段。 如果两个源都未提供位置, 现有的后端 后退行为适用,包括Cloudflare在启用时请求地理定位. 过 `location: {}` 以覆盖构造器默认并提供一个空请求-位置默认 而不是Cloudflare的地理位置。 这不会抹去现有的配置文件位置 。 后端 从批次中带有非空位置的最新时间标记的事件中选择配置位置, 返回现有配置文件位置,如果没有。 请求位置受到影响 评价和配置更新;它不是一个永久位置锁定。 这个 `ip` 选项控制 IP 通过 `X-Force-IP` ,不控制剖面定位. `upsertManyProfiles` 不发送请求级别位置,包括构造器默认值. 对于批量更新,通过每次活动提供位置 `context.location`。 。 。 . 关于这些输入如何影响后续服务器和浏览器请求的配置连续性,请参见 [位置输入和简介更新](https://contentful.github.io/optimization/documents/Documentation.Concepts.Profile_synchronization_between_client_and_server.html#location-inputs-and-profile-updates)。 。 。 . ### 透视 API 透视 API 方法被限定为 `client.insights` 并发送满分的事件 `Profile` 由经验 API 返回: ```ts await client.insights.sendBatchEvents([ { profile, events: [viewEvent], }, ]) ``` 透视端点不返回响应数据. 对于最后的chance浏览器生命周期发送,通过 a 每一次通话 `beacon` 接收请求 URL 和已序列化正文的发件人 . A 类 `true` 结果意味着在使用取回时Beacon队列接受或成功的HTTP响应. 灯塔的接受不能证实服务提供情况;结果也证明分析的持久性. ### Schema 切入点 `@contentful/optimization-api-client/api-schemas` 拥有经验 API 和 Insights API 运行时间 此客户端使用的验证策略、 推断类型和验证助手 。 导入这些 在建立SDK层、工具或测试时从该切入点订立合同: ```ts import { ExperienceResponse } from '@contentful/optimization-api-client/api-schemas' ``` 此切入点不包括Contentful CDA计划. 导入 CDA 计划 `@contentful/optimization-core/api-schemas` 换句话说 核心切入点还提供了 既需要CDA合同,也需要API合同的SDK层的集合外表. ExO 交互事件使用 `Experience` 财务报告和审定财务报表 `ExperienceFragment` 实体类型。 他们接受 `parentVariantId` 对于根经验选取的变体, 包括 `default` 其基线。 这与被交付的实体本身无关 `variantId`。 。 。 . SDK 事件构建器提供这些值; 计程器在请求序列化时保存这些值 并接受更古老的事件 忽略它们. ### 获取帮助 此软件包还导出 SDK 层所使用的获取帮助函数 : | 帮助 | 目的 | | --- | --- | | `createProtectedFetchMethod` | 围绕获取方法添加超时并重试保护 | | `createRetryFetchMethod` | 应用重试策略来重试可操作的响应 | | `createTimeoutFetchMethod` | 在配置的超时后中止请求 | 用于帮助签名和回调有效载荷的参考文件. ## 相关 - [API 客户端生成引用](https://contentful.github.io/optimization/modules/_contentful_optimization-api-client.html) - 说吧 导出 API 引用 - [优化核心 SDK](https://github.com/contentful/optimization/blob/optimization-api-client-v2.2.3/packages/universal/core-sdk/README.md) - 平台不可知的 SDK 层 组成这个 客户端并拥有 CDA 计划 `/api-schemas` 进入点 - [API 斯克马斯](https://github.com/contentful/optimization/blob/optimization-api-client-v2.2.3/packages/universal/api-schemas/README.md) - 贬值的相容外观和进口迁移 指导 - [选择正确的 SDK](https://contentful.github.io/optimization/documents/Documentation.Guides.choosing-the-right-sdk.html) - 说吧 应用程序集成软件包选择指南 ## 常见问题 ### @contentful/optimization-api-client 是什么？ API 内容优化服务客户端 ### 如何安装 @contentful/optimization-api-client？ 在项目目录运行 npm install @contentful/optimization-api-client，或使用 pnpm add / yarn add / bun add。 ### @contentful/optimization-api-client 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @contentful/optimization-api-client 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @contentful/optimization-api-client 可以商用吗？ @contentful/optimization-api-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @contentful/optimization-api-client 的下载量有多少？ 根据 npm 官方下载统计，@contentful/optimization-api-client 在 2026/10/11 – 2026/11/09 这 30 天内被下载 8,298 次，日均约 277 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @contentful/optimization-api-client 还在维护吗？ 最新版本 2\.2\.3 发布于 2026/11/06（4 天前）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/02/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。