ربط نسبيات أداة تصور الغرف بالطلبات المدفوعة#

التقط لقطة النسبية التي ينشرها Visualizer SDK، واحتفظ بها مع سلة العميل أو صفحة الدفع، وأبلغ عن الطلب النهائي المدفوع من خادمك.

لا يقوم SDK بتعديل عربة التسوق الخاصة بك أو الإبلاغ عن الطلبات تلقائيًا. يجب أن يتضمن التكامل الخاص بك:

1. التقاط أحدث لقطة في واجهة المتجر;
2. الاحتفاظ باللقطة الكاملة مع السلة والطلب; و
3. إرسال الطلب المدفوع إلى Ideal House من خادم موثوق.

1. التقاط اللقطة#

اقرأ ملفات تعريف الارتباط ih_visualizer عند تهيئة واجهة المتجر واستمع إلى ih:visualizer لاستقبال التحديثات. يحتوي ملف تعريف الارتباط على JSON مشفر بتنسيق URL. يوفر حدث المتصفح نفس الكائن في 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.

حقول لقطة الحالة هي:

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

احفظ واستبدل لقطة الحالة كاملة معًا. لا تقم بإعادة تسمية أو نسخ جزئي أو تعديل قيمها. تعامل مع البيانات المقروءة من ملف تعريف الارتباط على أنها غير موثوقة والتهمها إذا لم تكن كائنًا كاملًا بهذا الشكل.

إذا كانت صفحة الدفع تستخدم اسم المضيف نفسه أو منصة خارجية، انسخ اللقطة إلى السلة أو جلسة الخادم قبل أن يغادر العميل صفحة واجهة المتجر.

2. احتفظ بها مع الطلب#

عند اكتمال الدفع، أعد بناء اللقطة الأصلية من بيانات السلة أو الدفع أو تعريفات الطلب. إذا لم تكن اللقطة الكاملة متاحة، استخدم null بدلاً من إنشاء كائن جزئي.

تخزين اللقطة كقيمة JSON أو استخدام حقول البيانات الوصفية الموصى بها التالية:

حوّل 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 في جسم الطلب.

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 مطلوبًا:

{
  "visualizer": null
}

4. معالجة إعادة المحاولات#

إنشاء event_id مستقر لحدث الطلب المدفوع وإعادة استخدامه مع كل محاولة إعادة إرسال.

مثال على استجابة النجاح:

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

5. قائمة تحقق للتكامل#

1. تأكد من أن واجهة المتجر قادرة على قراءة ih_visualizer بعد استخدام أداة التصور.
2. تأكد من أن مستمع ih:visualizer يحدث بيانات السلة أو تعريفات الدفع.
3. تأكد من وصول لقطة الحالة الكاملة إلى الطلب المدفوع.
4. قدّم طلب اختبار مدفوع من خادمك وتوقع HTTP 200.
5. قدّم نفس الحدث مرة أخرى بنفس event_id وقبول duplicate: true كنجاح.
6. قدّم طلبًا بدون نسبيات باستخدام "visualizer": null.
7. تأكد من أن Client Secret وبيانات العميل الشخصية لا تظهر أبدًا في طلبات المتصفح أو بيانات الطلب المُقدَّمة.