Storefront API¶

Storefront API 提供了一个 JavaScript 接口（window.GiftHeroAPI），用于在您的店面上构建自定义的礼品卡选择和购买流程。

Storefront API 配置

启用 API¶

在左侧导航中进入 For developers。
勾选 Enable storefront API 并保存。

应用在您的礼品卡商品页面上生成的礼品卡界面会被关闭，转而加载 window.GiftHeroAPI。由您来构建界面。

该 API 不读取礼品卡余额。它收集购买者的选择，并将礼品卡添加到购物车中。

无头店面

在无头店面上，当无头模式和 Enable storefront API 都开启时，API 才会加载。请参阅无头集成。

初始化¶

API 异步加载。Gift Card Hero 准备就绪时会在 window 上触发一个事件。在调用任何方法之前，请先监听该事件：

window.addEventListener('gift.hero:initalized', function () {
  const api = window.GiftHeroAPI;
  // API is ready to use
});

事件名称拼写为 initalized

该事件名称存在拼写错误：gift.hero:initalized（只有一个 "i"）。请完全按照原样使用。该事件在 window 上触发，而不是 document 上，并且是在 Gift Card Hero 店面脚本加载完成之后。如果页面上没有该脚本，或店面 API 已关闭，则事件不会触发。

API 启动时，会选择第一个变体（或 ?variant= URL 参数中指定的变体）以及第一张图片。

方法¶

addToCart(quantity?, skipValidation?)¶

验证礼品卡数据，并使用 Shopify 的 /cart/add.js 将配置好的礼品卡添加到购物车中。

try {
  const result = await window.GiftHeroAPI.addToCart(1);
  // result: { status: 200, data: { ... } }
} catch (e) {
  // e: { status: 400, data: { errors: ['...'] } } when validation fails
}

参数	类型	默认值	说明
`quantity`	number	1	要添加的礼品卡数量
`skipValidation`	boolean	false	即使 `validate()` 报告错误，仍添加该卡

返回值： 一个 Promise，解析为 Shopify 购物车响应（{ status, data }）。验证失败时会以 { status: 400, data: { errors } } 拒绝。

generatePreview()¶

打开一个预览，使用目前已设置的数据展示礼品卡在收件人看来的效果。

window.GiftHeroAPI.generatePreview();

getImages()¶

返回可用于礼品卡的图片 URL 数组：您自己的设计、所选的内置设计，以及（如已启用）商品图片。

const images = window.GiftHeroAPI.getImages();
// ['https://cdn.shopify.com/...', 'https://cdn.shopify.com/...']

getOptions()¶

返回商品选项，包括可用的面额。

const options = window.GiftHeroAPI.getOptions();

getTranslations()¶

返回当前语言的界面翻译，例如标签和验证消息。

const translations = window.GiftHeroAPI.getTranslations();

getVariants()¶

返回商品变体数组。

const variants = window.GiftHeroAPI.getVariants();

setCardData(cardData)¶

一次性设置所有礼品卡数据。

window.GiftHeroAPI.setCardData({
  variantId: 12345678,
  image: 'https://cdn.shopify.com/...',
  message: 'Happy Birthday!',
  from: 'Alice',
  to: 'Bob',
  deliveryDate: new Date('2026-12-25'),
  email: 'recipient@example.com'
});

字段	类型	说明
`variantId`	number	所选变体 ID
`image`	string	所选卡片图片的 URL
`message`	string	礼品卡留言
`from`	string	发送人姓名
`to`	string	收件人姓名（可选）
`deliveryDate`	`Date`	计划发送日期，为 JavaScript `Date` 对象（可选）
`email`	string	收件人邮箱地址（可选）

API 不支持短信发送，因此没有电话字段。

单独的设置方法¶

方法	参数	说明
`setDeliveryDate(date)`	`Date`	设置计划发送日期。如果不是有效的日期对象，则抛出错误
`setEmail(email)`	string	设置收件人邮箱
`setFrom(name)`	string	设置发送人姓名
`setTo(name)`	string	设置收件人姓名
`setImage(image)`	string	设置所选卡片图片的 URL
`setMessage(message)`	string	设置礼品卡留言
`setVariant(variantId)`	number 或 string	设置所选变体
`setProperty(name, value)`	string, string	为购物车行项目添加额外的行项目属性

validate()¶

检查当前的礼品卡数据，并返回 { valid, errors }，其中 errors 是由您的翻译生成的消息数组。

const { valid, errors } = window.GiftHeroAPI.validate();

验证规则：

如果设置了收件人邮箱，则发送日期、发送人姓名（from）和留言为必填项。
如果设置了发送日期，则收件人邮箱、发送人姓名和留言为必填项。
若既没有邮箱也没有发送日期，则没有必填项。

setCustomAmount(amount)¶

以店铺货币选择自定义金额（例如 75 表示 75.00）。仅当店铺已开启自定义金额时有效；否则会抛出 Custom amount is not enabled。此方法不检查最低和最高限额，因此请自行验证金额。

window.GiftHeroAPI.setCustomAmount(75);

实体礼品卡¶

如果您销售实体礼品卡，请使用 setCardType('physical') 将 API 切换为实体礼品卡（使用 setCardType('eGift') 可切换回来）。

方法	说明
`setCardType(type)`	`'eGift'` 或 `'physical'`。选择 `'physical'` 时会选中第一个实体变体和图片
`getPhysicalProduct()`	实体礼品卡商品
`getPhysicalVariants()`	实体商品的变体
`getPhysicalImages()`	实体商品的图片 URL
`setPhysicalVariant(variantId)`	选择实体变体（仅限实体类型）
`setPhysicalDeliveryAddress(address)`	设置收货地址（仅限实体类型）：`firstName`、`lastName`、`address`、`zipCode`、`city`、`country`，以及可选的 `state`
`isPhysicalCard()`	选择实体类型时为 `true`

uploadCustomDesign(file, options?)¶

上传购买者自己的图片，并返回其 URL，可将该 URL 传给 setImage()。

const { url } = await window.GiftHeroAPI.uploadCustomDesign(file);
window.GiftHeroAPI.setImage(url);

文件必须为 JPG、PNG、GIF 或 WebP 图片，默认最大 5 MB。您可以通过 options.maxSize（字节）和 options.allowedTypes 更改限制。如果文件被拒绝，该方法会抛出一条含有明确信息的错误。

React 集成示例¶

JSFiddle 上提供了完整的 React 集成示例。它演示了如何初始化 API、构建自定义礼品卡选择界面，以及处理加入购物车的流程：

在 JSFiddle 上查看 React 示例