无头集成¶

Gift Card Hero 支持不使用 Shopify 标准主题系统的无头 Shopify 店面。启用无头模式即可获得集成代码片段，将其嵌入您的自定义店面即可。

第 1 步：启用无头模式¶

在左侧导航中进入 For developers。在 Headless mode 卡片中，点击 Enable headless mode。状态标签会变为 Enabled。点击保存栏中的 Save 以保留更改。

启用无头模式

第 2 步：复制集成代码¶

无头模式启用后，页面上会显示一段代码片段。点击 Copy to clipboard。该片段包含一个空的 <div id="sc-giftcard-builder">、一个配置代码块以及 Gift Card Hero 的店面脚本。请将其添加到您的礼品卡商品页面。

集成代码片段

第 3 步：替换占位符¶

代码片段中包含占位值，您必须将其替换为您店铺的具体信息：

占位符	替换为	示例
`[MONEY_FORMAT]`	您店铺的货币格式字符串	`${{amount}}`
`[PRODUCT_ID]`	您礼品卡商品的 Shopify 数字 ID	`7654321098765`
`[MYSHOPIFY_DOMAIN]`	您店铺的 `.myshopify.com` 地址	`my-store.myshopify.com`
`[ADD_TO_CART_CALLBACK]`	处理将商品加入购物车的 JavaScript 函数	`addItemToCart`
`[LOCALE]`	您翻译所用的语言代码	`en`

[PRODUCT_ID] 是数字，在代码片段中没有引号。其余占位符位于引号之中。请将 '[ADD_TO_CART_CALLBACK]' 连同其引号一起替换为您的函数（例如 addToCart: addItemToCart），因为 Gift Card Hero 会将其作为函数调用。

货币格式¶

货币格式字符串决定价格的显示方式。页面会在占位符旁边以示例形式显示您店铺自己的货币格式。格式代码请参阅 Shopify 的货币格式指南。

常见格式：

${{amount}} — 美元
{{amount}} EUR — 欧元
${{amount}} CAD — 加元

商品 ID¶

查找礼品卡商品的 Shopify ID：

打开 Shopify Admin
进入 Products
点击您的礼品卡商品
查看浏览器地址栏中的网址，数字 ID 位于末尾

例如，如果网址为 https://admin.shopify.com/store/my-store/products/7654321098765，则商品 ID 为 7654321098765。

加入购物车回调¶

[ADD_TO_CART_CALLBACK] 占位符应替换为您的店面用于将商品加入购物车的 JavaScript 函数名称。Gift Card Hero 会以一个对象调用该函数，并期望返回一个 promise：

function addItemToCart({ items, sections }) {
  // items: [{ id: <variant id>, quantity: 1, properties: { ... } }]
  // Add the line to your cart (for example a Storefront API cart) and return a promise.
}

properties 包含买家的选择（留言、发送人、收件人、发送日期以及礼品卡设计数据）。请将所有这些内容原样传递到您的购物车行项目中，以便正确创建礼品卡。如果缺少该函数，加入购物车会失败，并提示“Add to cart method is not defined in headless mode”。

语言¶

[LOCALE] 占位符用于设置 Gift Card Hero 界面的语言。请使用您在应用翻译中设置的语言代码，并完全按照相同的写法（例如 en 或 fr）。如果省略，默认为 en。

代码片段如何获取设置¶

页面加载时，店面脚本会使用您的 [MYSHOPIFY_DOMAIN]、[PRODUCT_ID] 和 [LOCALE]，从 https://gifthero.syncu.be/api/configuration/headless 请求您的礼品卡设置、商品和翻译。该请求无需登录。结果会缓存约一分钟，在应用中保存设置会刷新缓存。

如果商品 ID 有误，请求会失败并返回 Product id is incorrect，且不会显示任何内容。如果代码片段中缺少货币格式、商品 ID 或店铺信息，脚本会在浏览器控制台中给出提示。

自定义金额¶

如果您销售自定义金额的礼品卡，金额必须保持在您在应用中设置的最低和最高金额之间；服务器会拒绝超出范围的金额。通过 Gift Card Hero 创建结账时，服务器会根据您的设置重新构建订单，因此无法在浏览器中更改价格。在此流程中，买家会被引导至服务器返回的结账链接，而不会调用您的加入购物车函数。

集成之后¶

代码片段嵌入并替换占位符后，Gift Card Hero 会在您的店面中显示其礼品卡选择界面。如果您想构建自己的界面，而不是使用应用的礼品卡构建器，还需在 For developers 页面中勾选 Enable storefront API。此时将不再显示构建器，并会为您加载 Storefront API（window.GiftHeroAPI），供您调用。