نظرة عامة

Cart SDK هي واجهة برمجة تطبيقات JavaScript لسلة Aftersell على واجهة متجرك. تتيح لك تغيير سلوك السلة، والتفاعل مع ما يقوم به المتسوقون، وقراءة محتويات السلة أو تغييرها من خلال التعليمات البرمجية. يمكنك تشغيل تعليمات SDK البرمجية عبر النصوص البرمجية المخصصة، أو عبر وضع React في كتلة التعليمات البرمجية المخصصة لكتلة تعرض واجهتها الخاصة.

كثير مما يطلبه التجار من SDK متوفر بالفعل كإعداد. قبل كتابة نص برمجي، تحقق مما إذا كانت كتلة سلة، أو الشروط حسب السوق/الدولة/العملة، أو أحد إعدادات السلة يقوم بذلك بالفعل. فهذه تستمر في العمل عبر عمليات إعادة تصميم السلة، بينما قد لا يستمر نصك البرمجي.

نقطة الدخول العامة

كل شيء يتفرع من متغير عام واحد:

window.aftersell.cart

كل مقتطف في هذه الوثائق يكتب window.aftersell.cart بالكامل، بحيث يعمل أي منها بمفرده عند لصقه. كما أن إنشاء اسم مختصر له مرة واحدة (const cart = window.aftersell.cart;) واستخدام cart من ذلك الحين فصاعدًا صالح تمامًا أيضًا، وآمن حتى قبل تحميل السلة. فقط تذكّر تضمين ذلك السطر إذا اختصرت مقتطفًا، لأن cart بمفردها تُلقي الخطأ cart is not defined.

أربعة أجزاء تقوم بالعمل:

التهيئة

حدّد سلوك السلة: متى يُفتح الدُرج، وكيف يتم تنسيق العملة، وما إذا كانت Aftersell تعترض الإضافة إلى السلة.

الأحداث

تفاعل مع ما يحدث: تم تحميل السلة، تمت إضافة عنصر، فُتح الدُرج، تم النقر على الدفع.

الإجراءات

اقرأ السلة وغيّرها: افتحها، أضف عنصرًا، حدّث كمية، اقرأ الحالة الحالية.

الخُطافات

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

إذا توقف أحد سكربتاتك عن العمل عند الإضافة إلى السلة، فابدأ من اعتراض الإضافة إلى السلة. فهو يشرح لماذا يتولى Aftersell عملية الإضافة، وكل طريقة لاستثناء نموذج.

بالإضافة إلى ثلاثة أعضاء أصغر:

العضو	ما هو الغرض منه
`ready()`	وعد (Promise) يتحقق بمجرد تحميل السلة لأول مرة.
`context`	سياق المشتري المعروض من الخادم، قابل للقراءة بشكل متزامن.
`shadowRoot`	الجذر الظلي (shadow root) للسلة، للاستعلام عن العناصر داخل الدُرج.

أحداث أم إجراءات أم خُطافات؟

من السهل الخلط بين الثلاثة، واختيار الخيار الخاطئ هو السبب الأكثر شيوعًا لعدم قيام النص البرمجي بما توقعه كاتبه:

تريد أن…	استخدم	مثال
تشغّل تعليمات برمجية عند حدوث شيء ما	حدث	إرسال حدث تحليلات عند إضافة عنصر.
تغيّر ما بداخل السلة	إجراء	إضافة هدية مجانية بمجرد تجاوز الإجمالي 50$.
تغيّر طريقة عمل السلة أو عرضها	خُطاف	إخفاء أسطر الهدايا المجانية من الدُرج.

الفرق الأهم: الإجراء يغيّر سلة المتسوق الفعلية (وإجماليه)، بينما الخُطاف يغيّر ما يُعرض فقط. إخفاء سطر بخُطاف يُبقيه في السلة وفي الإجمالي؛ أما إزالته بإجراء فتخرجه فعليًا.

كيف ومتى يتم التحميل

تُحمَّل السلة على مرحلتين، وقد بُنيت SDK بحيث لا تضطر إلى التفكير في الترتيب:

بذرة (stub) صغيرة تنشئ window.aftersell.cart فورًا، لذا فهي موجودة دائمًا.
تُحمَّل SDK الكاملة بعد ذلك بوقت قصير وتتولى الأمر، مطوّرةً البذرة في مكانها، لذا يستمر المرجع الذي التقطته سابقًا في العمل.

هذا يمنحك فئتين من الاستدعاءات:

استدعاءات الإعداد: آمنة فورًا

configure(...) و events.on(...) وكل استدعاء hooks.register*. تُخزَّن مؤقتًا قبل الإقلاع وتُعاد بالترتيب بمجرد تحميل SDK. ضعها في أعلى نصك البرمجي.

الإجراءات: انتظر ready()

كل شيء ضمن actions.*. شغّلها داخل ready() أو داخل معالج حدث. إذا استُدعيت مبكرًا جدًا فإنها تحذّر في وحدة التحكم ولا تفعل شيئًا، بأمان: فالإجراءات غير المتزامنة لا تزال تتحقق، لذا لن تنكسر سلسلة .then().

// Set-up: fine at the top level, before the cart has loaded.
window.aftersell.cart.configure({ open_on_add_to_cart: 'always' });

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

// Actions: wait until the cart is ready.
window.aftersell.cart.ready().then(() => {
  const state = window.aftersell.cart.actions.getCart();
  console.log(state.itemCount, 'items');
});

ready()

تُعيد ready() وعدًا يتحقق بمجرد استقرار أول تحميل للسلة. وهي تتحقق عند الفشل كما عند النجاح، لذا لن يترك متسوق على اتصال متقطع نصك البرمجي معلقًا أبدًا. تحقق من getCart() بحثًا عن null بدلًا من افتراض وصول سلة. استدعاء ready() بعد أن تكون السلة قد حُمّلت بالفعل يتحقق فورًا، لذا فهي آمنة للاستخدام كبوابة عامة تعني “السلة موجودة الآن” في أي مكان في تعليماتك البرمجية.

لا تحتاج إلى ready() داخل معالج حدث. فبحلول وقت انطلاق cart_loaded أو cart_updated أو item_added، تكون السلة محمّلة والإجراءات آمنة للاستدعاء.

context

يحمل window.aftersell.cart.context بيانات المشتري المعروضة من الخادم، وهي قابلة للقراءة بشكل متزامن، دون الحاجة إلى ready(). استخدمه للتفريع حسب السوق أو الدولة الذي يجب أن يحدث قبل تحميل السلة.

الحقل	الوصف	متاح قبل الإقلاع
`shopify_market`	سوق Shopify الخاص بالمشتري.	نعم
`customer_country`	رمز الدولة المكوّن من حرفين.	نعم
`customer_currency`	رمز العملة النشطة.	نعم
`money_format`	تنسيق العملة في Shopify الخاص بالمتجر.	نعم
`backend_url`	مضيف الخادم الخلفي المباشر، يُستخدم كبديل عندما لا يكون وكيل التطبيق مهيأً.	نعم
`storefront_access_token`	رمز مميز لاستدعاءات Storefront API.	لا — يُضاف عند إقلاع السلة

storefront_access_token هو حقل context الوحيد الذي لا يعرضه الخادم داخل cart.context. يُضاف إلى context عند إقلاع السلة، لذا فإن قراءته في أعلى نصك البرمجي تعطي undefined. انتظر window.aftersell.cart.ready() أولًا.

if (window.aftersell.cart.context.customer_country === 'CA') {
  // Canada-only behavior, decided before the cart loads.
}

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

shadowRoot

تُعرض السلة داخل جذر ظلي (shadow root)، لذا فإن document.querySelector لا يستطيع رؤية أي شيء داخل الدُرج. للوصول إلى عنصر في السلة، استعلم عن الجذر الظلي:

const root = window.aftersell.cart.shadowRoot;
const button = root?.querySelector('.cart-external-checkout-button');

استهدف نفس فئات cart-external-* العامة التي تستخدمها CSS المخصصة. فهذه هي المقابض المدعومة. أما نظائرها cart-internal-* فهي أعمال السلة الداخلية، لذا استعلم عن الخارجية بدلًا منها.

لا تلجأ إلى الجذر الظلي إلا عندما لا تقوم أي كتلة أو إعداد أو خُطاف بالمهمة. فالخُطاف يصمد أمام إعادة تصميم السلة؛ أما استعلام DOM فصيانته مشكلة تقع على عاتق تعليماتك البرمجية.

الجذر الظلي لا يكون موجودًا إلا بعد إقلاع السلة، لذا اقرأه داخل ready() أو داخل معالج حدث بدلًا من أعلى نصك البرمجي.

تصحيح الأخطاء

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

ما الذي فشل	أين يظهر
نصك البرمجي ألقى خطأ في المستوى الأعلى	`console.error`، مع ذكر السطر وما الذي لم يعمل أبدًا
معالج حدث ألقى خطأ	`console.error`؛ المعالجات الأخرى تستمر في العمل
خُطاف ألقى خطأ	صامت. يذهب إلى قناة التصحيح أدناه
إجراء نُفّذ قبل تحميل السلة	`console.warn`؛ الاستدعاء لا يفعل شيئًا

عندما يُلقي نصك البرمجي خطأ

يتوقف النص البرمجي المخصص عند أول خطأ، لذا فإن كل configure و events.on و hooks.register* تحت ذلك السطر لا تعمل أبدًا. تقول السلة ذلك صراحةً:

[aftersell-cart] Initialization script error on line 12 — 4 more line(s) did not run;
any configure/events/hooks below are unregistered.

هذه هي الرسالة التي يجب البحث عنها عندما لا ينطلق أبدًا معالج أنت متأكد من تسجيله: على الأرجح لم يتم الوصول إليه أصلًا. رقم السطر هو العبارة في المستوى الأعلى حيث توقف التنفيذ، وليس الدالة الداخلية التي ألقت الخطأ، ويُحذف بدلًا من تخمينه إذا لم يكن تتبع المكدس في المتصفح قابلًا للاستخدام. كما تعمل نصوصك البرمجية تحت أسماء ملفاتها الخاصة، لذا تظهر باسم aftersell-cart-init.js و aftersell-cart-cart-update.js في DevTools. يمكنك فتحها من لوحة Sources وتعيين نقاط توقف مثل أي ملف آخر.

قناة التصحيح

تُبقى أعطال الخُطافات عمدًا بعيدة عن وحدة التحكم حتى لا يراها المتسوقون أبدًا. إنها تذهب إلى هنا بدلًا من ذلك:

// After reproducing the problem, inspect what was swallowed:
window.aftersellCartDebugEvents.filter((entry) => entry.level === 'ERROR');

// Or watch them live:
window.addEventListener('aftersell-cart-debug', (event) => console.log(event.detail));

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

التهيئة

كل خيار، مع مثال لكل منها.

الأحداث

كل حدث، ومتى ينطلق، وما الذي يجب تجنبه في المعالج.

الإجراءات

كل إجراء، مع مقتطف لكل منها.

الخُطافات

كل خُطاف، وكيف تتراكب التسجيلات.

كائن السلة

شكل السلة وأسطرها.

حالات الاستخدام

حلول كاملة وقابلة للتشغيل لأكثر الطلبات شيوعًا.

البدء

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

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

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

عربة التسوق

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

صفحة الشكر

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

Rokt Thanks

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

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

التكاملات

Aftersell MCP

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

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

نقطة الدخول العامة

التهيئة

الأحداث

الإجراءات

الخُطافات

أحداث أم إجراءات أم خُطافات؟

كيف ومتى يتم التحميل

استدعاءات الإعداد: آمنة فورًا

الإجراءات: انتظر ready()

ready()

context

shadowRoot

تصحيح الأخطاء

عندما يُلقي نصك البرمجي خطأ

قناة التصحيح

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

التهيئة

الأحداث

الإجراءات

الخُطافات

كائن السلة

حالات الاستخدام

​نقطة الدخول العامة

التهيئة

الأحداث

الإجراءات

الخُطافات

​أحداث أم إجراءات أم خُطافات؟

​كيف ومتى يتم التحميل

استدعاءات الإعداد: آمنة فورًا

الإجراءات: انتظر ready()

​ready()

​context

​shadowRoot

​تصحيح الأخطاء

​عندما يُلقي نصك البرمجي خطأ

​قناة التصحيح

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

التهيئة

الأحداث

الإجراءات

الخُطافات

كائن السلة

حالات الاستخدام

نقطة الدخول العامة

أحداث أم إجراءات أم خُطافات؟

كيف ومتى يتم التحميل

ready()

context

shadowRoot

تصحيح الأخطاء

عندما يُلقي نصك البرمجي خطأ

قناة التصحيح

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