萨莱斯-阿皮

阅读下一节 关于从v2升级到v3的信息.

这个版本的库只与Elevate 4 Storefront API v3合作. 对 Elevate API v2 的支持仅限于 v1.x.x 本包中。 对于 升级信息 v2 版本,见 升级部分

向您提交请求的助手库 高级存储前置 API v3。 。 。 . 它包括所有HTTPS响应的类型定义和库 API.

所需资源

从 npm 安装软件包 :

npm install @apptus/esales-api

• 支持浏览器, Deno 和 Node v18+ 通过使用 globalThis.fetch() 发送请求的跨平台
• 船舶编码以无害环境管理和CJS格式捆绑
• 拥有现代ES2022代码的船舶——工具如 esbuild 可用于 支持旧平台/环境查看工具(中文(简体) )
• 见多填充 所需全球API的

使用量

完整 API 和所有选项/返回值由 Typescript 描述 定义dist/mod.d.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 (英语) 或者说 unpkg.com (英语),或者任何其他npm镜.

提供会议信息

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

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

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

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

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

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

用户背景

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

// 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>' } });

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

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

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

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

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

对于 仅限客户的SPA 连续的会话数据 LocalStorage 在v3之前 localStorageBackedSession() 帮助者提供救助 回调( 见 升级) (中文(简体) ). 它只管理 customerKey编号 :sessionKey 并且确实 没有 控件 userContext。 。 。 . 要与上下文决定配对, 请将回调包入:

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

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

升级

从v2到v3

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

• 新财产 session 在初始化 API 时需要 . 在v3之前,会话信息通过 LocalStorage。与以前一样的行为可以通过 方法 localStorageBackedSession()。 。 。 .

  // 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()。 。 。 .

  // 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 旗下,使库支持交叉平台.

  // 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一起导入产品时.

  // Before
  const api = esales({ ..., market: 'SE' });
  
  // After
  const api = esales({ ..., market: 'SE', locale: 'sv-SE' });
  

• 重命名参数 pageId 改为 pageReference,用于 query.landingPage() 请求.

  const api = esales(options);
  
  // Before
  api.query.landingPage({ ...params, pageId: id });
  
  // After
  api.query.landingPage({ ...params, pageReference: id });
  

• 变动 webApiId 改为 clusterId 用于初始化配置.

  // 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)不导入地图, (中文(简体) ), 但大多数的建造工具 都应该处理这一点.

此外,为了运送最小可能的捆绑,该代码正在使用 现代 ES2022 语法. 这与想要的浏览器支持无关 从盒子里出来,并且很可能 使用前需要转接。 。 。 .

转接

用 Webpack 构建时如何转换此库的例子 见下文。 类似的东西可以通过使用 include 属性为 @rollup/babel-plugin。 。 。 .

// 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

许可证

麻省理工学院