# @apptus/esales-api 中文文档

规范地址：https://npmcn.com/package/%40apptus/esales-api/

版本：3\.7\.0
npm 元数据更新时间：2026-09-04T07:08:23.508Z
中文译文更新时间：2026-11-06T12:42:30.440Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40apptus/esales-api
原文对照：https://npmcn.com/package/%40apptus/esales-api/?lang=original
项目主页：https://docs.elevate.voyado.cloud/elevate/4/

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

- 包体积（解压后）：404 kB，104 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2021-11-26T12:07:12.416Z
- 最新版本发布：2026-09-04T07:08:23.330Z
- 近 30 天下载量：12242（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：129（近 12 个月 3 个）

## 中文简介

向 Elevate 4 API v3 提出请求的图书馆

## 安装

```sh
npm install @apptus/esales-api
```

也可以使用：`pnpm add @apptus/esales-api`、`yarn add @apptus/esales-api`、`bun add @apptus/esales-api`

## README

# 萨莱斯-阿皮

> [阅读下一节](https://npmcn.com/package/%40apptus/esales-api/#readme-from-v2-to-v3) 关于从v2升级到v3的信息.

> 这个版本的库只与Elevate 4 Storefront API v3合作. 对 Elevate API v2 的支持仅限于 `v1.x.x` 本包中。 对于 升级信息 `v2` 版本,见 [升级部分](https://npmcn.com/package/%40apptus/esales-api/#readme-from-v1-to-v2)

向您提交请求的助手库 [高级存储前置 API v3](https://docs.elevate.voyado.cloud/elevate/4/api/storefront/v3/)。 。 。 . 它包括所有HTTPS响应的类型定义和库 API.

## 所需资源

从 npm 安装软件包 :

```
npm install @apptus/esales-api
```

-   支持浏览器, Deno 和 Node v18+ 通过使用 `globalThis.fetch()` 发送请求的跨平台
-   船舶编码以无害环境管理和CJS格式捆绑
-   拥有现代ES2022代码的船舶——工具如 `esbuild` 可用于 支持旧平台/环境[查看工具](https://npmcn.com/package/%40apptus/esales-api/#readme-tooling)(中文(简体) )
-   [见多填充](https://npmcn.com/package/%40apptus/esales-api/#readme-polyfills) 所需全球API的

## 使用量

完整 API 和所有选项/返回值由 Typescript 描述 定义`dist/mod.d.ts`与这个库捆绑在一起.

```ts
import { elevate } from '@apptus/esales-api';


const api = elevate({
  market: 'GB',
  locale: 'en-GB',
  clusterId: '<ID>',
  touchpoint: 'desktop',
  session: { customerKey: '<UUID>', sessionKey: '<UUID>' }
});

async function main() {
  const result = await api.query.searchPage({ q: 'jeans', limit: 60 });
  // Use the search result
}

main().catch(err => console.warn(err));
```

A 类 `CHANGELOG.md` 包含在软件包中,但 npm 无法显示 在线软件包中的单个文件。 更改日志可以读取 例如,《公约》规定. [esm.sh (英语)](https://esm.sh/@apptus/esales-api/CHANGELOG.md) 或者说 [unpkg.com (英语)](https://unpkg.com/browse/@apptus/esales-api/CHANGELOG.md),或者任何其他npm镜.

### 提供会议信息

这个 `session` 财产通过下列方式将每项请求与特定访客联系起来: `customerKey` 财务报告和审定财务报表 `sessionKey`当这些值在 API被初始化,直接作为对象传递:

```ts
const api = elevate({
  ...
  session: { customerKey: '<UUID>', sessionKey: '<UUID>' }
});
```

如果会话尚未可用, 或者您想要重读每页的值 查询和通知,提供回调。 每个都引用 ,因此它总是看到最新的值 :

```ts
const api = elevate({
  ...
  session: () => ({
    customerKey: readCookie('customerKey'),
    sessionKey: readCookie('sessionKey')
  })
});
```

对象和回调也可能是同步的;或者通过 直接承诺,或者从回电回话.

```ts
const api = elevate({
  ...
  session: async () => {
    const { customerKey, sessionKey } = await loadSession();
    return { customerKey, sessionKey };
  }
});
```

#### 用户背景

默认情况下,每个请求都被视为 **`PERSONALIZED`** - 绑在 访客的 `customerKey`编号 :`sessionKey` 个人化和 行为追踪 届会可以选择不同程度的同意 携带 `userContext`数字 :

```ts
// Fully anonymous — no keys, no personalization or tracking
elevate({ ..., session: { userContext: 'ANONYMOUS' } });

// Session-scoped but not personalized — sessionKey only
elevate({ ..., session: { userContext: 'UNPERSONALIZED', sessionKey: '<UUID>' } });
```

这四个背景和他们接受的关键:

| `userContext` | `customerKey` | `sessionKey` | 页:1 |
| --- | --- | --- | --- |
| `PERSONALIZED` | 所需经费 | 所需经费 | 默认时间 `userContext` 删除 |
| `UNPERSONALIZED` | —— 说 | 所需经费 |  |
| `ANONYMOUS` | —— 说 | —— 说 | 未发送密钥 |
| `SYNTHETIC` | 选项 | 选项 | 服务器接受但忽略的密钥 |

因为没有关键的背景(`ANONYMOUS` 财务报告和审定财务报表 `SYNTHETIC`没有钥匙, 上下文字符串可直接作为缩写传递 `{ userContext: '<context>' }`数字 :

```ts
elevate({ ..., session: 'ANONYMOUS' });  // same as { userContext: 'ANONYMOUS' }
```

由于它生活在会话元数据, `userContext` 以每一种形式工作—— 对象、承诺或召回(当一个没有键的 上下文是允许的)——因此,可以按请求决定,例如: 饼干同意的选择 :

```ts
const api = elevate({
  ...
  session: async () => {
    const { consented, customerKey, sessionKey } = await loadUserInfo();
    return consented ? { customerKey, sessionKey } : 'ANONYMOUS';
  }
});
```

对于 **仅限客户的SPA** 连续的会话数据 `LocalStorage` 在v3之前 `localStorageBackedSession()` 帮助者提供救助 回调( 见 [升级](https://npmcn.com/package/%40apptus/esales-api/#readme-from-v2-to-v3)) (中文(简体) ). 它只管理 `customerKey`编号 :`sessionKey` 并且确实 **没有** 控件 `userContext`。 。 。 . 要与上下文决定配对, 请将回调包入:

> \[注\] 对于在服务器上渲染网站的集成(Next.js, SvelteKit等), 页:1 `localStorageBackedSession()` 应避免效用. 在服务器上 `LocalStorage` 将不存在,如果 Storefront API 用于客户端和服务器,有更好的保存方式 页:1 `customerKey`\+ 键`sessionKey` 组合在它们之间同步.

```ts
const stored = localStorageBackedSession();
const session = () => (hasConsent() ? stored() : 'ANONYMOUS');
```

## 升级

### 从v2到v3

这个 `CHANGELOG.md` 包括完整的更改清单。 对于整合者 使用此软件包,升级时需要下列修改 改为版本 `3.0.0` 软件包:

-   新财产 `session` 在初始化 API 时需要 . 在v3之前,会话信息通过 `LocalStorage`。与以前一样的行为可以通过 方法 `localStorageBackedSession()`。 。 。 .
    
    ```ts
    // Before
    import { esales } from '@apptus/esales-api';
    
    const api = esales({
      clusterId: 'wABCD1234',
      market: 'UK',
      locale: 'en-GB',
      touchpoint: 'desktop'
    });
    
    // After
    import { esales, localStorageBackedSession } from '@apptus/esales-api';
    
    const api = esales({
      clusterId: 'wABCD1234',
      market: 'UK',
      locale: 'en-GB',
      touchpoint: 'desktop',
      session: localStorageBackedSession()
    });
    ```
    
-   这个 `session` 已配置 API 对象上的属性 已删除。 与读取/更新会议元数据有关的功能性 改为 `LocalStorage` 可以在返回的对象上找到 `localStorageBackedSession()`。 。 。 .
    
    ```ts
    // Before
    const api = esales({ ... });
    api.session.sessionKey;
    api.session.customerKey;
    api.session.customerKey = user.id;
    api.session.reset();
    
    // After
    const session = localStorageBackedSession();
    const { customerKey, sessionKey } = session();
    session.updateCustomerKey(user.id);
    session.reset();
    ```
    
-   全体 `esales().notify.*` 方法现在正在兑现承诺,应该 因此,为了避免未兑现的诺言,应采取行动。 之前,这些POST消息 经由 `Navigator.sendBeacon()`已替换为 `fetch()` 与 `keepalive` 旗下,使库支持交叉平台.
    
    ```ts
    // Before
    try {
      api.notify.click();
    } catch {
      // failed to queue POST request with notification
    }
    
    // After
    await api.notify.click().catch(() => {});
    // to ignore errors, or:
    try {
      await api.notify.click();
    } catch {
      // Network error or a non-OK HTTP status code
    }
    ```
    

### 从v1到v2

这个 `CHANGELOG.md` 包括完整的更改清单。 对于整合者 使用此软件包,升级时需要下列修改 改为版本 `2.0.0` 软件包:

-   新财产 `locale`,必须在 API 初始化中添加. 这个字段应该是与 `market` 与管理API一起导入产品时.
    
    ```ts
    // Before
    const api = esales({ ..., market: 'SE' });
    
    // After
    const api = esales({ ..., market: 'SE', locale: 'sv-SE' });
    ```
    
-   重命名参数 `pageId` 改为 `pageReference`,用于 `query.landingPage()` 请求.
    
    ```ts
    const api = esales(options);
    
    // Before
    api.query.landingPage({ ...params, pageId: id });
    
    // After
    api.query.landingPage({ ...params, pageReference: id });
    ```
    
-   变动 `webApiId` 改为 `clusterId` 用于初始化配置.
    
    ```ts
    // Before
    const api = esales({ ..., webApiId: 'w00000000' });
    
    // After
    const api = esales({ ..., clusterId: 'w00000000' });
    ```
    

我们还稍微清理了包裹的公共API表面, 删除一些内部/私人特性。 不应该有任何 因此,不应影响升级:

-   删除 `@apptus/esales-api/mock` 子模块。 它会显示一些帮助函数 用于创建 API 响应的被嘲笑对象.
-   删除 `api.query.settings()` 使用私人/无文件记录方法 API 终点
-   删除 `webApiUrl`。有可能为 `clusterId` 必要时。 任何集成器都应该选择使用ID而不是 URL `clusterId`。当提供 URL 到 `clusterId` 不应该有 (单位:千美元) `/api/v2/` 后缀,但只需用 `'/'` 或者说 `''`。 。 。 .

## 今后的工作

该图书馆正积极发展. 最高议程:

-   打开 Github 上的仓库源
-   制作 `CHANGELOG.md` (目前列入国家防范机制一揽子计划)

## 工具

此库被打包为零依赖性的ES模块. 这需要使用预处理器步骤,因为光入不是本地的 在浏览器中支持( n)[不导入地图](https://github.com/WICG/import-maps), (中文(简体) ), 但大多数的建造工具 都应该处理这一点.

此外,为了运送最小可能的捆绑,该代码正在使用 现代 `ES2022` 语法. 这与想要的浏览器支持无关 从盒子里出来,并且很可能 [使用前需要转接](https://npmcn.com/package/%40apptus/esales-api/#readme-transpilation)。 。 。 .

### 转接

用 Webpack 构建时如何转换此库的例子 见下文。 类似的东西可以通过使用 `include` 属性为 [`@rollup/babel-plugin`](https://github.com/rollup/plugins/tree/master/packages/babel)。 。 。 .

```js
// webpack.config.js
const { resolve } = require('path');

module.exports = {
  module: {
    rules: [
      {
        test: /\.m?js$/,
        type: 'javascript/auto',
        include: [resolve(__dirname, 'node_modules/@apptus/esales-api')],
        use: ['babel-loader']
      }
    ]
  }
};
```

### 圆柱体

根据所需的浏览器支持水平,可能需要多填充 在使用此库之前包含。 现假设以下API可用:

-   全体 `ES2015` API的软件
-   `globalThis.fetch`
-   `globalThis.URL`
-   `globalThis.crypto.randomUUID()` (仅在 `localStorageBackedSession()` 用于)
-   `Object.entries`
-   `Object.values`

## 许可证

麻省理工学院

## 常见问题

### @apptus/esales-api 是什么？

向 Elevate 4 API v3 提出请求的图书馆

### 如何安装 @apptus/esales-api？

在项目目录运行 npm install @apptus/esales-api，或使用 pnpm add / yarn add / bun add。

### @apptus/esales-api 支持 TypeScript 吗？

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

### @apptus/esales-api 支持 ESM 还是 CommonJS？

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

### @apptus/esales-api 可以商用吗？

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

### @apptus/esales-api 的下载量有多少？

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

### @apptus/esales-api 还在维护吗？

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