Skip to main content
تتيح لك السكربتات المخصصة تشغيل JavaScript الخاص بك على السلة باستخدام Cart SDK. أضفها في محرر السلة تحت Cart settings → Custom script، حيث تبدّل قائمة منسدلة بين خانتين: Initialization وOn cart update. اكتب JavaScript عاديًا في هذين المحررين، دون وسوم <script>. لخانة On cart update إجراء Reset to default يعيد قالبها الأولي؛ أما Initialization فلا، لذا احتفظ بنسختك الخاصة قبل مسحها.
كثير مما اعتاد التجار كتابته كسكربتات أصبح الآن إعدادًا مدمجًا. راجع قبل أن تكتب سكربتًا أولًا: الإعداد يستمر في العمل عبر عمليات إعادة تصميم السلة، أما سكربتك فقد لا يستمر.

أي خانة تستخدم

Initialization

يعمل سكربت Initialization مرة واحدة عند تحميل السلة. وهو نقطة دخولك لإعداد الأمور: تكوين سلوك السلة والاشتراك في الأحداث وتسجيل الخطافات (hooks). يتوفر SDK عبر window.aftersell.cart. استدعاءات الإعداد التي تجريها هنا (configure(...) وevents.on(...) وhooks.*) آمنة الاستدعاء في أعلى السكربت حتى قبل اكتمال إقلاع السلة؛ فهي تُخزَّن مؤقتًا وتُطبَّق بمجرد اكتماله. أما الإجراءات التي تقرأ السلة أو تغيّرها (مثل addItem أو getCart) فينبغي تشغيلها داخل ready() أو داخل معالج حدث. تبدأ الخانة بثلاثة أمثلة معلّقة (commented-out) — فتح الدرج عند كل إضافة، والتفاعل مع cart_loaded، وإخفاء أسطر الهدايا المجانية — لذا فإن سكربت Initialization غير المعدَّل لا يفعل شيئًا. أزل التعليق عن أحدها لتجربته، أو استبدلها. الشكل الطبيعي لهذه الخانة هو تسجيل لمرة واحدة دون أحداث: سجّل السلوك مرة واحدة ودع السلة تطبّقه من ذلك الحين. إخفاء أسطر الهدايا المجانية من الدرج، دون تغيير الإجمالي، هو المثال المشحون لذلك:
يعمل registerLineTransform لكل سطر أثناء عرضه، وsetHidden مخصص للعرض فقط، لذا يبقى السطر في السلة ويظل محتسبًا في الإجمالي، لكنه لا يظهر في الدرج فحسب. راجع إخفاء أسطر السلة وإعادة تسميتها لمزيد مما يمكن للتحويل فعله. الإجراءات التي تقرأ السلة توضع داخل ready():
الوصول إلى DOM السلة يحتاج الانتظار نفسه، ويحتاج shadowRoot: تُعرض السلة داخل shadow root، لذا لا يمكن لـ document.querySelector رؤية أي شيء في الدرج.
هل تتفرع حسب السوق أو البلد أو العملة قبل تحميل السلة؟ اقرأ context بدلًا من ذلك. فهو متاح بشكل متزامن، دون الحاجة إلى ready()، لتتمكن من تخطي تسجيل المعالجات كليًا للمتسوقين الذين لا تنطبق عليهم القاعدة.

On cart update

يعمل سكربت On cart update في كل مرة تتغير فيها السلة. وهو غلاف مقفل حول اشتراك cart_updated، فلا تحرر إلا الجسم، ويستقبل كودك كائن cart المحدّث. هذه الخانة للقواعد التي يجب إعادة تقييمها عند كل تغيير في السلة. عتبة الهدية المجانية هي الحالة الكلاسيكية (أنفق 75$ واحصل على حقيبة مجانية) لأن الإجابة تعتمد على المحتويات الحالية ولا شيء آخر يمكنه إخبارك بموعد تغيرها:

إبقاء السلة في الحالة المرغوبة

السطر if (shouldHaveGift === hasGift) return; هو ما يجعل هذا آمنًا، وهو يعمّم على كل سكربت يُبقي السلة في حالة مرغوبة. هذه الخانة تتفاعل مع تغييرات السلة وتسبّبها معًا، لذا فإن كل addItem أو removeItem يعيد الدخول إليها. صِف الحالة التي تريدها، وقارنها بالحالة الموجودة، وعُد مبكرًا عندما تتفقان بالفعل، ليصل المعالج إلى الاستقرار بعد مرور واحد بدلًا من الدوران في حلقة. راجع القاعدتين للنسخة غير المحمية الواجب تجنبها ولماذا الحمولة للقراءة فقط. في متجر أبطأ يُستحسن أيضًا الاحتفاظ براية “قيد التنفيذ” على مستوى الوحدة، حتى لا يبدأ تغييران متسارعان عملية إضافة قبل هبوط الأولى.
لا يُطلق cart_updated إلا عند التغييرات بعد التحميل الأول (توقيت الأحداث)، لذا لن يصحح سكربت في هذه الخانة سلة مؤهلة أصلًا عند تحميل الصفحة. لنسخة تعالج الحالتين، اشترك في cart_loaded وcart_updated بالدالة نفسها من خانة Initialization. راجع إضافة هدية مجانية تلقائيًا عند عتبة.

عندما يتعطل سكربت

تعمل كل خانة في بيئة معزولة خاصة بها، لذا لا يمكن لسكربت Initialization معطوب أن يوقف تشغيل On cart update، ولا يمكن لأي منهما تعطيل السلة نفسها. لكن داخل الخانة الواحدة، يتوقف التنفيذ عند أول خطأ. كل ما تحت ذلك السطر يُتخطى، ما يعني أن أي configure أو events.on أو hooks.register* أدناه لا يُسجَّل أبدًا. هذا هو التفسير المعتاد لـ”معالجي لا يعمل أبدًا” عندما يبدو الكود صحيحًا. تذكر السلة السطر المتعطل في وحدة تحكم المتصفح، وتعمل كل خانة باسم ملف خاص بها (aftersell-cart-init.js وaftersell-cart-cart-update.js)، لذا يمكنك فتح أيهما من لوحة Sources في DevTools ووضع نقاط توقف. راجع تصحيح الأخطاء للرسائل الدقيقة، ولقناة التصحيح التي تلتقط أخطاء الخطافات المحجوبة عن وحدة التحكم. ولأن cart_loaded يُعاد بثه للمشتركين المتأخرين، لا يهم ترتيب التسجيل أبدًا. أسلم بنية هي تسجيل كل شيء أولًا وتنفيذ العمل الخطر داخل المعالجات، حيث يُعزل أي خطأ يُرمى في ذلك المعالج وحده.

إلى أين تتجه بعد ذلك