接入前指引

Headless SDK 用于在 Shopify 自建店面（如 Hydrogen、Next.js、Nuxt 等不使用 Liquid 主题的站点）中售卖邮包险（SP）和延保险（PP）。阅读本页约需 5 分钟，你将了解接入前的准备事项、需向客户经理（AM）确认的后台配置，以及后续文档的阅读路线。

SDK 做什么，你做什么

职责维度	SDK 负责	你的站点负责
界面渲染	渲染 SP 面板、PP 面板及各自的弹窗	渲染商品页、购物车页、购物车抽屉及结账按钮
报价计算	计算 SP 报价与 PP 方案价格	—
购物车写入	默认 adapter 下通过 Shopify Storefront API 写入费用行与保障行，配置 adapter 时走你的接口；pp.addToCart 串起主商品写入、同步与保障	实现 pp.addToCart 的主商品回调、修改数量、删除商品行、跳转结账页
状态同步	SDK 写车或 syncCart 确认购物车后，触发你注册的 onCartChange 回调；它只通知已确认事实，不代表业务成功	修改购物车后，调用 syncCart(cart.id)

SDK 渲染面板与弹窗（包括面板开关和弹窗按钮），不会改写站点已有的按钮。面板挂载在站点配置的容器内，弹窗由 SDK 单独挂载。结账、加购与购物车补购按钮由站点渲染，并在点击事件中调用对应的 SDK 方法（详见各场景章节）。

不要重复写入

费用行与保障行已由 SDK 写入购物车，请勿再通过 Xcotton OpenAPI 重复写入同样的行，否则同一份保障会被写入两次。OpenAPI 仅用于补充 SDK 未覆盖的服务端能力，详见 选择接入方式。

准备清单

• 店铺已安装 Xcotton Shopify 插件。
• 已获取该店铺的 Shopify Storefront API Public Access Token（默认 adapter 用它读写购物车）。
• 店铺已启用 SDK v0.3（版本代号 030）。本系列文档与类型声明文件仅适用于 v0.3；若存量项目运行的是 v0.2（024），请先阅读 从 v0.2 升级到 v0.3。
• 页面初始化时可获取当前市场的三个参数并传给 SDK：国家（country）、币种（currency）和语言（language）。

国家和币种必须与 Shopify Markets 一致

传给 SDK 的 country 必须与购物车买家国家及 Shopify Markets 当前市场一致，currency 必须为该市场实际结算返回的币种。购物车自身币种也必须与 currency 一致，币种守卫会在不一致时拒绝同步；country 不一致不会被守卫拦截，但可能导致面板报价与费用行或结账金额不符。language 可独立切换；它决定面板文案，并作为 Storefront 查询与报价请求的语言参数，不会改变结算币种。

和客户经理（AM）确认的配置

以下配置由客户经理（AM）在后台设定，无法通过前端代码修改。由于它们直接决定你要编写哪些接入代码，请在开发前逐项确认：

配置项	可选值	对接入代码的影响
SP 是否开启	开 / 关	关闭时 window.xcotton.sp 为 undefined，可跳过所有 SP 章节
PP 是否开启	开 / 关	关闭时 window.xcotton.pp 为 undefined，可跳过所有 PP 章节
SP 适配模式	cart、checkout、checkout+	决定结账按钮的调用逻辑，详见 适配模式
SP 面板样式与文案	带开关（cart / checkout）/ 仅显示报价（checkout+）	面板样式须与适配模式配合；cart / checkout 需要表达顾客意愿的开关，checkout+ 由站点的两个结账按钮表达意愿
SP 开关默认状态	开 / 关	决定新访客首次打开购物车时的开关初始状态
PP 面板主题与文案	—	无需改动代码
加购时是否打开 PP 方案弹窗	是 / 否	canBePopup() 按此项判断顾客未选方案时是否弹窗；pp.addToCart() 内部复用同一判断
是否显示购物车加购保险按钮	是 / 否	关闭时 getCartQuotes() 返回 { enabled: false, quotes: [] }

术语表

后续章节将直接使用以下术语：

术语	含义
邮包险（SP）	Shipping Protection，按整个购物车计价的运输保障。顾客投保后，购物车中会新增一条费用行。
延保险（PP）	Product Protection，按单件商品计价的延长保障。顾客投保后，主商品旁会新增一条关联的保障行。
费用行	SP 写入购物车的商品行，代表邮包险费用。
保障行	PP 写入购物车的商品行，与对应的主商品行关联。
主商品行	顾客购买的常规商品所在的购物车行（即 Storefront API 的 CartLine）。
适配模式	SP 费用行写入购物车的时机，分为 cart、checkout、checkout+ 三种。
面板	SDK 渲染到站点预留容器内的 SP 或 PP 交互界面。
绑定购物车	调用 syncCart(cartId) 告知 SDK 当前页面使用的购物车。首次绑定、切换购物车与同车刷新都用这一个方法，SDK 自行判断属于哪一种。
adapter	可选适配器。当购物车读写必须经过站点自有 API 或 BFF 时，用于替换 SDK 默认的 Storefront API 请求。

阅读路线

1. 快速开始（必读）：加载 SDK，将 SP 面板渲染到购物车页。
2. 购物车同步（必读）：厘清 syncCart 与 onCartChange 的调用方向——绝大多数接入问题都源于混淆两者。
3. 若已开启 SP：阅读 适配模式；当模式为 checkout 或 checkout+ 时，继续阅读 Checkout 适配模式 或 Checkout+ 适配模式。
4. 若已开启 PP：阅读 接入延保险，再按需阅读 延保险弹窗 与 购物车加购保险按钮。
5. 进阶与参考：若购物车读写经过自有 API 或 BFF，请阅读 使用自己的购物车 API；完整方法签名、类型定义与错误码速查见 SDK 参考。