متى تحتاج ربط أنظمة شركتك؟ وكيف تختار طريقة التكامل المناسبة؟

1. ابدأ من عملية العمل، لا من الـAPI

قبل اختيار تقنية التكامل، صنّف عملية العمل التي تحتاج الربط: ما الحدث الذي يبدأ سير العمل؟ من يملك المصدر؟ من يحتاج النتيجة؟ ماذا يحدث عند الفشل؟

• ما الذي يبدأ التكامل؟
• أي نظام مصدر البيانات؟
• أي نظام يستهلك البيانات؟
• هل يحتاج المستدعي إلى إجابة فورية؟
• ما السلوك المتوقع عند فشل الاتصال؟
• من يتابع ويملك التكامل بعد الإطلاق؟

2. حدد النظام المرجعي قبل مزامنة البيانات

لا تتبع مزامنة فقط لتقليل اختلافات العرض. قرّر أي نظام هو صاحب الحقيقة لكل نطاق بيانات (عميل، منتج، مخزون، فاتورة) لتجنب تعارضات ومشاكل التصحيح لاحقاً.

• عَيّن مالك كل كيان بيانات.
• وثّق الحقول التي تظل مرجعية ومتى يجب الاعتماد على التحديثات الخارجية.
• صمّم استراتيجية لإعادة التوافق (reconciliation) عند وجود تعارض.

3. متى تختار متزامن أو غير متزامن أو مجدول

اختر طريقة الاتصال بناءً على حاجة العملية لحداثة البيانات والاعتمادية المتوقعة. بعض حالات الاستخدام تحتاج تأكيداً فورياً، والبعض الآخر يقبل معالجة متأخرة أو مجمعة.

• متزامن (API): عندما تحتاج نتيجة فورية أو قبول/رفض مباشر.
• غير متزامن (رسائل/أحداث): عندما تريد فصل الاعتمادية وتقليل تأثر المتصل.
• مجدول (batch): عندما لا تحتاج لحداثة عالية وتريد كفاءة معالجة الدفعات.

4. Cart attributes وoptimistic UI — ماذا تغيّر Shopify

أعلنت Shopify في 6 أغسطس 2026 أن معيار storefront الآن يدعم تعديل سمات السلة (cart attributes) عبر الإجراء المعياري updateCart، وأن حدثاً جديداً shopify:cart:attributes-update يُطلق عند بدء تحديث السمات. هذا التغيير يسمح لتنفيذ واجهات مستخدم متفائلة (optimistic UI) مع آلية تأكيد/تراجع تعتمد على وعد (promise) يأتي مع الحدث.

• الحدث يُضمّن مجموعة السمات الكاملة التي يجب أن تحل محل السمات السابقة (replace‑all).
• الحدث يتضمن event.promise الذي يحلّ أو يرفض حسب نتيجة التحديث؛ الحل قد يتضمن userErrors توضح مشاكل تحقق القيم.
• عند حل الوعد لا تحتوي كائنات السلة المرجعة على attributes؛ يجب قراءة event.attributes أو استدعاء جلب منفصل بعد النجاح.

1. 1راجع changelog Shopify للتاريخ والبيان الرسمي: https://shopify.dev/changelog/events-and-actions-cart-attributes-support.
2. 2اطّلع على مرجع الحدث لمعرفة الشكل والوضوح حول replace-all وpromise: https://shopify.dev/docs/api/storefront-events-and-actions/events/cart-attributes-update.
3. 3راجع مرجع updateCart لفهم سلوك التحديث وطرق تحديث واجهة المتجر: https://shopify.dev/docs/api/storefront-events-and-actions/actions/update-cart.

5. نمط التنفيذ لواجهة متفائلة باستخدام الحدث

نمط متوقع وآمن: طبّق التغيير فوراً في الواجهة باستخدام event.attributes ثم انتظر event.promise لتأكيده أو التراجع عن التغيير إذا فشل أو عاد مع userErrors.

• عند استلام shopify:cart:attributes-update طبّق event.attributes فوراً على الواجهة لخفض زمن الإدراك.
• انتظر event.promise. إذا حُلّ بلا أخطاء، حافظ على التغييرات؛ إذا حُلّ مع userErrors أو رُفض، قم بإرجاع الحالة السابقة وعرِض رسالة خطأ مفهومة للمستخدم.
• عند رفض الوعد بشكل كامل، استمع أو أطلق shopify:cart:error وفق إرشادات Shopify لتوحيد معالجة الأخطاء عبر الثيمات والتطبيقات.

1. 1إعداد طلب التحديث: عند إرسال تحديث السمات، أرسِل مصفوفة السمات كاملة (replace-all).
2. 2تطبيق الواجهة: خزّن نسخة محلية من السمات السابقة قبل التطبيق لتسهيل التراجع.
3. 3تأكيد/تراجع: عند تحقق event.promise، اضبط الحالة النهائية أو عدّل الواجهة للنسخة السابقة وعدّ المستخدم بسبب userErrors.

6. متى تستخدم Shopify.actions.updateCart مقابل Storefront API مباشرة

عندما تعمل داخل الثيم أو تتحكم بالثيم والتطبيق معاً، فضّل استخدام Shopify.actions.updateCart لأنّه يوحّد سلوك تحديث واجهة المتجر ويُصدر الحدث القياسي. استخدم Storefront API المباشر لكتابات من الخادم أو عندما تحتاج أن تتجاوز سلوك التحديث المعياري للثيم.

• استخدام updateCart: يبسّط التوافق بين ثيمات والتطبيقات، ويُشغّل الأحداث القياسية، ويتيح سلوك تحديث واجهة مكوّن بحسب إعدادات الثيم.
• استخدام Storefront API: مناسب للكتابات من جانب الخادم، أو لعمليات تتطلب تجاهل سلوك تحديث الثيم، أو لعمليات خلفية غير مرتبطة بواجهة المتصفح.
• تحقّق من إعدادات الثيم لأنّ سلوك التحديث يختلف: بعض المتاجر قد تستخدم إعادة تحميل كاملة كتصرف افتراضي إذا لم تُفعّل إجراءات التحديث المعيارية.

7. قائمة اختبار وQA للسمات المتفائلة والتحديثات المتزامنة

اختبارات مهمة لتجنب فقدان البيانات ومشكلات التزامن عند اعتماد الحدث والإجراء المعياري.

• حاكي تحديثات متزامنة من ثيم وتطبيق خارجي لاكتشاف سباقات التحديث.
• اختبر المسار المتفائل مع تراجع: جعل الشبكة تفشل مؤقتاً وتحقق أن التراجع يعيد الواجهة بحالة متسقة ويعرض الأخطاء.
• تحقق من أن حذف مفتاح في مصفوفة السمات يزيله فعلياً من السلة كما هو متوقع.
• اختبر على ثيمات متعددة: تحقق من سلوك التحديث داخل ثيمات تُهيّئ updateCart مقابل تلك التي تعتمد إعادة تحميل الصفحة.
• اختبر تدفقات التسليم المسرّع (accelerated checkout) وتحقق إن كانت سمات السلة محفوظة ومُرسلة خلال الطريق إلى الخروج.

8. الأمان وخطة الترحيل والتشغيل

السمات قابلة للتعديل من جهة العميل؛ لا تعتمد عليها كحقيقة موثوقة دون تحقق من جهة الخادم. عند الانتقال من استدعاءات Storefront API أو منطق polling، ضع خطة تجريبية ومراقبة للتراجع السريع.

• لا تستخدم السمات كحساسيات أمان أو لإصدار قرارات موثوقة دون تحقق خادمي.
• سجّل نتائج event.promise مع معرف السلة (cart id) وuserErrors للقياس والتصحيح.
• خطّة ترحيل: حصر الأماكن التي كانت تستخدم Storefront API أو polling، نفّذ نموذج الحدث في مجموعة صفحات صغيرة، راقب السلوك واطلق ترحيل مرحلي.
• راقب وتحليل لقطات ما قبل/بعد عند نشر التغييرات لتجنب فقدان السمات أو حذفها عن طريق خطأ في payload.

1. 1جرد الاستخدام الحالي للسمات: أنشئ قائمة بمصادر التعديل (ثيمات، تطبيقات، تكاملات خادم).
2. 2التنفيذ المرحلي: فعل السلوك أولاً في بيئة staging ثم على مجموعة صغيرة من المتاجر/المستخدمين.
3. 3المراقبة والتراجع: أنشئ تنبيهات على زيادة userErrors أو رفض الوعود واحتفظ بخطة تفعيل roll-back.
4. 4تحديث الاختبارات: أضف اختبارات تلقائية لمسارات النجاح، رفض الوعد، وحالات السباق.

الأسئلة الشائعة

هل حدث shopify:cart:attributes-update يُستخدم فقط للثيمات؟ لا. الحدث يُطلق عندما يبدأ تحديث السمات سواء بمبادرة من الثيم أو تطبيق أو كود مخصص، لذلك المصمّمون والمطوّرون يجب أن يتعاملوا مع حدوث تحديثات متزامنة ومشاكل السباق.

ماذا يعني أن السمات بصيغة replace-all؟ يعني ذلك أن المصفوفة المرسلة يجب أن تحتوي على مجموعة المفاتيح الكاملة التي تريد الاحتفاظ بها في السلة؛ حذف مفتاح من المصفوفة سيحذف ذلك المفتاح من السمات الفعلية.

الخلاصة

توحيد تحديث سمات السلة عبر updateCart وshopify:cart:attributes-update يبسط التوافق بين الثيمات والتطبيقات ويوفّر آلية واجهة متفائلة قابلة للتراجع. اتّبع نمط التطبيق المتفائل مع انتظار event.promise، اختبر حالات السباق والتراجع، ولا تعتمد على السمات لقرارات أمان دون تحقق خادمي.