نظرة عامة
POST إلى /api/public/strategy/evaluate، واعرض الاستجابة.
تغطي هذه الصفحة نمطي تنفيذ:
- سياق صفحة المنتج (PDP) - أضف قسمًا إلى صفحات المنتجات يستدعي واجهة برمجة التطبيقات مع المنتج المعروض حاليًا ويعرض عرضًا دوّارًا للتوصيات المُعادة.
- سياق السلة - اعرض كتلة بيع إضافي داخل سلة مخصصة تستدعي واجهة برمجة التطبيقات مع جميع بنود السلة الحالية وتعرض المنتجات المُعادة.
ما ستحتاج إليه
- مفتاح Strategy API الخاص بك. في Aftersell، انتقل إلى Settings → Product Strategy، وفي بطاقة Security Token، انسخ الرمز الخاص بك (هذا هو مفتاح Strategy API).
- معرّف الاستراتيجية. افتح الاستراتيجية التي تريد تشغيلها في محرر الاستراتيجيات في Aftersell وانسخ معرّفها.
- الوصول إلى كود القالب. ستضيف قسم Liquid (لصفحة المنتج) أو كتلة (للسلة المخصصة) إلى قالب Shopify الخاص بك - Online Store → Themes → … → Edit code.
سياق صفحة المنتج: مقتطف القسم
التثبيت
- في لوحة تحكم Shopify، انتقل إلى Online Store → Themes، وانقر على … في قالبك، واختر Edit code.
- ضمن مجلد Sections، أنشئ ملفًا جديدًا باسم
aftersell-upsell-carousel.liquid. - الصق المقتطف أدناه في الملف الجديد واستبدل
YOUR_STRATEGY_API_KEYبمفتاح API من Aftersell. - احفظ.
- افتح قالب المنتج الخاص بك (عادةً
templates/product.jsonأوsections/main-product.liquid) وأضف قسم Aftersell Carousel حيث تريد أن يظهر العرض الدوّار. من محرر القالب، يمكنك أيضًا سحبه إلى صفحة المنتج مباشرة. - في إعدادات القسم، الصق معرّف الاستراتيجية (Strategy ID) الخاص بك.
ما يرسله القسم
- products - مصفوفة من عنصر واحد تحتوي على المنتج المعروض حاليًا (productId وvariantId وquantity وprice وhandle وtitle وvendor وproductType وtags وcollections وsellingPlan).
- cart - الإجمالي الفرعي وعدد العناصر وعدد البنود لسلة المتسوق الحالية (تُحذف إذا كانت السلة فارغة).
- cartToken - لتتمكن واجهة برمجة التطبيقات من ربط هذا التقييم بالجلسة نفسها.
- customer - الوسوم والبلد والمقاطعة واللغة المحلية وعدد الطلبات وإجمالي الإنفاق وعلامة قبول التسويق، ولكن فقط إذا كان المتسوق مسجّل الدخول.
- session - رمز العملة من
shop.currency.
session قبل الاستدعاء عبر fetch.
المقتطف

التخصيص
{% schema %} لكشف المزيد من الخيارات لمحرر القالب.
أنماط CSS محصورة ضمن أسماء فئات .aftersell-* وتتضمن عرضًا دوّارًا مدعومًا بـ Splide بأربعة عناصر ينخفض إلى عنصرين عند 768 بكسل وإلى عنصر واحد عند 480 بكسل. عدّلها بحرية لتناسب قالبك - لا شيء منها مطلوب لعمل استدعاء واجهة برمجة التطبيقات.
سياق السلة: كتلة بيع إضافي في سلة مخصصة
cart.liquid. شكل استدعاء واجهة برمجة التطبيقات ومعالجة الاستجابة مطابقان لمثال صفحة المنتج - يختلف فقط مصفوفة products.
يبدو الهيكل كما يلي:
fetch إلى /api/public/strategy/evaluate لم يتغيرا عن نمط صفحة المنتج أعلاه - فقط مصفوفة products تتبدل من [productContext] إلى المصفوفة المشتقة من السلة.
ماذا يحدث عندما تُعيد الاستراتيجية نتيجة
evaluationId هو معرّف فريد لهذا التقييم. إذا التقطته وأرفقته بالمنتجات التي تعرضها، يمكنك إسناد الطلب الناتج إلى التوصية الدقيقة التي أنتجته - راجع الإسناد أدناه.
طريقة عرض مصفوفة products متروكة بالكامل لكود قالبك. يعرضها مقتطف صفحة المنتج أعلاه كعرض دوّار من البطاقات مع منتقيات المتغيرات وأزرار الإضافة إلى السلة؛ وقد تعرضها كتلة سلة مخصصة كقائمة عمودية داخل الدرج.
للاطلاع على مخطط الطلب والاستجابة الكامل، راجع مرجع Evaluate Strategy API.
عندما لا يُعاد أي منتج
products: [])، فإن طريقة التعامل مع ذلك متروكة لكودك. يخفي مقتطف صفحة المنتج أعلاه العرض الدوّار بالكامل. وقد تعود كتلة السلة المخصصة إلى قائمة البيع الإضافي الافتراضية للسلة، أو ببساطة لا تعرض شيئًا.
لتجنب استجابة فارغة، قم بإعداد Catch all في الاستراتيجية بحيث يكون هناك دائمًا منتج احتياطي يُعاد. راجع صفحة بناء الاستراتيجيات لمعرفة كيفية إعداد Catch all.
نصائح للتكاملات المخصصة
- ابنِ السياق في Liquid. يعمل Liquid وقت العرض ولديه وصول إلى كامل مخطط كائنات Shopify - المنتج والسلة والعميل والمتجر والطلب. استخدمه لتعبئة الحمولة على جانب الخادم بدلاً من اللجوء إلى استدعاءات على جانب العميل.
- أبقِ مفتاح API خارج المستودعات العامة. سينتهي به المطاف في كود قالبك، الذي يُرسل إلى المتصفح - لا بأس بذلك. لكن لا تلصق القالب نفسه في مستودع عام ولا تشارك الحزمة خارجيًا.
- استخدم Catch all. تبدو تجارب واجهة المتجر معطوبة عندما تختفي خانة ما. Catch all يحتوي على مجموعة صغيرة من الخيارات الافتراضية الآمنة يُبقي واجهة المستخدم متسقة.
- خزّن مؤقتًا حيث يكون ذلك منطقيًا. تقوم Strategies API بتخزين مؤقت خفيف على جانب الخادم (
meta.servedFromCache)، ولكن لصفحات المنتجات ذات الزيارات المرتفعة قد ترغب أيضًا في تقليل تكرار الاستدعاءات أو حفظ نتائجها على جانب العميل (على سبيل المثال، لا تعِد الاستدعاء عند عرض المنتج نفسه مرتين في جلسة واحدة).
الإسناد
/cart/add.js خصائص بند (line item properties) بعنصر السلة:
الإسناد إلى التقييم
evaluationId من الاستجابة وأرفقه بالبند تحت الخاصية __as_offer_id. يقرأ AfterSell هذا المفتاح، لذا تُسند الطلبات الموسومة به إلى التقييم المحدد في التقارير.
في معالج evaluate()، احتفظ بالمعرّف من الاستجابة:
__as_offer_id - فهو المفتاح الذي يبحث عنه AfterSell، وبادئة الشرطة السفلية تبقيه مخفيًا عن المتسوقين. إذا كان evaluationId غائبًا (على سبيل المثال، لم تُعَد أي منتجات)، فتخطَّ الخاصية بدلاً من إرسال قيمة فارغة.