เชื่อมโยงการอ้างอิง Visualizer กับยอดสั่งซื้อที่ชำระเงินแล้ว#

ดึงข้อมูล attribution snapshot ที่เผยแพร่โดย Visualizer SDK เก็บไว้กับตะกร้าหรือขั้นตอนการชำระเงินของลูกค้า และรายงานคำสั่งซื้อที่ชำระเงินเสร็จสิ้นจากเซิร์ฟเวอร์ของคุณ

SDK ไม่ได้ปรับเปลี่ยนตะกร้าของคุณหรือรายงานคำสั่งซื้อโดยอัตโนมัติ การบูรณาการของคุณต้อง:

1. จับ snapshot ล่าสุดในหน้าร้านออนไลน์;
2. เก็บ snapshot ทั้งหมดไว้กับตะกร้าและคำสั่งซื้อ; และ
3. ส่งยอดสั่งซื้อที่ชำระเงินแล้วไปยัง Ideal House จากเซิร์ฟเวอร์ที่เชื่อถือได้

1. จับ snapshot#

อ่านคุกกี้ ih_visualizer เมื่อหน้าร้านออนไลน์ของคุณเริ่มต้น และรับฟัง ih:visualizer เพื่อรับการอัปเดต คุกกี้มี URL-encoded 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)
}

ปรับใช้ saveAttributionWithCart กับแอตทริบิวต์ตะกร้า เมตาข้อมูลการชำระเงิน หรือเซสชันด้านเซิร์ฟเวอร์ API ของแพลตฟอร์มการค้าของคุณ

ฟิลด์ของ snapshot คือ:

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

เก็บและแทนที่ snapshot แบบครบถ้วนร่วมกัน อย่าเปลี่ยนชื่อ คัดลอกบางส่วน หรือแก้ไขค่าต่างๆ ถือว่าข้อมูลที่ได้จาก cookie เป็นข้อมูลที่ไม่น่าเชื่อถือและห้ามใช้หากไม่ใช่ object ที่สมบูรณ์และมีโครงสร้างตามนี้

หากขั้นตอนการชำระเงินของคุณใช้โฮสต์เนมอื่นหรือแพลตฟอร์มภายนอก ให้คัดลอก snapshot เข้าไปในตะกร้าหรือเซสชันด้านเซิร์ฟเวอร์ก่อนที่ลูกค้าจะออกจากหน้าหน้าร้านออนไลน์

2. เก็บไว้กับคำสั่งซื้อ#

เมื่อการชำระเงินเสร็จสมบูรณ์ ให้สร้าง snapshot เดิมอีกครั้งจากตะกร้า เมตาข้อมูลการชำระเงิน หรือเมตาข้อมูลคำสั่งซื้อของคุณ หากไม่มี snapshot ที่สมบูรณ์ ให้ใช้ null แทนการสร้างออบเจกต์บางส่วน

เก็บ snapshot ไว้เป็นค่า JSON หรือใช้ช่อง metadata ที่แนะนำดังนี้:

แปลง idealhouse_categories กลับเป็นอาร์เรย์สตริง JSON ก่อนส่งรายงานคำสั่งซื้อ

3. ส่งรายงานยอดสั่งซื้อที่ชำระเงินแล้ว#

เรียกจุดปลายทางนี้จากแบ็กเอนด์หรือตัวจัดการ webhook ยอดสั่งซื้อที่ชำระเงินแล้ว ห้ามเรียกจากเบราว์เซอร์ JavaScript

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

ใช้ข้อมูลรับรองสำหรับร้าน Ideal House เดียวกับ หน้าร้านออนไลน์ SDK อย่าใส่ shop_id หรือ shopId ใน body ของคำขอ

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 ใส่โซนเวลาในทุก timeStamp ส่งเฉพาะฟิลด์ที่ระบุในเอกสารเท่านั้น; ชื่อลูกค้า อีเมล เบอร์โทรศัพท์ และที่อยู่สำหรับเรียกเก็บเงินหรือจัดส่งไม่ยอมรับ

สำหรับคำสั่งซื้อที่ไม่มี attribution snapshot ที่สมบูรณ์ ฟิลด์ visualizer ยังคงจำเป็น:

{
  "visualizer": null
}

4. จัดการคำขอซ้ำ#

สร้าง event_id ที่มั่นคงสำหรับเหตุการณ์สั่งซื้ อที่ชำระแล้ว และนำมาใช้ซ้ำในทุกการลองส่งใหม่

ตัวอย่างการตอบสนองที่สำเร็จ:

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

5. รายการตรวจสอบการผสานรวม#

1. ยืนยันว่าหน้าร้านออนไลน์สามารถอ่าน ih_visualizer ได้หลังใช้ Visualizer
2. ยืนยันว่าผู้ฟัง ih:visualizer อัปเดตแอตทริบิวต์ตะกร้าหรือเมตาข้อมูลการชำระเงิน
3. ยืนยันว่า snapshot แบบครบถ้วนถึงคำสั่งซื้อที่ชำระเงินแล้ว
4. ส่งคำสั่งซื้อทดสอบที่ชำระเงินจากเซิร์ฟเวอร์ของคุณ และคาดหวัง HTTP 200
5. ส่งเหตุการณ์เดียวกันอีกครั้งด้วย event_id เดียวกัน และถือว่า duplicate: true เป็นความสำเร็จ
6. ส่งคำสั่งซื้อโดยไม่มีการอ้างอิงโดยใช้ "visualizer": null
7. ยืนยันว่า Client Secret และข้อมูลส่วนบุคคลของลูกค้าไม่ปรากฏในคำขอเบราว์เซอร์หรือข้อมูลคำสั่งซื้อที่ส่งเลย