将可视化器归因与已付款订单关联#

捕获Visualizer SDK发布的归因快照，将其与客户购物车或结帐信息一同保留，并从您的服务器报告最终已付款订单。

SDK 不会自动修改您的购物车或上报订单。您的集成必须：

在店铺前台捕获最新快照；
将完整快照与购物车和订单一同保留；以及
从受信任的服务器将已付款订单发送至Ideal House。

1. 捕获快照#

店铺前台初始化时读取ih_visualizercookie，并监听ih:visualizer以接收更新。cookie包含URL编码的JSON。浏览器事件在event.detail中提供相同对象。

function readVisualizerAttribution() {
  const prefix = 'ih_visualizer='
  const value = document.cookie
    .split(';')
    .map(part => part.trim())
    .find(part => part.startsWith(prefix))
    ?.slice(prefix.length)

  if (!value) return null

  try {
    return JSON.parse(decodeURIComponent(value))
  } catch {
    return null
  }
}

window.addEventListener('ih:visualizer', event => {
  saveAttributionWithCart(event.detail)
})

const currentAttribution = readVisualizerAttribution()
if (currentAttribution) {
  saveAttributionWithCart(currentAttribution)
}

使用商业平台的购物车属性、结帐元数据或服务器端会话API实现saveAttributionWithCart。

快照字段如下：

json

{
  "visitor_id": "anonymous-visitor-id",
  "session_id": "visualizer-session-id",
  "categories": ["wall", "furniture"],
  "last_used_at": "2026-09-10T12:34:56.000Z"
}

一起存储并替换完整快照。请勿重命名、部分复制或修改其值。将从 Cookie 读取的数据视为不可信，如果它不是具有此形状的完整对象，请丢弃。

如果您的结帐使用其他主机名或外部平台，请在客户离开店铺前台页面之前，将快照复制到购物车或服务器端会话中。

2. 将其与订单一同保留#

付款完成后，从购物车、结帐或订单元数据中重建原始快照。如果没有完整的快照可用，请使用null，而不是构建部分对象。

将快照存储为 JSON 值，或使用以下推荐的元数据字段：

元数据字段	值
`idealhouse_visitor_id`	`visitor_id`
`idealhouse_session_id`	`session_id`
`idealhouse_categories`	`categories`用逗号连接
`idealhouse_last_used_at`	`last_used_at`

在报告订单之前，将idealhouse_categories转换回JSON字符串数组。

3. 报告已付款订单#

从后端或已付款订单webhook处理器调用此端点。切勿从浏览器JavaScript调用它。

http

POST <IDEALHOUSE_API_URL>/integrations/commerce/order-events
Content-Type: application/json
X-Client-Id: <CLIENT_ID>
X-Client-Secret: <CLIENT_SECRET>

使用与店铺前台SDK相同的Ideal House店铺的凭据。不要在请求正文中包含shop_id或shopId。

bash

curl -X POST "<IDEALHOUSE_API_URL>/integrations/commerce/order-events" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-Client-Secret: <CLIENT_SECRET>" \
  -d '{
    "schema_version": 1,
    "event_id": "store-42-order-paid-1001",
    "event_type": "order.paid",
    "source": {
      "platform": "custom",
      "store_id": "store-42"
    },
    "order": {
      "id": "order-1001",
      "order_number": "#1001",
      "customer_po_number": null,
      "created_at": "2026-09-10T11:55:00.000Z",
      "paid_at": "2026-09-10T12:00:00.000Z",
      "financial_status": "paid",
      "currency": "USD",
      "subtotal": "125.50",
      "total": "143.25",
      "line_items": [
        {
          "id": "line-1",
          "product_id": "product-1",
          "variant_id": "variant-1",
          "sku": "WP-100",
          "product_type": "Wallpaper",
          "quantity": 2,
          "unit_price": "62.75",
          "total_price": "125.50"
        }
      ]
    },
    "visualizer": {
      "visitor_id": "anonymous-visitor-id",
      "session_id": "visualizer-session-id",
      "categories": ["wall", "furniture"],
      "last_used_at": "2026-09-09T12:00:00.000Z"
    }
  }'

货币值以 JSON 字符串格式发送。每条时间戳均须包含时区。仅发送已文档化的字段；客户姓名、邮箱地址、电话号码以及账单或收货地址均不予接收。

对于没有完整归因快照的订单，visualizer字段仍是必填项：

json

{
  "visualizer": null
}

4. 处理重试#

为已支付订单事件创建一个稳定的event_id，并在每次重试时复用该值。

响应	操作
HTTP 200	成功。`duplicate: true`也是成功结果。
网络错误或 HTTP `5xx`	使用退避策略和相同的 `event_id` 重试。
HTTP 400	在重试之前更正请求。
HTTP 401或403	检查服务器凭据。
HTTP 409	停止并检查`event_id`是否被用于其他订单。

成功响应示例：

json

{
  "accepted": true,
  "duplicate": false,
  "visualizer_assisted": true
}

5. 集成检查清单#

确认使用可视化器后，店铺前台可以读取ih_visualizer。
确认ih:visualizer监听器会更新购物车或结帐元数据。
确认完整快照已到达已支付订单。
从服务器提交一个已付款测试订单，预期收到HTTP 200。
使用相同的event_id再次提交同一事件，并将duplicate: true视为成功。
使用"visualizer": null提交一个无归因的订单。
确认Client Secret和客户个人数据永远不会出现在浏览器请求或提交的订单数据中。