الأحداث

تتيح لك الأحداث تشغيل كود عندما يحدث شيء ما في السلة. توجد تحت window.aftersell.cart.events. الاشتراك هو استدعاء إعداد، لذا فهو آمن في أعلى سكربتك، دون حاجة لانتظار ready().

الأحداث المتاحة

الحدث	الحمولة	يُطلق عندما
`cart_loaded`	`AftersellCart`	تُحمَّل السلة، مرة واحدة لكل صفحة.
`cart_updated`	`AftersellCart`	تتغير محتويات السلة، بعد التحميل الأول.
`item_added`	`{ item }`	يظهر بند جديد في السلة.
`item_removed`	`{ item }`	يختفي بند من السلة.
`cart_opened`	لا شيء	يفتح الدرج.
`cart_closed`	لا شيء	يُغلق الدرج.
`checkout`	لا شيء	يُنقر زر إتمام الشراء.

الاشتراك

يسجّل events.on(event, handler) معالجًا ويُرجع دالة تلغي اشتراكه:

const off = window.aftersell.cart.events.on('cart_updated', (state) => {
  console.log('Cart total is now', state.totalPrice);
});

// later, to stop listening:
off();

events.once(event, handler): يعمل مرة واحدة، ثم يلغي اشتراكه بنفسه.
events.off(event, handler): يزيل معالجًا محددًا.

المعالج الذي يرمي خطأً يُعزل ويُسجَّل في وحدة التحكم؛ وتستمر بقية المعالجات في العمل.

القاعدتان

يعود كل خطأ متعلق بالأحداث تقريبًا إلى إحدى هاتين القاعدتين.

لا تغيّر السلة من `cart_updated` دون حارس

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

لا تستدعِ أبدًا إجراءً دون شرط من داخل cart_updated أو cart_loaded. احمِه بفحص للحالة التي أنت على وشك إنشائها، بحيث لا تفعل التمريرة الثانية شيئًا.

// ❌ Loops forever: every add triggers an update, which triggers another add.
window.aftersell.cart.events.on('cart_updated', (state) => {
  window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
});

// ✅ Guarded: once the gift is present, the condition is false and it stops.
window.aftersell.cart.events.on('cart_updated', (state) => {
  const hasGift = state.items.some((line) => line.variantId === GIFT_VARIANT_ID);
  if (state.totalPrice >= 5000 && !hasGift) {
    window.aftersell.cart.actions.addItem(GIFT_VARIANT_ID, 1);
  }
});

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

تعامل مع الحمولة على أنها للقراءة فقط

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

// ❌ Corrupts the payload for every later handler.
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items = state.items.filter((line) => line.finalLinePrice > 0);
});

// ✅ Copy first.
window.aftersell.cart.events.on('cart_updated', (state) => {
  const paidItems = state.items.filter((line) => line.finalLinePrice > 0);
});

لتغيير السلة فعليًا، استخدم إجراءً. ولتغيير كيفية عرض البنود، استخدم registerLineTransform.

cart_loaded

يُطلق مرة واحدة، عندما تُحمَّل السلة أول مرة على الصفحة. الحمولة هي كائن السلة الكامل.

window.aftersell.cart.events.on('cart_loaded', (state) => {
  console.log('Page loaded with', state.itemCount, 'items');
});

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

المنطق الذي يجب أن يكون صحيحًا عند تحميل الصفحة وعند كل تغيير لاحق ينبغي أن يشترك في كلٍ من cart_loaded وcart_updated بالدالة نفسها. هذا هو النمط القياسي لـ “إبقاء X متزامنًا مع السلة”.

cart_updated

يُطلق في كل مرة تتغير فيها محتويات السلة بعد التحميل الأول، سواء من الدرج أو من إجراءاتك أو من القالب أو من تطبيق آخر. الحمولة هي كائن السلة الكامل.

window.aftersell.cart.events.on('cart_updated', (state) => {
  document.querySelector('#my-total').textContent =
    window.aftersell.cart.actions.formatMoney(state.totalPrice);
});

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

أعد قراءة القاعدتين قبل استدعاء إجراء هنا.

item_added

يُطلق عندما يظهر بند جديد في السلة. الحمولة هي { item }، حيث item هو بند السلة.

window.aftersell.cart.events.on('item_added', (payload) => {
  myAnalytics.track('Added to cart', {
    id: payload.item.variantId,
    title: payload.item.title,
    quantity: payload.item.quantity,
  });
});

استخدمه من أجل: تتبّع الإضافة إلى السلة في أداة تحليلات تابعة لطرف ثالث. هذا هو الاستخدام الأكثر شيوعًا لـ SDK على الإطلاق. راجع تتبع الإضافة إلى السلة. أمران يجب معرفتهما حول كيفية اشتقاقه:

تغيير الكمية ليس إضافة. تستنتج السلة الإضافات والإزالات بمقارنة البنود، لا الكميات. متسوق يرفع بندًا من 1 إلى 3 يطلق cart_updated وليس item_added. إذا احتجت إلى التقاط زيادات الكمية أيضًا، فقارن مع الحالة السابقة داخل معالج cart_updated.

كما أنه لا يُطلق للعناصر التي كانت في السلة بالفعل عند تحميل الصفحة؛ فتلك تصل عبر cart_loaded. إضافة عدة منتجات مختلفة دفعة واحدة تطلق الحدث مرة لكل بند.

item_removed

يُطلق عندما يختفي بند من السلة. الحمولة هي { item }، وهي البند كما كان قبل اختفائه مباشرةً، لذا لا يزال بإمكانك قراءة key وvariantId وtitle الخاصة به.

window.aftersell.cart.events.on('item_removed', (payload) => {
  console.log('Removed', payload.item.title);
});

استخدمه من أجل: عكس شيء فعلته عند الإضافة، مثل مسح علامة، أو إعادة إظهار عرض رفضه المتسوق، أو إبلاغ التحليلات بعمليات الإزالة. نفس التحذير الخاص بـ item_added: خفض الكمية دون بلوغ الصفر ليس إزالة.

cart_opened وcart_closed

يُطلقان عند فتح الدرج وإغلاقه. بلا حمولة.

window.aftersell.cart.events.on('cart_opened', () => {
  myAnalytics.track('Cart viewed');
});

window.aftersell.cart.events.on('cart_closed', () => {
  document.body.classList.remove('cart-is-open');
});

استخدمهما من أجل: تتبّع المشاهدات، أو إيقاف فيديو أو عرض شرائح خلف الدرج مؤقتًا، أو تبديل صنف (class) على الصفحة. لا يُطلق أي منهما عند التحميل الأولي للصفحة، بل فقط عند فتح أو إغلاق فعلي.

checkout

يُطلق عندما ينقر المتسوق زر إتمام الشراء، مباشرةً قبل انتقال المتصفح. بلا حمولة.

window.aftersell.cart.events.on('checkout', () => {
  myAnalytics.track('Checkout started');
});

استخدمه من أجل: تتبّع نية إتمام الشراء.

لا يمكنك إلغاء إتمام الشراء من هذا المعالج. الحدث إشعار وليس بوابة؛ يحدث الانتقال بغض النظر عما يفعله كودك. أبقِ المعالج سريعًا ومتزامنًا: قد لا يكتمل await أو استدعاء شبكة بطيء قبل تفريغ الصفحة. استخدم navigator.sendBeacon لأي شيء تحتاج إلى إرساله بشكل موثوق.

الاستماع من خارج SDK

يُبثّ كل حدث أيضًا كـ CustomEvent من DOM على window، لذا يمكنك الاستماع دون لمس window.aftersell.cart. هذا مفيد من ملف قالب أو تطبيق تابع لطرف ثالث أو سكربت يُحمَّل مستقلًا عن السلة.

حدث الناقل	حدث DOM
`cart_loaded`	`aftersell:cart:cart-loaded`
`cart_updated`	`aftersell:cart:cart-updated`
`item_added`	`aftersell:cart:item-added`
`item_removed`	`aftersell:cart:item-removed`
`cart_opened`	`aftersell:cart:cart-opened`
`cart_closed`	`aftersell:cart:cart-closed`
`checkout`	`aftersell:cart:checkout`

انتبه للتسمية: يستخدم الناقل snake_case، بينما تستخدم أحداث DOM صيغة kebab-case خلف البادئة aftersell:cart:.

window.addEventListener('aftersell:cart:cart-updated', (event) => {
  console.log('Cart total is now', event.detail.totalPrice);
});

تصل الحمولة على event.detail وتطابق كائن السلة. تُبثّ الأحداث على window، لذا يستقبلها مستمع في أي مكان على الصفحة. تُعرض السلة داخل shadow root، لكن حد الظل لا يقع أبدًا في مسار الحدث. كل بثّ يستنسخ الحمولة، لذا فإن مستمعًا يعدّل event.detail لا يمكن أن يؤثر على أي طرف آخر، ومستمعًا يرمي خطأً لا يمكن أن يعطّل SDK.

لا يُعاد تشغيل cart-loaded على DOM. يعيد الناقل تشغيل cart_loaded للمشتركين المتأخرين، لكن ذلك المسار يتجاوز بثّ DOM، لذا فإن window.addEventListener('aftersell:cart:cart-loaded') المسجَّل بعد تحميل السلة بالفعل لن يعمل أبدًا. إذا لم يكن ترتيب تحميل سكربتك مضمونًا، فاستخدم window.aftersell.cart.events.on('cart_loaded', …) الذي يُعاد تشغيله، أو استمع أيضًا إلى aftersell:cart:cart-updated.

أحداث سلة Shopify القياسية

بشكل منفصل، تنشر السلة أحداث السلة القياسية الخاصة بـ Shopify على document كلما غيّرت السلة، بحيث يستطيع كود القالب والتطبيقات الأخرى التفاعل مع تعديلات Aftersell بالطريقة نفسها التي تتفاعل بها مع تعديلات القالب:

الحدث	الحمولة على كائن الحدث
`shopify:cart:lines-update`	`action: 'add' \| 'update' \| 'remove'`، `context: 'cart' \| 'product'`، `lines`
`shopify:cart:note-update`	`context: 'cart'`، `note`
`shopify:cart:discount-update`	`discountCodes: [{ code }]`

الحمولة ليست على event.detail. يحمل detail فقط { source: 'aftersell' } — الوسم الذي تستخدمه السلة لتجاهل أحداثها الخاصة بدلًا من الدوران في حلقة. كل ما في الجدول أعلاه يُسند مباشرةً على كائن الحدث، لذا اقرأ event.action وليس event.detail.action.

يحمل كل حدث أيضًا promise يسوّيه Aftersell عند اكتمال عملية الكتابة الأساسية، بما يطابق معيار Shopify — انتظره بـ await ولا تحلّه بنفسك. تُبثّ هذه الأحداث على document وتتصاعد، لذا يستقبلها مستمع على window أيضًا.

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

كائن السلة: الشكل الكامل للحمولات أعلاه.
الإجراءات: كيفية تغيير السلة من داخل معالج.
الخطافات: لتغيير كيفية عرض السلة، بدلًا من التفاعل معها.
حالات الاستخدام: تتبّع التحليلات والهدايا المجانية وأمثلة كاملة أخرى.

البدء

الصفحة الرئيسية

أفضل الممارسات

عروض البيع الإضافي بعد الشراء

سلة Aftersell

عروض البيع الإضافي في صفحة الدفع (Shopify Plus)

صفحة الشكر

عروض البيع الإضافي في صفحة المنتج

Rokt Thanks

الاستراتيجيات

التحليلات والتتبع

التكاملات

Aftersell MCP

الفوترة والحساب

استكشاف الأخطاء وإصلاحها

الأحداث المتاحة

الاشتراك

القاعدتان

لا تغيّر السلة من `cart_updated` دون حارس

تعامل مع الحمولة على أنها للقراءة فقط

cart_loaded

cart_updated

item_added

item_removed

cart_opened وcart_closed

checkout

الاستماع من خارج SDK

أحداث سلة Shopify القياسية

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

​الأحداث المتاحة

​الاشتراك

​القاعدتان

​لا تغيّر السلة من cart_updated دون حارس

​تعامل مع الحمولة على أنها للقراءة فقط

​cart_loaded

​cart_updated

​item_added

​item_removed

​cart_opened وcart_closed

​checkout

​الاستماع من خارج SDK

​أحداث سلة Shopify القياسية

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

الأحداث المتاحة

الاشتراك

القاعدتان

لا تغيّر السلة من `cart_updated` دون حارس

تعامل مع الحمولة على أنها للقراءة فقط

cart_loaded

cart_updated

item_added

item_removed

cart_opened وcart_closed

checkout

الاستماع من خارج SDK

أحداث سلة Shopify القياسية

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