Skip to main content

نظرة عامة

فيما يلي إجابات لبعض الأسئلة الأكثر شيوعًا حول استخدام واجهة Upcart API.

أين تُضاف نصوص Upcart API البرمجية؟

يمكنك إضافة النصوص البرمجية في إعدادات Custom HTML الخاصة بـ Upcart أو مباشرة في كود قالب Shopify. يعتمد الخيار الأفضل على احتياجات التخصيص لديك.

كيف أستخدم Custom HTML في Upcart؟

  1. انتقل إلى Upcart → Settings → Custom HTML
  2. استخدم نصوص API البرمجية لتعديل سلوك السلة، مثل توقيت الفتح أو عروض البيع الإضافي (upsell)
  3. عدّل عناصر خارج Upcart، مثل إخفاء أزرار صفحة المنتج

💡 مثال: إخفاء زر السلة الثابت عندما تكون السلة فارغة

ملاحظة قديمة: ما زالت دوال الاستدعاء window.upcartOnCartLoaded تعمل لكنها مهملة وتسجّل تحذيرات في وحدة التحكم. استخدم upcartSubscribeCartLoaded لجميع النصوص البرمجية الجديدة. لاحظ أن event.cart لا يحتوي على خاصية item_count — استخدم event.cart.items.reduce((total, item) => total + item.quantity, 0) لحساب إجمالي عدد العناصر.

هل يجب أن أكون مطوّرًا لاستخدام واجهة Upcart API؟

لا! واجهة Upcart API سهلة الاستخدام حتى بدون مهارات برمجية. كثير من الميزات مدمجة، وتتضمن وثائق التخصيص لدينا نصوصًا برمجية جاهزة يمكنك نسخها إلى إعدادات Custom HTML في Upcart — دون الحاجة إلى برمجة! إذا أردت كتابة نصوص برمجية مخصصة، فمعرفة أساسيات JavaScript تفيد. وإذا كنت جديدًا على JavaScript، فلا تقلق! يمكن أن تساعدك هذه الموارد المناسبة للمبتدئين — W3Schools و**MDN Web Docs** — على البدء.

هل يمكن لواجهة Upcart API التكامل مع تطبيقات خارجية أخرى؟

نعم! تعمل واجهة Upcart API مع تطبيقات الترجمة والتحليلات والبيع الإضافي (upsell) وغيرها. بعضها يتكامل تلقائيًا، بينما قد يحتاج بعضها الآخر إلى نص برمجي صغير. على سبيل المثال، إذا كنت تستخدم TripleWhale للتتبع، فستحتاج إلى إضافة النص البرمجي التالي لضمان تسجيله لنشاط السلة بشكل صحيح:
ملاحظة قديمة: ما زالت دوال الاستدعاء window.upcartOnAddToCart تعمل لكنها مهملة وتسجّل تحذيرات في وحدة التحكم. استخدم upcartSubscribeAddedToCart لجميع النصوص البرمجية الجديدة. لاحظ أن خصائص الحدث موجودة في event.item (مع variantId وquantityAdded)، ولا تُمرَّر كمعاملات منفصلة.
نظرًا لاختلاف كل تطبيق، استشر فريق دعم تطبيقك لمعرفة ما إذا كان يلزم كود إضافي. لا يقدم Upcart دعمًا للنصوص البرمجية الخاصة بالتطبيقات الخارجية، لكن مزوّد تطبيقك قد يملك دليل تكامل.

كيف أختبر ما إذا كانت تغييرات API تعمل؟

بعد إضافة نص برمجي إلى إعدادات Custom HTML في Upcart، اتبع هذه الخطوات للتأكد من عمله:
  1. حدّث متجرك وأضف عنصرًا إلى السلة.
  2. امسح ذاكرة التخزين المؤقت وحاول مرة أخرى لرؤية أحدث التغييرات.
  3. أضف رسالة اختبار: أدرج console.log("The script works!"); قبل </script> للتحقق من تشغيل نصك البرمجي.
  4. تحقق من وحدة تحكم المتصفح:
    • افتح Dev Tools (‏F12 أو Ctrl + Shift + J على Windows، وCmd + Option + J على Mac).
    • انتقل إلى علامة تبويب Console وابحث عن “The script works!”
    • إذا رأيت الرسالة، فنصك البرمجي يعمل! وإذا لم ترها، فقد لا يكون النص البرمجي يُنفَّذ بشكل صحيح.
  5. اختبر إجراءات مختلفة (مثل إزالة عنصر) للتأكد من السلوك المتوقع.
استكشف المشاكل بالتحقق من الأخطاء الإملائية أو أخطاء وحدة التحكم وتعديل الكود حسب الحاجة.

ماذا أفعل إذا لم يعمل نص API برمجي؟

إذا لم يعمل نص API البرمجي لديك، فجرّب خطوات استكشاف الأخطاء التالية:
  • تحقق من الأخطاء الإملائية – حتى الأخطاء الصغيرة قد تعطّل النص البرمجي. ابحث عن أحرف مفقودة أو صيغة غير صحيحة.
  • تحقق من موضع النص البرمجي – تأكد من أن النص البرمجي في القسم الصحيح ضمن Upcart → Settings → Custom HTML. لدى Upcart عشرة أقسام للنصوص البرمجية (تسع نقاط حقن HTML بالإضافة إلى قسم Scripts-before-load واحد) — راجع هذه الأقسام هنا.
  • تحقق من وحدة تحكم المتصفح – اتبع الخطوات أعلاه للبحث عن الأخطاء.
  • جرّب نصًا برمجيًا مختلفًا – جرّب نص Upcart API برمجيًا جاهزًا آخر لمعرفة ما إذا كانت المشكلة في الكود الخاص بك.
  • ما زلت عالقًا؟ – إذا كنت تعدّل قالب Shopify أو تدمج تطبيقات خارجية، فيمكن لخبير Shopify من دليل شركاء Shopify مساعدتك.
من المفترض أن تساعدك هذه الخطوات على تحديد معظم مشاكل النصوص البرمجية وحلها!

كيف أتراجع عن التغييرات إذا أضفت نصًا برمجيًا يعطّل شيئًا ما؟

إذا أضفت نصًا برمجيًا لا يعمل كما هو متوقع، فيمكنك إزالته أو تعطيله بسهولة:
  • انتقل إلى إعدادات Custom HTML في Upcart حيث أُضيف النص البرمجي.
  • أزل النص البرمجي أو عطّله مؤقتًا بإضافة // في بداية كل سطر (هذا يحوّله إلى تعليق ويمنع تشغيله).
  • احفظ التغييرات وحدّث متجرك للتحقق من حل المشكلة.
إذا استمرت المشكلة، فجرّب مسح ذاكرة التخزين المؤقت أو التراجع عن تغييرات القالب الأخيرة — فهذا غالبًا يحل التعارضات الخفية.
🚧 هل تبحث عن تخصيصات متقدمة؟ هل تحتاج إلى تخصيصات على مستوى المتجر أو تكاملات مع تطبيقات خارجية؟ قد تحتاج إلى مطوّر لإضافة واجهة Upcart API إلى قالب Shopify الخاص بك. فكّر في توظيف خبير Shopify عبر دليل شركاء Shopify وشارك معه وثائق API الخاصة بنا للمساعدة