> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 自定义集成
> 直接调用 Strategies API 来驱动自定义店面体验——PDP 轮播、自定义购物车追加销售，以及 Aftersell 原生界面覆盖不到的任何地方。
## 概述
当 Aftersell 的原生界面（购买后、结账、Upcart）和现成的打包集成都不适用时，你可以从 Shopify 主题中自行调用 Strategies API，并以任意方式渲染返回的商品。
各种情况下的模式都相同：用 Liquid 构建上下文负载（这样当前商品、购物车内容和客户字段等 Shopify 属性会在渲染时被填充），将其 `POST` 到 `/api/public/strategy/evaluate`，然后渲染响应。
本页介绍两种实现模式：
* **PDP 上下文**——在商品页面放置一个 section，以**当前浏览的商品**调用 API，并以轮播形式渲染返回的推荐商品。
* **购物车上下文**——在自定义购物车内渲染一个追加销售区块，以**当前购物车的所有行项目**调用 API，并渲染返回的商品。
两者的区别在于**商品上下文**的形态：PDP 上是单个商品，购物车中是所有行项目组成的数组。
***
## 前置条件
1. \*\*你的 Strategy API 密钥。\*\*在 Aftersell 中，前往 **Settings → Product Strategy**，在 **Security Token** 卡片中复制你的令牌（这就是你的 Strategy API 密钥）。
2. \*\*Strategy ID。\*\*在 Aftersell Strategy 编辑器中打开你要运行的 Strategy 并复制其 ID。
3. \*\*主题代码访问权限。\*\*你将向 Shopify 主题中添加一个 Liquid section（PDP）或 block（自定义购物车）——Online Store → Themes → ... → Edit code。
你的 Strategy API 密钥位于客户端主题代码中，任何查看页面源代码的人都能看到它。请将其视为公开的店面凭证，如果它以你意料之外的方式暴露，请在 Aftersell 的 **Settings → Product Strategy** 中轮换它。
***
## PDP 上下文：Section 代码片段
此模式向你的商品页面添加一个 Shopify section。页面渲染时，Liquid 将当前商品、购物车和客户属性嵌入负载，然后 JavaScript 向 Strategies API 发送 POST 请求，并在 Splide 轮播中渲染返回的商品。
### 安装
1. 在 Shopify 后台，前往 **Online Store → Themes**，点击主题上的 **...**，选择 **Edit code**。
2. 在 **Sections** 文件夹下，创建一个名为 `aftersell-upsell-carousel.liquid` 的新文件。
3. 将下面的代码片段粘贴到新文件中，并将 `YOUR_STRATEGY_API_KEY` 替换为来自 Aftersell 的 API 密钥。
4. 保存。
5. 打开你的商品模板（通常是 `templates/product.json` 或 `sections/main-product.liquid`），在你希望轮播出现的位置添加 **Aftersell Carousel** section。你也可以在主题编辑器中直接将它拖到商品页面上。
6. 在该 section 的设置中，粘贴你的 **Strategy ID**。
### 该 section 发送的内容
对每次 PDP 浏览，负载包括：
* **products**——一个只含一个元素的数组，包含当前浏览的商品（productId、variantId、quantity、price、handle、title、vendor、productType、tags、collections、sellingPlan）。
* **cart**——顾客当前购物车的小计、商品件数、行数（购物车为空时省略）。
* **cartToken**——使 API 能将此次评估拼接到同一会话中。
* **customer**——标签、国家、省份、语言区域、订单数、总消费额和接受营销标记，但**仅当顾客已登录时**。
* **session**——来自 `shop.currency` 的货币代码。
该 section 默认不发送 UTM 参数。如果你希望在 PDP 上进行基于 UTM 的定向，请在客户端捕获它们，并在 fetch 之前将它们添加到 `session` 对象中。
### 代码片段
```liquid theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{% comment %}
Aftersell Carousel (Splide)
Type: Section — save to sections/aftersell-upsell-carousel.liquid
{% endcomment %}
{% if product %}
{{ section.settings.heading | default: 'You might also like' }}
{% endif %}
{% schema %}
{
"name": "Aftersell Carousel",
"settings": [
{ "type": "text", "id": "strategy_id", "label": "AfterSell Strategy ID", "default": "ADD_ID_HERE" },
{ "type": "text", "id": "heading", "label": "Heading", "default": "You might also like" },
{ "type": "text", "id": "cta_label", "label": "CTA Button Label", "default": "Add to cart" },
{ "type": "range", "id": "max_products", "label": "Max Products to Show", "default": 8, "min": 1, "max": 20, "step": 1 }
],
"presets": [{ "name": "Aftersell Carousel" }]
}
{% endschema %}
```
### 自定义
该 section 的 schema 提供了四个商家可编辑的设置：**Strategy ID**、**Heading**、**CTA Button Label** 和 **Max Products to Show**。在 `{% schema %}` 块中添加或移除设置，即可向主题编辑器暴露更多选项。
CSS 限定在 `.aftersell-*` 类名下，包含一个由 Splide 驱动的 4 列轮播，在 768px 时降为 2 列，在 480px 时降为 1 列。你可以随意编辑以匹配你的主题——这些样式都不是 API 调用正常工作的必要条件。
***
## 购物车上下文：自定义购物车追加销售区块
此模式在结构上与 PDP 模式相同，只有一个关键区别：**商品上下文数组**由购物车的行项目构建，而不是当前浏览的商品。Strategy 会接收顾客添加的每个商品，并基于整个购物车返回推荐。
具体实现位于你的自定义购物车代码所在的位置——渲染购物车抽屉的 Liquid section、无头店面中的自定义区块，或 `cart.liquid` 之类的主题模板。API 调用的形式和响应处理与 PDP 示例完全相同——只有 `products` 数组不同。
结构如下：
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
var products = {{ cart.items | json }}.map(function(item) {
return {
productId: 'gid://shopify/Product/' + item.product_id,
variantId: 'gid://shopify/ProductVariant/' + item.variant_id,
quantity: item.quantity,
price: item.price / 100
// ...other fields as needed
};
});
```
负载的其余部分（cart、customer、session、cartToken）以及对 `/api/public/strategy/evaluate` 的 `fetch` 调用与上文的 PDP 模式相同——只有 `products` 数组从 `[productContext]` 换成了由购物车派生的数组。
***
## Strategy 返回后会发生什么
无论你发送的是哪种上下文，响应形式都相同：
```json theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
{
"success": true,
"products": [ /* enriched recommended products */ ],
"evaluationId": "f3a1c2e0-...",
"resolution": { "strategyId": "...", "matchedRuleIds": [...], "fallbackUsed": false },
"meta": { "servedFromCache": false, "processingTimeMs": 12, "data": {} }
}
```
`evaluationId` 是本次评估的唯一 ID。如果你捕获它并将其附加到所渲染的商品上，就可以将最终产生的订单归因到产生它的确切推荐——见下文的[归因](#attribution)。
如何渲染 `products` 数组完全取决于你的主题代码。上面的 PDP 代码片段将它们渲染为带有变体选择器和加购按钮的卡片轮播；自定义购物车区块可以在抽屉内将它们渲染为垂直列表。
完整的请求和响应 schema 参见 [Evaluate Strategy API 参考](/zh/aftersell/strategies_api_reference_evaluate_strategy)。
***
## 未返回商品时
如果 Strategy 未返回任何商品（`products: []`），如何处理由你的代码决定。上面的 PDP 代码片段会完全隐藏轮播。自定义购物车区块可以回退到购物车的默认追加销售列表，或者干脆什么都不渲染。
为避免空响应，请在 Strategy 中配置 **Catch all**，这样始终会有一个可返回的兜底商品。有关如何设置 Catch all，请参见[构建 Strategies](/zh/aftersell/strategies_building_in_app) 页面。
***
## 自定义集成小贴士
* \*\*用 Liquid 构建上下文。\*\*Liquid 在渲染时运行，可以访问完整的 Shopify 对象图——product、cart、customer、shop、request。用它在服务端填充负载，而不是依赖客户端调用。
* \*\*不要把 API 密钥放进公开仓库。\*\*它最终会出现在你的主题代码中并被发送到浏览器——这没有问题。但不要把同一份主题粘贴到公开仓库或在外部分享打包文件。
* \*\*使用 Catch all。\*\*当某个位置消失时，店面体验会显得残缺。配置少量安全默认商品的 Catch all 可以保持 UI 一致。
* \*\*在合适的地方缓存。\*\*Strategies API 在服务端有轻量缓存（`meta.servedFromCache`），但对于高流量的 PDP，你可能还希望在客户端对调用进行防抖或记忆化（例如，同一商品在一个会话中被渲染两次时不要重复调用）。
***
## 归因
当顾客点击代码片段中的加购按钮时，`/cart/add.js` 调用会向购物车条目附加**行项目属性**：
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "Aftersell",
"_attribution": "CTA"
}
```
这些属性会随行项目一路传递到 Shopify 订单，出现在行项目记录中。你可以在下游用它们归因收入、筛选订单，或输入读取行项目属性的分析工具。
这里的键和值只是约定，不是必需的——无论你放什么，API 调用的行为都相同。你可以修改它们以适配自己的归因模型。例如：
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: {
"_source": "PDP Carousel",
"_strategy_id": "{{ section.settings.strategy_id }}",
"_campaign": "summer-2026"
}
```
以下划线（`_`）开头的属性键会在购物车和结账 UI 中隐藏，但仍会附加到订单上。对于不希望顾客看到的仅用于归因的元数据，请使用下划线前缀。
在购物车上下文的实现中应用同样的模式——你从自定义追加销售区块发起的任何加购调用都可以携带你需要的任何属性。
### 归因回具体评估
要将订单归因回推荐该商品的**确切评估**——而不仅仅是"来自某个 Strategy"——请从响应中捕获 `evaluationId`，并在 `__as_offer_id` 属性下将其附加到行项目。AfterSell 会读取这个键，因此带有该标记的订单会在报告中归因到具体的评估。
在 `evaluate()` 处理函数中，保存响应中的 ID：
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
.then(function(data) {
if (!data || !data.success || !data.products || !data.products.length) {
clearSkeletons(); return;
}
evaluationId = data.evaluationId; // declare `var evaluationId;` alongside your other state
renderCards(data.products.slice(0, MAX_PRODUCTS));
})
```
然后将其包含在加购属性中：
```js theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
properties: Object.assign(
{ "_source": "Aftersell", "_attribution": "CTA" },
evaluationId ? { "__as_offer_id": evaluationId } : {}
)
```
请保留 `__as_offer_id` 中的双下划线——这是 AfterSell 查找的键，且下划线前缀可使其对顾客隐藏。如果 `evaluationId` 不存在（例如未返回任何商品），请跳过该属性，而不要发送空值。
