Skip to main content

نظرة عامة

عندما لا تناسبك الأسطح الأصلية لـ Aftersell (ما بعد الشراء، صفحة الدفع، Upcart) ولا تكامل جاهز، يمكنك استدعاء Strategies API بنفسك من قالب Shopify الخاص بك وعرض المنتجات المُعادة بالطريقة التي تريدها. النمط هو نفسه في كل الحالات: ابنِ حمولة سياق من Liquid (بحيث تُملأ خصائص Shopify مثل المنتج الحالي ومحتويات السلة وحقول العميل وقت العرض)، ثم أرسل POST إلى /api/public/strategy/evaluate، واعرض الاستجابة. تغطي هذه الصفحة نمطي تنفيذ:
  • سياق صفحة المنتج (PDP) - أضف قسمًا إلى صفحات المنتجات يستدعي واجهة برمجة التطبيقات مع المنتج المعروض حاليًا ويعرض عرضًا دوّارًا للتوصيات المُعادة.
  • سياق السلة - اعرض كتلة بيع إضافي داخل سلة مخصصة تستدعي واجهة برمجة التطبيقات مع جميع بنود السلة الحالية وتعرض المنتجات المُعادة.
الاختلاف بين الاثنين هو شكل سياق المنتج: منتج واحد في صفحة المنتج، ومصفوفة بجميع البنود في السلة.

ما ستحتاج إليه

  1. مفتاح Strategy API الخاص بك. في Aftersell، انتقل إلى Settings → Product Strategy، وفي بطاقة Security Token، انسخ الرمز الخاص بك (هذا هو مفتاح Strategy API).
  2. معرّف الاستراتيجية. افتح الاستراتيجية التي تريد تشغيلها في محرر الاستراتيجيات في Aftersell وانسخ معرّفها.
  3. الوصول إلى كود القالب. ستضيف قسم Liquid (لصفحة المنتج) أو كتلة (للسلة المخصصة) إلى قالب Shopify الخاص بك - Online Store → Themes → … → Edit code.
يوجد مفتاح Strategy API الخاص بك في كود القالب على جانب العميل، مما يجعله مرئيًا لأي شخص يعرض مصدر الصفحة. تعامل معه كبيانات اعتماد عامة لواجهة المتجر، وقم بتدويره من Settings → Product Strategy في Aftersell إذا تم كشفه بأي طريقة لم تكن مقصودة.

سياق صفحة المنتج: مقتطف القسم

يضيف هذا النمط قسم Shopify إلى صفحة منتجك. عند عرض الصفحة، يضمّن Liquid خصائص المنتج الحالي والسلة والعميل في الحمولة، ثم يرسل JavaScript الطلب إلى Strategies API ويعرض المنتجات المُعادة في عرض Splide دوّار.

التثبيت

  1. في لوحة تحكم Shopify، انتقل إلى Online Store → Themes، وانقر على في قالبك، واختر Edit code.
  2. ضمن مجلد Sections، أنشئ ملفًا جديدًا باسم aftersell-upsell-carousel.liquid.
  3. الصق المقتطف أدناه في الملف الجديد واستبدل YOUR_STRATEGY_API_KEY بمفتاح API من Aftersell.
  4. احفظ.
  5. افتح قالب المنتج الخاص بك (عادةً templates/product.json أو sections/main-product.liquid) وأضف قسم Aftersell Carousel حيث تريد أن يظهر العرض الدوّار. من محرر القالب، يمكنك أيضًا سحبه إلى صفحة المنتج مباشرة.
  6. في إعدادات القسم، الصق معرّف الاستراتيجية (Strategy ID) الخاص بك.

ما يرسله القسم

لكل مشاهدة لصفحة المنتج، تتضمن الحمولة:
  • products - مصفوفة من عنصر واحد تحتوي على المنتج المعروض حاليًا (productId وvariantId وquantity وprice وhandle وtitle وvendor وproductType وtags وcollections وsellingPlan).
  • cart - الإجمالي الفرعي وعدد العناصر وعدد البنود لسلة المتسوق الحالية (تُحذف إذا كانت السلة فارغة).
  • cartToken - لتتمكن واجهة برمجة التطبيقات من ربط هذا التقييم بالجلسة نفسها.
  • customer - الوسوم والبلد والمقاطعة واللغة المحلية وعدد الطلبات وإجمالي الإنفاق وعلامة قبول التسويق، ولكن فقط إذا كان المتسوق مسجّل الدخول.
  • session - رمز العملة من shop.currency.
لا يرسل القسم معلمات UTM بشكل افتراضي. إذا كنت تريد استهدافًا معتمدًا على UTM في صفحة المنتج، التقطها على جانب العميل وأضفها إلى كائن session قبل الاستدعاء عبر fetch.

المقتطف

عرض دوّار للمنتجات مدعوم باستراتيجية معروض في صفحة منتج على Shopify

التخصيص

يكشف مخطط القسم عن أربعة إعدادات قابلة للتعديل من قبل التاجر: Strategy ID وHeading وCTA Button Label وMax Products to Show. أضف إعدادات أو أزلها في كتلة {% schema %} لكشف المزيد من الخيارات لمحرر القالب. أنماط CSS محصورة ضمن أسماء فئات .aftersell-* وتتضمن عرضًا دوّارًا مدعومًا بـ Splide بأربعة عناصر ينخفض إلى عنصرين عند 768 بكسل وإلى عنصر واحد عند 480 بكسل. عدّلها بحرية لتناسب قالبك - لا شيء منها مطلوب لعمل استدعاء واجهة برمجة التطبيقات.

سياق السلة: كتلة بيع إضافي في سلة مخصصة

هذا النمط مطابق هيكليًا لنمط صفحة المنتج، مع اختلاف رئيسي واحد: مصفوفة سياق المنتج تُبنى من بنود السلة بدلاً من المنتج المعروض حاليًا. تستقبل الاستراتيجية بعد ذلك كل عنصر أضافه المتسوق وتُعيد التوصيات بناءً على السلة ككل. يوجد التنفيذ حيثما يوجد كود سلتك المخصصة - قسم Liquid يعرض درج السلة (cart drawer)، أو كتلة مخصصة في واجهة متجر headless، أو قالب مثل cart.liquid. شكل استدعاء واجهة برمجة التطبيقات ومعالجة الاستجابة مطابقان لمثال صفحة المنتج - يختلف فقط مصفوفة products. يبدو الهيكل كما يلي:
بقية الحمولة (cart وcustomer وsession وcartToken) واستدعاء 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) بعنصر السلة:
تنتقل هذه الخصائص مع البند طوال الطريق إلى طلب Shopify، حيث تظهر في سجل البند. يمكنك استخدامها لاحقًا لإسناد الإيرادات أو تصفية الطلبات أو تغذية أدوات التحليلات التي تقرأ خصائص البنود. المفاتيح والقيم اصطلاحات وليست متطلبات - يعمل استدعاء واجهة برمجة التطبيقات بالطريقة نفسها بغض النظر عما تضعه هنا. غيّرها لتناسب نموذج الإسناد الخاص بك. على سبيل المثال:
مفاتيح الخصائص التي تبدأ بشرطة سفلية (_) تُخفى من واجهة السلة وصفحة الدفع لكنها تظل مرفقة بالطلب. استخدم بادئة الشرطة السفلية لبيانات الإسناد الوصفية التي لا تريد أن يراها المتسوقون.
طبّق النمط نفسه في تنفيذ سياق السلة - أي استدعاء إضافة إلى السلة تجريه من كتلة بيع إضافي مخصصة يمكن أن يحمل أي خصائص تحتاجها.

الإسناد إلى التقييم

لربط طلب بـ التقييم الدقيق الذي أوصى بالمنتج - بدلاً من مجرد “جاء من استراتيجية” - التقط evaluationId من الاستجابة وأرفقه بالبند تحت الخاصية __as_offer_id. يقرأ AfterSell هذا المفتاح، لذا تُسند الطلبات الموسومة به إلى التقييم المحدد في التقارير. في معالج evaluate()، احتفظ بالمعرّف من الاستجابة:
ثم ضمّنه في خصائص الإضافة إلى السلة:
حافظ على الشرطة السفلية المزدوجة في __as_offer_id - فهو المفتاح الذي يبحث عنه AfterSell، وبادئة الشرطة السفلية تبقيه مخفيًا عن المتسوقين. إذا كان evaluationId غائبًا (على سبيل المثال، لم تُعَد أي منتجات)، فتخطَّ الخاصية بدلاً من إرسال قيمة فارغة.