تكامل PrestaShop (وصول مبكر)

وصول مبكر

تكامل PrestaShop في مرحلة الوصول المبكر. لم يتم التحقق منه بعد على متجر حي في بيئة الإنتاج. مزامنة البيانات وتتبع واجهة المتجر ورسائل In-App وإشعارات الويب ورموز القسائم ونماذج الموقع جاهزة؛ أما الإدراج في سوق Addons فسيأتي لاحقًا - راجعوا غير متاح بعد.

اربطوا متجر PrestaShop 8 أو 9 باستخدام وحدة Joryio. تتم مزامنة العملاء والطلبات والمبالغ المستردة والمنتجات والسلات مع Joryio، وتحصل السلات المتروكة على رابط استعادة، وتتبع موافقة النشرة البريدية ما في المتجر، وتُتتبَّع زيارات المتسوقين وتُنسب إلى حملاتكم، وتصل رسائل In-App وإشعارات الويب إلى واجهة متجركم، وتنشئ برامج القسائم رموزًا شخصية في المتجر.

ما الذي تتم مزامنته

البيانات	التفاصيل
العملاء	العملاء المسجلون، وعمليات الشراء كضيف حسب البريد الإلكتروني. لا يُحفظ الضيف أبدًا كرقم عميل PrestaShop على جهة اتصال.
الطلبات	الحالة والمبالغ والمنتجات والعناوين وكل رمز قسيمة مع الخصم الذي منحه وإسناد الحملة والعملة. الطلبات في حالة الإلغاء أو خطأ الدفع ترسل حدث Order Cancelled واحدًا؛ وكل إشعار دائن (credit slip) يرسل حدث Order Refunded واحدًا بمبلغه.
المنتجات	الاسم والوصف والسعر (شاملًا الضريبة، مع سعر التخفيض) والعلامة التجارية وGTIN والفئات والصور والخصائص والتركيبات والمخزون. تغذّي تغييرات المخزون والسعر محفزات الكتالوج.
السلات	السلات أثناء تسوق العملاء، والسلات المتروكة مع رابط استعادة موقّع.
موافقة النشرة البريدية	اشتراك العميل في النشرة البريدية. راجعوا الموافقة التسويقية.
أحداث واجهة المتجر	مشاهدات الصفحات والمنتجات والفئات والبحث والسلة، والإضافة إلى السلة والإزالة منها، وبدء إتمام الشراء، والبريد الإلكتروني الذي يكتبه المتسوق. راجعوا تتبع واجهة المتجر.
نماذج الموقع	نموذج الاتصال ونماذج الوحدات الأخرى، مع ربط الحقول في صفحة الوحدة (الوحدة 1.2.0). راجعوا نماذج الموقع.

عند الربط يستورد Joryio العملاء والمنتجات والطلبات الحالية (آخر 90 يومًا افتراضيًا) عبر Webservice الخاص بـ PrestaShop. بعد ذلك ترسل الوحدة التغييرات فور حدوثها.

غير متاح بعد

سيأتي إدراج الوحدة في سوق PrestaShop Addons في إصدار لاحق. حتى ذلك الحين، ثبّتوا الوحدة من ملف zip الموجود في Joryio.

المتطلبات

• PrestaShop 8.0 أو أحدث، أو 9.x (الإصدار PrestaShop 1.7 غير مدعوم)
• إصدار PHP الذي يتطلبه إصدار PrestaShop لديكم (PrestaShop 8: من PHP 7.2.5 إلى 8.1؛ PrestaShop 9: PHP 8.1 أو أحدث)
• إمكانية الوصول إلى المتجر من الإنترنت عبر https على عنوان عام، وهو عنوانه النهائي (بدون إعادة توجيه). يتصل Joryio دائمًا عبر https:// ويرفض العناوين الخاصة أو الداخلية وإعادات التوجيه
• اتصال HTTPS صادر من خادمكم إلى Joryio
• يُنصح بمهمة cron على الخادم - راجعوا Cron

الإعداد

الخطوة 1: احصلوا على عنوان الخادم ومفتاح API

1. في Joryio، انتقلوا إلى Integrations → PrestaShop
2. انسخوا عنوان الخادم
3. انقروا إنشاء مفتاح API وانسخوا المفتاح (يبدأ بـ jry_ps_)

الخطوة 2: ثبّتوا الوحدة

1. نزّلوا الوحدة باستخدام تنزيل الوحدة في صفحة PrestaShop في Joryio (joryio-prestashop.zip)
2. في لوحة إدارة PrestaShop، انتقلوا إلى Modules → Module Manager → Upload a module وارفعوا ملف zip هناك

الخطوة 3: الربط

1. افتحوا الوحدة (Configure)
2. الصقوا عنوان الخادم ومفتاح API
3. انقروا Connect

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

تنشئ الوحدة مفتاح Webservice جديدًا عند كل Connect. لا يستطيع المفتاح إلا قراءة (GET) البيانات التي يزامنها Joryio - ولا يقرأ إعدادات المتجر أبدًا - ويستطيع، ابتداءً من الوحدة 1.1.0، إنشاء قواعد السلة (cart rules) وتعديلها وحذفها، وهي الطريقة التي ينشئ بها Joryio رموز برامج القسائم الخاصة بكم. لا يمكن كتابة أي شيء آخر به. إذا رفض Joryio الاتصال، تحذف الوحدة المفتاح مجددًا، وإذا كانت الوحدة هي التي شغّلت Webservice فإنها توقفه مرة أخرى.

تعدد المتاجر

مع Multistore، يتصل كل متجر بمفرده. افتحوا الوحدة مع اختيار ذلك المتجر في سياق المتجر، واستخدموا مفتاح API لمساحة عمل Joryio التي ينتمي إليها المتجر. لا يمكن ربط المتجر إلا بمساحة عمل واحدة: ربطه بمساحة ثانية يعرض "This store is already connected to another Joryio workspace." افصلوه هناك أولًا.

كذلك تضم مساحة العمل متجرًا واحدًا: يُرفض ربط متجر ثانٍ بمفتاح مساحة العمل نفسها ("This Joryio workspace is already connected to another PrestaShop shop..."). خصصوا لكل متجر مساحة عمل خاصة به واستخدموا مفتاح تلك المساحة.

Cron

تحتفظ الوحدة بالأحداث في قائمة انتظار في قاعدة بيانات المتجر وترسلها في الخلفية. تعرض صفحة الوحدة عنوان cron مع رمز سري. أضيفوه إلى crontab على الخادم ليعمل كل دقيقة، مثلًا:

* * * * * curl -fsS "<cron URL from the module page>" > /dev/null

بدون مهمة cron ترسل الوحدة أيضًا أثناء حركة المتجر العادية، فتستمر الأحداث في الوصول - لكنها قد تتأخر في متجر هادئ.

التسليم وإعادة المحاولة

لا يضيع الحدث عندما يتعذر الوصول إلى Joryio لبعض الوقت:

• Joryio غير متاح أو مشغول - تتوقف قائمة الانتظار وتعيد المحاولة بعد فترات متزايدة (دقيقة واحدة، تتضاعف حتى مرة كل ساعة) لمدة تصل إلى 7 أيام، مع الحفاظ على ترتيب الأحداث لكل طلب وسلة وعميل.
• الحدث الذي يرفضه Joryio (مثل البيانات غير الصالحة) يُستبعد فورًا، حتى لا يؤخر الأحداث الأخرى.
• Joryio يرفض مفتاح API - يتوقف التسليم وتعرض صفحة الوحدة تنبيهًا. تُحفظ الأحداث: الصقوا المفتاح الحالي وانقروا Connect.
• تُحفظ الأحداث التي تعذر تسليمها لمدة 30 يومًا. تعرض صفحة الوحدة عدد الأحداث المنتظرة وغير المسلّمة مع آخر خطأ، ويعيد Retry now إرسالها.

المطابقة المجدولة

قد تضيع التحديثات المباشرة (الوحدة) - مثلًا عندما يكون المتجر غير متاح، أو عندما يفشل التسليم مرات كثيرة. كل 6 ساعات يفحص Joryio المتجر بحثًا عمّا تغيّر منذ الفحص السابق، ويضيف ما فاتته التحديثات المباشرة: الطلبات، وإشعارات الدائن (الاستردادات)، وتغييرات حالة الطلبات، والعملاء، والمنتجات، وسلال التسوق خلال آخر 24 ساعة.

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

• الطلب المفقود الذي تم خلال آخر 24 ساعة يُسجَّل كما لو وصل مباشرة، فتبدأ مسارات ما بعد الشراء كالمعتاد. أما الطلب المفقود الأقدم، والاسترداد أو الإلغاء لطلب كان Joryio يعرفه، فيُسجَّلان دون بدء مسارات؛ ويُسجَّل كل من Order Refunded وOrder Cancelled مرة واحدة فقط.
• يُفحص كل متجر في وقته الخاص، فلا تُقرأ المتاجر كلها دفعة واحدة، ويقرأ الفحص الواحد عددًا محدودًا من التغييرات؛ والمتجر الذي لديه تغييرات أكثر يُستكمل خلال نصف ساعة.
• تُتخطى المتاجر غير المتصلة أو التي بها خطأ أو التي ما زالت قيد المزامنة حتى تتصل من جديد.

تظهر النتيجة في الإعدادات → التكاملات → PrestaShop: آخر مطابقة: 22/10/2026 12:00 - العناصر التي تمت إضافتها: 3. إذا استمرت الفحوص في العثور على تغييرات لم تصل مباشرة، يُطلق Joryio تنبيه Live updates from PrestaShop may be failing (الجرس، والسجلات والمراقبة، وبريد إلى مسؤولي مساحة العمل). تُضاف البيانات المفقودة في جميع الأحوال، لكن تحقق من اتصال المتجر: المسارات التي تتفاعل مع هذه التغييرات تبدأ متأخرة.

تعرض الصفحة نفسها آخر حدث مستلم - متى وصل آخر تحديث مباشر من المتجر إلى Joryio (بتأخير دقيقة واحدة على الأكثر) - وآخر مزامنة، وهي الأحدث بين آخر مزامنة كاملة وآخر مطابقة. في المتجر الذي يرسل تحديثات مباشرة يتقدم آخر حدث مستلم حتى عندما لا تعمل أي مزامنة.

المبالغ المستردة والإلغاءات

كل إشعار دائن على طلب يصبح حدث Order Refunded واحدًا بمبلغه. والطلب الذي ينتقل إلى حالة إلغاء (أو خطأ دفع) يصبح حدث Order Cancelled واحدًا. يقرأ Joryio عند الربط الحالات التي تعني "ملغى" و"مسترد" في متجركم، لذا تُحتسب الحالات التي تمت إعادة تسميتها أيضًا. راجعوا أحداث الاسترداد والإلغاء.

الموافقة التسويقية

يُطبَّق اشتراك العميل في النشرة البريدية في PrestaShop على اشتراك البريد الإلكتروني لجهة الاتصال:

في PrestaShop	في Joryio
مشترك (مربع النشرة عند التسجيل أو في الحساب، أو كتلة النشرة البريدية، أو لوحة الإدارة)	مشترك في البريد الإلكتروني، بالتاريخ الذي سجّله PrestaShop.
ألغى الاشتراك بعد أن كان مشتركًا	إلغاء الاشتراك في البريد الإلكتروني - ما لم يسجّل Joryio تغييرًا لاحقًا لجهة الاتصال.

الإثبات المسجَّل (الوحدة 1.2.17): مربع النشرة في طلب أو في نموذج التسجيل يسجّل أيضًا عنوان IP للمتسوق والصفحة (صفحة الدفع أو صفحة التسجيل) في سجل الموافقة - في الطلب، العنوان الذي سجّله PrestaShop لزيارة المتسوق. يظهر عنوان IP فقط لأعضاء الفريق المسموح لهم برؤية البيانات الشخصية، ويُضمَّن عندما يطلب الشخص بياناته، ويُحذف عند محو بياناته.

يشترك الاستيراد الأولي العملاء الذين يعرضهم PrestaShop كمشتركين؛ ولا يلغي اشتراك أي أحد، لأن "غير مشترك" قد تعني أيضًا "لم يشترك قط". مربع عروض الشركاء (optin) ليس موافقة تسويقية في Joryio ويتم تجاهله.

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

متى تُحتسب علامة الموافقة

مربع "Sign up for our newsletter" الخاص بـ PrestaShop نفسه جزء من خطوة المعلومات الشخصية في صفحة الدفع. يحفظه PrestaShop على العميل عندما يتجاوز المتسوق تلك الخطوة، لذلك ترسله الوحدة إلى Joryio في تلك اللحظة - قبل تنفيذ الطلب. لا يوجد خيار "فقط عند تنفيذ الطلب"، ولا يُرسل شيء عند تحميل الصفحة. المربع ونصه من PrestaShop نفسه؛ ولا تحدده الوحدة مسبقًا أبدًا.

الوحدة 1.2.8 أو أحدث - القاعدة نفسها المطبقة مع Record consent immediately في Magento وWooCommerce:

المتسوق	ما يفعله التحديد قبل الطلب
مشترٍ معروف (لدى Joryio طلب من جهة الاتصال) أو شخص مشترك بالفعل في البريد الإلكتروني أو SMS	يُحتسب فورًا: مشترك.
ضيف جديد (وأيضًا متسوق ينشئ حسابًا في خطوة الدفع)	يبقى معلّقًا: يُسجَّل التحديد (الوقت والمتجر وعملية الدفع وعنوان IP للمتسوق)، لكن جهة الاتصال لا تُشترك ولا تتلقى أي تسويق - ويُتخطى تذكير السلة المتروكة بسبب بانتظار التأكيد. طلبه الخاص مع تحديد المربع يُشركه، وكذلك النقر على بريد التأكيد إذا فعّلتموه.
شخص ألغى اشتراكه ولم يطلب بعد	يبقى غير مشترك. ثم يتبع طلبه قواعد إعادة الاشتراك من المتجر.

• يحمل الطلب حالة المربع كما كانت عند تنفيذ الطلب. محدد: يُشترك المشتري مرة واحدة. غير محدد: لا يتغير شيء - الطلب غير المحدد لا يُشرك أبدًا ولا يلغي الاشتراك أبدًا، ويبقى التحديد المعلّق معلّقًا. عند تفعيل الإعداد الاختياري المربع غير المحدد يلغي الاشتراك، يسجّل المربع غير المحدد في طلب مقدَّم إلغاء اشتراك بدلاً من ذلك.
• إذا عاد المتسوق إلى خطوة المعلومات الشخصية وألغى تحديد المربع، يُسحب تحديد عملية الدفع تلك - هو وحده: يبقى أي اشتراك أعطاه في أي مكان آخر.
• يتبع نموذج التسجيل وصفحة الحساب وكتلة النشرة البريدية لعميل مسجّل الدخول والاستيراد الأولي القاعدة نفسها: لا يتحقق PrestaShop من عنوان البريد الإلكتروني هناك أيضًا، لذلك يُحتسب الاشتراك في النشرة فورًا فقط لمشترٍ معروف أو لشخص مشترك بالفعل. ويبقى أي شخص آخر معلّقًا حتى ينقر على بريد التأكيد (فعّلوا إرسال رابط تأكيد بالبريد الإلكتروني إلى الضيوف الجدد). وحده الاشتراك عبر كتلة النشرة البريدية الذي أُكّد ببريد التحقق الخاص بـ PrestaShop نفسه يُحتسب فورًا. أما إلغاء الاشتراك فيُطبَّق دائمًا فورًا. لاحتسابهم فورًا بدلًا من ذلك، راجع موافقات المتسوقين الجدد. يُسجَّل تحديد التسجيل المعلّق بالسبب registration_tick_pending_confirmation.

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

ضمانتان في التكاملات ← PrestaShop ← الإعدادات (للمسؤولين فقط؛ يُسجَّل كل تغيير في سجل التدقيق):

• إرسال رابط تأكيد بالبريد الإلكتروني إلى الضيوف الجدد - متوقف افتراضيًا، لأن العنوان كُتب عند الدفع ولم يتحقق منه أحد بعد. عند تفعيله يتلقى الضيف الجديد المعلّق رسالة واحدة؛ ورابطها يُشركه (المصدر double_opt_in). يستخدم قالب تأكيد الاشتراك المزدوج إذا اخترتم واحدًا.
• تحديدات الموافقة لكل متسوق في الساعة - الافتراضي 3، تُحتسب لكل عنوان IP ولكل عملية دفع ولكل عنوان بريد إلكتروني. يتم تجاهل العلامات التي تتجاوز الحد؛ ويظل الطلب يسجل الاختيار. للوحدة الحد نفسه (Opt-in ticks per shopper per hour في إعدادات الوحدة، الافتراضي 3) ولا ترسل مثل هذا التحديد إطلاقًا.

تحتسب الوحدة عنوان IP للاتصال نفسه. إذا كان متجركم خلف وكيل (proxy) أو CDN يحدد عنوان الزائر (X-Forwarded-For)، ففعّلوا Behind a trusted proxy في إعدادات الوحدة؛ وإلا فاتركوه متوقفًا، لأن الزائر يستطيع تعيين هذا الترويسة بنفسه.

مع الوحدة 1.2.7 أو أقدم، يبقى تحديد الضيف الجديد معلّقًا أيضًا، لكن طلبه لا يستطيع إشراكه (لا ترسل هذه الإصدارات المربع مع الطلب) - وحده بريد التأكيد يستطيع. حدّثوا الوحدة إلى 1.2.8.

معروضة في Joryio

لا يوجد في PrestaShop إعداد "متى يُحتسب التحديد"، وتقول ذلك بطاقة Store checkout opt-in (set in your store) في التكاملات → PrestaShop → الإعدادات، للقراءة فقط: خانة النشرة البريدية خاصة بـ PrestaShop نفسه (وحدة Newsletter subscription، ps_emailsubscription، ضمن Modules → Module Manager) وتُرسل قبل الطلب، لذا تنطبق عليها وسائل الحماية في الصفحة نفسها. لا يغيّر Joryio أي شيء في PrestaShop.

موافقات المتسوقين الجدد

يحدد الإعداد موافقات المتسوقين الجدد (الذين لم يشتروا بعد) في التكاملات → PrestaShop → الإعدادات (للمسؤولين فقط؛ ويُسجَّل كل تغيير في سجل التدقيق) ما تفعله موافقة من شخص لم يشترِ بعد:

الخيار	ما يحدث
الانتظار حتى يطلبوا أو يؤكدوا عبر البريد الإلكتروني (افتراضي، موصى به)	تبقى موافقة المتسوق الجديد معلّقة حتى طلبه هو مع تحديد المربع أو نقره على رسالة التأكيد (إذا فعّلت إرسال رابط تأكيد بالبريد الإلكتروني إلى الضيوف الجدد).
الاحتساب فورًا (أقل صرامة - يمكن لأي زائر إدخال أي بريد إلكتروني)	تُحتسب فورًا. يمكن لأي زائر كتابة أي عنوان بريد إلكتروني، لذا يمكن لشخص ما أن يشترك باسم شخص آخر؛ ويمكن لهذا الأخير إلغاء الاشتراك بنقرة واحدة. هكذا كان Joryio يحتسبها قبل الوحدة 1.2.8.

يغطي كل موافقة تصل من دون طلب: مربع النشرة البريدية عند الدفع ونموذج التسجيل وصفحة الحساب وكتلة النشرة البريدية لعميل مسجّل الدخول والاستيراد الأولي. وفي الحالتين:

• يُحتسب المشتري المعروف أو المشترك بالفعل فورًا، وكذلك الاشتراك في كتلة النشرة البريدية الذي أُكّد برسالة التحقق من PrestaShop؛
• التحديد الذي يأتي مع طلب المتسوق نفسه يُحتسب دائمًا؛
• يُطبَّق إلغاء الاشتراك فورًا دائمًا؛
• يبقى حد تحديدات الموافقة لكل متسوق في الساعة ساريًا.

المربع غير المحدد يلغي الاشتراك (اختياري)

للمتاجر ذات سياسة الموافقة الصارمة، تتضمن الوحدة 1.2.15 أو أحدث إعداداً اختيارياً في إعدادات الموافقة في الوحدة: An unticked opt-in box at checkout or registration unsubscribes the person. وهو معطّل افتراضياً.

الإعداد	ما يفعله المربع غير المحدد
معطّل (افتراضي)	لا شيء. المربع غير المحدد لا يغيّر حالة أي شخص أبداً.
مفعّل	المربع الذي عُرض وأُرسل دون تحديد - مع طلب تم تقديمه، أو في نموذج التسجيل - يسجّل إلغاء اشتراك لقناة ذلك المربع (Email أو SMS). للعملاء المسجّلين الدخول فقط، الذين تحقق منهم المتجر.
مفعّل، مع Also for guest checkouts	الأمر نفسه أيضاً عند الدفع كضيف وعند تسجيل حساب جديد. عند الدفع كضيف يمكن لأي شخص كتابة بريد شخص آخر - فقد يلغي ضيف اشتراك شخص آخر. تسجيل حساب جديد يُعد ضيفاً: المتجر لا يتحقق من عنوان البريد.

• يُسجَّل إلغاء الاشتراك مثل أي إلغاء آخر: في سجل اشتراكات جهة الاتصال (المصدر prestashop_checkout / prestashop_registration، السبب checkout_box_unticked، مع النص المعروض بجانب المربع) وكحدث message.unsubscribed.
• حتى من لم يوافق قط: عند تشغيل الإعداد، يلغي المربع غير المحدد اشتراك الشخص حتى لو لم يوافق قط (Not Set يصبح Unsubscribed). ومثل كل إلغاء اشتراك، ينطبق على كل جهة اتصال لها البريد الإلكتروني أو الهاتف نفسه في مساحة العمل، والتراجع عنه يتطلب موافقة جديدة.
• لا يحدث أبداً لمربع لم يُعرض (مربع SMS فقط حيث يُعرض)، ولا من مزامنة طلبات سابقة، ولا لمربع أُزيل تحديده قبل تقديم الطلب - إزالة التحديد أثناء الدفع تسحب فقط تحديد عملية الدفع نفسها. لا يشترك أو يعيد اشتراك أي شخص أبداً، ولا يغيّر حظراً بسبب ارتداد أو شكوى.
• تعرض Integrations → PrestaShop → Settings الإعداد للقراءة فقط. الإصدارات الأقدم لا تبلّغ عنه، ويعامله Joryio على أنه معطّل.

كتلة النشرة البريدية

كتلة النشرة البريدية (الوحدة ps_emailsubscription) نموذج عام: يمكن لأي شخص كتابة أي عنوان بريد إلكتروني فيها. لذلك يتعامل Joryio معها بشكل مختلف عن حساب العميل نفسه:

• الاشتراك يُعدّ موافقة فقط عندما يثبت PrestaShop أن العنوان يخص الشخص: إما أن المتسوق مسجّل الدخول إلى الحساب المسجّل بهذا البريد، أو أن التحقق من البريد الإلكتروني مفعّل في إعدادات كتلة النشرة وتم النقر على رابط التأكيد (يستلم Joryio الاشتراك بعد التأكيد، في تشغيل cron التالي). أي شيء آخر لا يُرسل إلى Joryio. فعّلوا التحقق من البريد الإلكتروني في إعدادات كتلة النشرة لكي تصل اشتراكات الزوار إلى Joryio.
• يُحتسب التأكيد فقط لعنوان لم يكن مشتركًا عند إرسال النموذج، وفقط عندما يسجّل PrestaShop الاشتراك بعد إرسال النموذج. العنوان الذي كان مشتركًا بالفعل لا يُرسل مرة أخرى؛ وإذا عُطّل التحقق من البريد قبل النقر على الرابط، يُحذف الاشتراك. يستلم Joryio تاريخ الاشتراك الذي سجّله PrestaShop (بالنسبة للزائر، يحتفظ PrestaShop بوقت التسجيل وليس بوقت التأكيد).
• إلغاء الاشتراك من الكتلة يُطبَّق دائمًا، حسب عنوان البريد الإلكتروني - طلب إلغاء الاشتراك هو الاتجاه الآمن. ولا يربط الطلب أبدًا بحساب عميل.
• الاستيراد الأولي والمزامنة الآن يشتركان عميلًا يعرضه PrestaShop كمشترك فقط إذا لم تُلغِ جهة الاتصال اشتراكها قط؛ ولا يعيدان اشتراك أي أحد. عندما يكون التحقق من البريد معطّلًا، يضع PrestaShop نفسه علامة الاشتراك على عميل مسجّل عندما يكتب أي شخص عنوانه في الكتلة، ولا يستطيع الاستيراد التمييز بين ذلك.
• تغيير النشرة البريدية المحفوظ على العميل من واجهة المتجر بواسطة شخص غير مسجّل الدخول كذلك العميل يمكنه إلغاء الاشتراك، لكنه لا يشترك أبدًا.

تتبع واجهة المتجر

ابتداءً من الوحدة 1.1.0 تضيف الوحدة متتبّع Joryio إلى واجهة متجركم (مفعّل افتراضيًا - Storefront tracking في صفحة الوحدة). يُخزَّن كل حدث باسمه القياسي، وهو الاسم نفسه المستخدم في WooCommerce و Shopify و Magento:

الحدث	يُخزَّن باسم	متى يُرسل
Page View	Page Viewed	كل صفحة
Product Viewed	Product Viewed	صفحة منتج، مع التركيبة المختارة والسعر والعلامة التجارية والفئة وحالة المخزون: in_stock (true أو false) و stock_status (in_stock أو backorder أو out_of_stock)
Category Viewed	Product List Viewed	صفحة فئة، مع category_id و category_name وعنوان الصفحة
Search	Products Searched	صفحة نتائج البحث، مع query
Add to Cart	Product Added	كل إضافة: زر الإضافة إلى السلة، ونموذج منتج يعيد تحميل الصفحة، وزيادة الكمية في السلة. يسجّل PrestaShop الإضافة ويرسلها متصفح المتسوق مرة واحدة
Remove from Cart	Product Removed	تقليل الكمية أو إزالة منتج من السلة
Cart Viewed	Cart Viewed	صفحة السلة
Checkout Started	Checkout Started	صفحة إتمام الشراء، مرة واحدة لكل سلة. إعادة تحميلها ليست بداية ثانية
Identify	$identify	العميل المسجّل الدخول، والبريد الإلكتروني المكتوب في نماذج تسجيل الدخول أو التسجيل أو إتمام الشراء أو النشرة البريدية، وبريد الطلب في صفحة تأكيد الطلب

الطلب نفسه ليس حدثًا من واجهة المتجر: يأتي Order Completed من الطلب الذي ترسله الوحدة، فتُحتسب الإيرادات مرة واحدة.

الهوية والموافقة. بالنسبة للعميل المسجّل الذي سجّل الدخول (الوحدة 1.2.2 أو أحدث)، توقّع الوحدة رقم عميل PrestaShop على خادم المتجر؛ يتحقق Joryio من هذا الإثبات ويضم تصفّح الزائر إلى جهة الاتصال التي تحمل رقم العميل هذا بالفعل - وليس أبدًا إلى جهة اتصال وُجدت حسب البريد الإلكتروني. أي عملية identify أخرى (ضيف، بريد مكتوب) تضيف البريد الإلكتروني فقط إلى الملف المجهول الخاص بالزائر في Joryio (لا تستبدل أبدًا بريدًا موجودًا في الملف، ولا تدمج جهتي اتصال حسب البريد الإلكتروني). كانت الإصدارات الأقدم من الوحدة تتعرّف على العميل المسجّل الدخول بالبريد الإلكتروني فقط، ما قد يترك جهة اتصال ثانية تحمل البريد فقط؛ بعد التحديث تُضم إلى جهة اتصال العميل في المرة التالية التي يسجّل فيها العميل الدخول من المتصفح نفسه. لا تشترك عملية identify أي أحد أبدًا - الموافقة تأتي فقط من اشتراك العميل في النشرة البريدية، راجعوا الموافقة التسويقية.

المتصفحات المشتركة (الوحدة 1.2.14 أو أحدث). يمنح تسجيل الخروج من المتجر المتصفح زائرًا مجهولًا جديدًا، فلا يظهر الشخص التالي على الجهاز نفسه على أنه الشخص الذي سبقه. وعندما يسجّل عميل آخر الدخول في متصفح استخدمه عميل آخر، يحصل أولًا على زائر جديد، وعندما يجد Joryio أن زائر المتصفح يعود بالفعل إلى شخص آخر (مثل مدير المتجر الذي استخدمه من قبل)، تبدأ الوحدة زائرًا جديدًا وترسل إثبات تسجيل الدخول مرة أخرى. يبقى ملف الشخص السابق وسجلّه كما هما، ولا يُدمج شخصان أبدًا. وأثناء حسم ذلك تنتظر أحداث الصفحة بضع ثوانٍ على الأكثر.

القوالب. يستخدم المتتبّع خطافات PrestaShop القياسية (displayHeader و actionFrontControllerSetMedia و displayOrderConfirmation) وأحداث السلة التي يسجّلها PrestaShop نفسه، لذا يعمل مع قالبي Classic و Hummingbird ومعظم القوالب الأخرى. القالب الذي يزيل خطاف displayHeader، أو وحدة إتمام شراء من صفحة واحدة تستبدل صفحة order، قد يوقف الأحداث الخاصة بصفحات معينة (مثل Checkout Started)؛ أما مشاهدات الصفحات وأحداث السلة والإسناد فتستمر في العمل. وحدة التخزين المؤقت للصفحات (page cache) تخزّن من المتتبّع البيانات العامة للصفحة فقط: بريد العميل المسجّل الدخول وأحداث السلة يجلبها متصفح كل زائر ولا تُخزَّن مؤقتًا أبدًا.

موافقة ملفات تعريف الارتباط. كما في تكاملي WooCommerce و Magento، لا ينتظر المتتبّع شريط ملفات تعريف الارتباط. إذا كان متجركم يحتاج إلى موافقة قبل ملفات تعريف الارتباط التحليلية، أوقفوا Storefront tracking أو حمّلوه عبر وحدة الموافقة الخاصة بكم.

إسناد الحملات

ينسخ المتتبّع معرّفات نقرات Joryio (jr_cid للحملة، و jr_jid للرحلة) ومعاملات UTM من الرابط الذي وصل به المتسوق إلى ملفات تعريف ارتباط من الطرف الأول (joryio_jr_cid و joryio_jr_jid و joryio_utm_*، لمدة 30 يومًا). ترفقها الوحدة بالطلب، فيُنسب البيع إلى الحملة أو الرحلة - راجعوا إسناد الإيرادات. كما تحتفظ بها مع سلة المتسوق، فيُنسب أيضًا الطلب الذي يؤكَّد لاحقًا عبر استدعاء من مزوّد الدفع (بدون متصفح المتسوق). الطلبات من الاستيراد الأولي لا تحمل إسنادًا.

التعرّف على الزوار من البريد الإلكتروني الذي يكتبونه

بدءًا من الإصدار 1.2.10 من الوحدة، تحتوي صفحة إعداد الوحدة على Recognise visitors by the email they type. يكون مفعّلًا افتراضيًا، والوحدة الأقدم تتصرّف كأنه مفعّل.

• مفعّل (افتراضي) - البريد الإلكتروني الذي يكتبه الزائر عند الدفع أو في نموذج يعرّف متصفحه على أنه جهة الاتصال صاحبة هذا البريد: جهة الاتصال الموجودة (الأحدث نشاطًا، عندما تشترك عدة جهات اتصال في البريد - انظر أدناه) أو جهة اتصال جديدة. يُضم تصفح الزائر السابق إلى جهة الاتصال هذه، ولا تُنشأ جهة اتصال ثانية بالبريد نفسه. هذا ما تتوقعه معظم المتاجر. المقابل: من يكتب بريد شخص آخر يُتعرَّف عليه كذلك الشخص في هذا المتصفح - فقد يرى مثلًا رسائل in-app والمحتوى المخصّص لذلك الشخص.
• معطّل (هوية صارمة) - البريد المكتوب لا يعرّف المتصفح أبدًا. تذهب السلة والطلب وإرسال النموذج مع ذلك إلى جهة الاتصال صاحبة هذا البريد، فتصل رسائل السلة المتروكة إلى العنوان المكتوب. لا يُتعرَّف في المتصفح إلا على عميل مسجّل الدخول إلى المتجر.

يعرض Joryio الإعداد للقراءة فقط ضمن التكاملات → PrestaShop → الإعدادات، مع إصدار الوحدة ووقت آخر إبلاغ عنه - ويُضبط في الوحدة فقط. حفظه يُبلغ Joryio به فورًا، ويسري التغيير خلال دقائق.

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

عندما تشترك عدة جهات اتصال في بريد إلكتروني

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

رسائل In-App وإشعارات الويب

ابتداءً من الوحدة 1.1.0 يحمّل المتتبّع أيضًا حزمة Joryio للويب (SDK) في واجهة متجركم، من https://sdk.joryio.com/web/1/joryio.min.js (أحدث إصدار من 1.x). تذهب طلبات البيانات الخاصة بها إلى عنوان الخادم الذي ربطتم به. الإعدادات موجودة في صفحة الوحدة:

الإعداد	الافتراضي	ما الذي يفعله
In-app messages	نعم	يعرض رسائل In-App الخاصة بكم من Joryio في المتجر
Allow HTML in-app messages	نعم	يعرض أيضًا الرسائل المبنية بمحرر HTML. تُعرض في إطار محمي: النصوص البرمجية المكتوبة فيها لا تعمل، ولا تستطيع الرسالة الوصول إلى صفحات متجركم أو إجراء طلبات شبكة خاصة بها
Web push	لا	يتيح للمتسوقين الاشتراك في إشعارات المتصفح

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

إعداد إشعارات الويب

لا يقبل المتصفح عامل الخدمة (service worker) الخاص بالإشعارات إلا من عنوان متجركم نفسه، في https://your-shop/joryio-sw.js. فعّلوا Web push واحفظوا، ثم افتحوا لوحة Web push في صفحة الوحدة:

1. متجر واحد في جذر نطاقه: تكتب الوحدة الملف joryio-sw.js في مجلد PrestaShop. تذكر اللوحة ذلك - لا شيء آخر عليكم فعله. (إذا لم يكن المجلد قابلًا للكتابة، أو كان فيه بالفعل ملف joryio-sw.js لم تكتبه الوحدة، تذكر اللوحة ذلك بدلًا منه.)
2. في غير ذلك (Multistore، أو مجلد للقراءة فقط): تجيب الوحدة بنفسها على /joryio-sw.js عندما يمرّر خادمكم العناوين غير المعروفة إلى PrestaShop، وهو ما يفعله ملف .htaccess الخاص بـ PrestaShop عند تفعيل العناوين الودّية (friendly URLs). انقروا Check the service worker address في اللوحة: يجب أن يُظهر نصًا برمجيًا يبدأ بـ // Joryio web push.
3. إذا أظهر الفحص صفحة 404، أضيفوا السطر الواحد الذي تعرضه اللوحة إلى إعدادات خادمكم:
   • Apache، في .htaccess فوق قواعد PrestaShop: RewriteRule ^joryio-sw\.js$ index.php?fc=module&module=joryio&controller=sw [QSA,L]
   • nginx: location = /joryio-sw.js { rewrite ^ /index.php?fc=module&module=joryio&controller=sw last; }

لا يمكن استخدام إشعارات الويب مع PrestaShop المثبّت في مجلد فرعي (https://example.com/shop/): لا تقبل المتصفحات عامل الخدمة إلا في جذر النطاق.

يُطلب من المتسوقين الإذن عبر رسالة In-App لطلب الاشتراك في الإشعارات (push opt-in) تنشئونها في Joryio، لذا أبقوا In-app messages مفعّلًا، وفعّلوا إشعارات الويب للتطبيق في Joryio أيضًا. إيقاف Web push يجعل العنوان نفسه يقدّم عامل خدمة يزيل نفسه من متصفحات الزوار.

فعّل إشعارات الويب في Joryio أيضًا. أنشأ ربط المتجر تطبيقًا له في Joryio (الإعدادات → التطبيقات، باسم المتجر). افتحه، وانقر على الجرس (Push) ثم تفعيل Web Push: يُنشئ ذلك مفاتيح إشعارات الويب الخاصة بالمتجر، التي يقرؤها SDK في متجرك بنفسه - لا شيء لنسخه. ثم أنشئ رسالة داخل التطبيق بزر مضبوط على اطلب تفعيل الإشعارات واعرضها في ذلك التطبيق؛ يمكن للمتسوقين الذين يوافقون تلقي حملات الإشعارات وخطوات الرحلات.

برامج القسائم

ابتداءً من الوحدة 1.1.0 يمكن لـ برامج القسائم استخدام المتجر: ينشئ Joryio رمز كل شخص على شكل قاعدة سلة (cart rule) في PrestaShop عبر مفتاح Webservice (باسم Joryio - <program> (<variable> v<version>)، ويذكر وصفها أنها أُنشئت بواسطة Joryio).

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

رابط التطبيق. يفتح {{ coupons.<variable>.apply_url }} العنوان index.php?fc=module&module=joryio&controller=coupon&code=... في متجركم: يدخل الرمز إلى سلة المتسوق، مع فحوصات PrestaShop نفسها (التواريخ، ومرات الاستخدام، والحد الأدنى، والمنتجات، وقفل الحساب). مع سلة فارغة يُحتفظ بالرمز ويُطبَّق عند إضافة منتج؛ والرمز المقفل يطلب من المتسوق تسجيل الدخول أولًا.

الاستردادات. يُرسل كل رمز على الطلب مع الخصم الذي منحه، فتصل الاستردادات والإيرادات إلى تقرير البرنامج. يقرأ الاستيراد الأولي وSync now الرموز أيضًا (الوحدة 1.1.0 أو أحدث).

الترقية من 1.0.0. ارفعوا ملف zip الجديد للوحدة فوق القديم (Module Manager → Upload a module). تمنح الترقية مفتاح Webservice الحالي صلاحية قواعد السلة - ويبقى اتصالكم كما هو. حتى ذلك الحين يعرض Joryio "PrestaShop refused coupon access" على البرنامج.

نماذج الموقع

بدءًا من الوحدة 1.2.0، يمكن لنماذج متجركم إرسال ما يُرسَل عبرها إلى Joryio، بالطريقة نفسها التي تعمل بها نماذج ووردبريس: كل إرسال ينشئ جهة الاتصال أو يحدّثها ويسجّل حدث Form Submitted، وتختارون لكل نموذج ما إذا كان يشترك جهة الاتصال أيضًا في القوائم.

النموذج	متى يُرسَل
نموذج الاتصال (وحدة contactform في PrestaShop)	عندما يحفظ PrestaShop رسالة الزائر. يجب تفعيل Save messages لجهة الاتصال المختارة في النموذج (Customers → Contacts)؛ الرسالة إلى جهة اتصال بدون هذا الإعداد يرسلها PrestaShop بالبريد فقط ولا تصل إلى Joryio
نماذج أخرى	عندما تستدعي وحدة أو القالب الـ hook actionJoryioFormSubmit بعد قبول الإرسال (انظروا أدناه). يظهر النموذج في صفحة الوحدة في أول مرة يُرسَل فيها، أو تضيفونه هناك بمعرّفه

إعداد نموذج. في صفحة الوحدة، ضمن نماذج الموقع، حدّدوا إرسال هذا النموذج إلى Joryio واربطوا حقول النموذج:

• حقل البريد الإلكتروني وحقل الهاتف وحقل الاسم الأول وحقل اسم العائلة - اسم حقل النموذج. حقل البريد الإلكتروني في نموذج الاتصال هو from. اربطوا حقل بريد إلكتروني أو هاتف على الأقل: الإرسال الذي لا يحتوي على أي منهما لا يُرسَل.
• سمات مخصصة - واحدة في كل سطر، attribute_key = اسم الحقل (مثلًا company = company).
• القوائم - القوائم التي يشترك فيها النموذج. بدون قائمة تُحفظ جهة الاتصال فقط.
• الاشتراك في القوائم - فقط عند تحديد مربع الموافقة (الافتراضي؛ أدخلوا اسم المربع)، أو هذا نموذج اشتراك - اشترك دائمًا.
• صياغة الموافقة (الوحدة 1.2.17) - النص الدقيق المعروض بجانب مربع الموافقة. لا تستطيع الوحدة قراءة تسمية القالب الخاص بكم، لذا اكتبوه هنا. عندما يحدد الزائر المربع، يسجّل Joryio هذه الصياغة في سجل الموافقة على أنها ما وافق عليه.

ثم انقروا حفظ إعدادات النماذج. يبدأ كل نموذج متوقفًا: لا يُرسَل شيء حتى تفعّلوه.

ما يُرسَل. الحقول التي تربطونها فقط - لا تُرسَل الرسالة نفسها إلا إذا ربطتموها بسمة. البريد الإلكتروني هو الذي كتبه الزائر: لا يُربط أبدًا بحساب عميل في المتجر، ولا يغيّر نموذج الزائر أبدًا البريد الإلكتروني أو الهاتف لجهة اتصال موجودة. يمكن للعميل المسجَّل دخوله تحديث هاتفه (الوحدة 1.2.18): عندما يرسل عميل مسجَّل دخوله إلى متجرك نموذجًا ويكون بريد النموذج تابعًا لجهة الاتصال الخاصة به، يحلّ الهاتف الذي كتبه محل هاتف جهة الاتصال. تثبت الوحدة هوية المستخدم المسجَّل دخوله بإثبات موقَّع يُنشأ على خادم المتجر، فقط لنموذج أُرسل على متجرك؛ ولا يتغير البريد الإلكتروني بهذه الطريقة أبدًا. القائمة التي تتطلب تأكيدًا مزدوجًا ترسل أولًا بريد التأكيد؛ وتُشترك جهة الاتصال عند التأكيد. يُسجَّل Form Submitted سواء وافق الزائر أم لا (الخصائص: source - prestashop_contact أو prestashop_form، وformId وformName وpageUrl وconsentGiven وconsentText وlistsSubscribed وlistsPending، وemail وphone الخاصين بالنموذج (بالتنسيق الذي تخزّنهما به جهة الاتصال، حتى لا يضيع هاتف مختلف كتبه زائر) وphoneUpdated عندما يختلف هاتف النموذج عن هاتف جهة الاتصال - true عندما تحمله جهة الاتصال الآن، وfalse عندما احتفظت جهة الاتصال بهاتفها. أعضاء الفريق غير المسموح لهم برؤية البيانات الشخصية لا يرون قيم البريد والهاتف، وتُمحى هذه القيم مع الشخص). عندما يشترك النموذج بجهة الاتصال في قائمة، يحتفظ سجل الموافقة في سجل الاشتراكات بإثبات الموافقة: صياغة المربع المحدَّد (صياغة الموافقة، أو consent_text الذي مرّره النموذج)، والصفحة التي أُرسل منها النموذج (pageUrl)، والوقت، وعنوان IP للزائر (يظهر فقط لأعضاء الفريق المسموح لهم برؤية البيانات الشخصية). المربع غير المحدد لا يرسل صياغته أبدًا. بدون قائمة لا يُشترك أحد، فلا يُكتب سجل موافقة: تبقى الصياغة في حدث Form Submitted فقط (ولا يوضع عنوان IP في الحدث أبدًا).

الموافقة في نموذج الاتصال. لا يحتوي نموذج الاتصال في PrestaShop على مربع للتسويق. لاشتراك الزوار الموافقين، أضيفوا مربعًا غير محدد مثل <input type="checkbox" name="joryio_consent" value="1"> إلى نسخة نموذج الاتصال في قالبكم، وأدخلوا joryio_consent كحقل الموافقة. مربع GDPR في نموذج الاتصال هو موافقة على معالجة الرسالة، وليس على التسويق - لا تستخدموه كحقل الموافقة.

نماذج أخرى. يضيف المطوّر استدعاءً واحدًا حيث يُقبل النموذج:

Hook::exec('actionJoryioFormSubmit', [
    'form_id' => 'quote',            // letters, digits and _ . : -
    'form_name' => 'Quote request',
    'values' => ['email' => $email, 'company' => $company, 'consent' => $consentTicked],
    'consent_text' => 'Email me news and offers', // optional (1.2.17): the text next to the consent checkbox
]);

consent_text اختياري؛ عند تمريره يُستخدم بدل صياغة الموافقة للنموذج، وفقط عندما يكون مربع الموافقة محددًا.

التسليم. تدخل عمليات الإرسال إلى قائمة الانتظار ويرسلها cron مثل أي حدث آخر، بالمحاولات المتكررة نفسها؛ ولا يُسجَّل الإرسال المُعاد أبدًا مرتين.

الترقية من 1.1.0. ارفعوا ملف zip الجديد للوحدة فوق القديم (Module Manager → Upload a module). تسجّل الترقية الـ hooks الجديدين؛ ويبقى اتصالكم وإعداداتكم كما هي.

التعرّف على الزائر. البريد المكتوب في نموذج على الموقع يعرّف أيضًا متصفح الزائر عندما يكون التعرّف على الزوار من البريد الإلكتروني الذي يكتبونه مفعّلًا (الافتراضي). يذهب الإرسال نفسه دائمًا إلى جهة الاتصال صاحبة هذا البريد.

استرداد السلات المتروكة

1. تتتبع الوحدة السلات أثناء تسوق العملاء
2. بعد فترة من عدم النشاط (تُضبط في صفحة الوحدة)، يتم إبلاغ Joryio بأن السلة متروكة
3. يستلم Joryio السلة مع رابط استعادة موقّع
4. استخدموا رحلة لإرسال رسائل الاسترداد مع هذا الرابط

يفتح رابط الاستعادة المتجر مع إعادة منتجات السلة إليها. في سلة الزائر، تُستبعد المنتجات التي لم يعد ممكنًا إضافتها مع الرسالة "بعض المنتجات لم تعد متاحة ولم تُضف."؛ وعندما لا يمكن إضافة أي منها يرى المتسوّق "لم تعد المنتجات في هذه السلة متاحة." (الوحدة v1.2.5 أو أحدث).

فتح الرابط: صفحة استعادة، وسلة واحدة لكل رابط

بدءاً من الوحدة 1.2.9، لا يغيّر فتح الرابط وحده أي شيء. فمعاينات الروابط في تطبيقات الدردشة وماسحات أمان البريد (Outlook Safe Links وGmail وغيرهما) تفتح الروابط قبل المتسوق، وكان كل فتح من هذا النوع ينسخ سلة الزائر مرة أخرى - فقد يترك رابط واحد عدة نسخ.

• فتح الرابط يعرض صفحة قصيرة ضمن قالب متجرك، "جارٍ استعادة سلتك المحفوظة..."، لا تُخزَّن مؤقتاً ولا تُفهرس أبداً. عندما تكون سلة هذا المتصفح فارغة، يستعيد السكربت فيها السلة المحفوظة ثم ينتقل إلى صفحة السلة؛ ومن دون سكربت ينقر المتسوق استعادة سلتي. وعندما تحتوي سلة هذا المتصفح على منتجات بالفعل، تسأل الصفحة أولاً، لأن الاستعادة تستبدل السلة المعروضة في هذا المتصفح: استعادة سلتي أو الاحتفاظ بسلتي الحالية. المعاينة أو الماسح الذي لا يشغّل السكربت لا يستعيد شيئاً.
• سلة واحدة لكل رابط، في كل متصفح - في سلة الزائر، تُحفظ النسخة التي أنشأها الرابط مع المتصفح الذي أُنشئت فيه (ملف تعريف ارتباط الزائر في المتجر). فتح الرابط نفسه مرة أخرى في ذلك المتصفح (مثلاً بعد فقدان سلته) يعيد النسخة نفسها بدلاً من نسخة جديدة، لمدة 7 أيام (يعيد رابط الاستعادة استخدام سلته لمدة (أيام) في صفحة الوحدة، من 1 إلى 30)، ما لم يكن فيها عنوان. أما المتصفح أو الجهاز الآخر - أو الماسح الذي شغّل الصفحة فعلاً - فلا يحصل على تلك النسخة أبداً، حتى لو كان عميل مسجّلاً الدخول فيه: يحصل على نسخة جديدة فيها منتجات السلة المحفوظة فقط، فلا يظهر أي شيء كتبه أحد عند الدفع في متصفح ما في متصفح آخر. بعد ذلك يتذكر الرابط نسخة أحدث متصفح. تظل النسختان محسوبتين على أنهما السلة المحفوظة نفسها: الطلب من أي منهما استرداد واحد، ولا يُرسل إلا تذكير واحد بأن السلة "تُركت مرة أخرى" لكل سلة أصلية.
• تم الطلب بالفعل - "تم بالفعل تقديم طلب من هذه السلة."، ولا يُستعاد شيء.
• 10 عمليات استعادة كحد أقصى لكل رابط في الساعة - بعدها، "محاولات كثيرة جدًا باستخدام رابط السلة هذا. يرجى المحاولة لاحقًا."

النسخة المستعادة لزائر ليس لها بريد إلكتروني (لا ينسخه الرابط أبداً)؛ بدءاً من 1.2.9 يُبلَّغ عنها مع ذلك، دون بريد، ويرسل Joryio التذكير الواحد إلى جهة اتصال السلة الأصلية - راجع السلال.

بدءًا من الإصدار 1.2.11، يذكر كل حدث سلة لنسخة مستعادة السلة التي استُعيدت منها (restoredFromSessionId)، فتظهر نسخة الضيف في E-Commerce → السلال كـنسخة مستعادة من سلة جهة الاتصال الأصلية بدلًا من سلة بدون جهة اتصال، ولا تُحتسب سلة متروكة إضافية - راجع السلال.

بدءًا من الوحدة 1.2.12، يحمل كل حدث سلة رابط استرداد السلة (صالح لمدة 30 يومًا من تحديث السلة ذاك) وما إذا كانت سلة زائر، وتُبلغ الوحدة عن Track guest carts وعن مدة الترك مع كل طلب، لذا فالسلة التي يحددها Joryio بنفسه كمتروكة تتبعهما - راجع السلال. عندما يكون Track guest carts متوقفًا لم تعد الوحدة ترسل سلال الدفع كزائر إطلاقًا (كان الإصدار 1.2.11 يرسلها لكنه لم يُبلغ عنها كمتروكة). يصل البريد الإلكتروني للزائر إلى السلة عند إرسال خطوة المعلومات الشخصية؛ والبريد الذي كُتب قبل ذلك يُعرّف المتصفح فقط.

إسناد طلبات الاستعادة

بدءًا من الوحدة 1.2.6، يحتفظ رابط الاستعادة بمعاملات الإسناد التي يضيفها تتبع النقرات في Joryio (jr_cid وjr_jid وutm_*) عندما ينقل المشتري إلى السلة، فيُسند الطلب إلى الرسالة التي أرسلت الرابط. تُنقل هذه المعاملات فقط، ويُتحقق من صيغة كل منها - ولا يُنقل رمز الرابط أو أي شيء آخر أبدًا. وعندما يفتح المشتري الرابط ويُتم الشراء ببريد إلكتروني مختلف، يُسند Joryio الطلب إلى نقرة جهة الاتصال التي أُرسلت إليها الرسالة. راجع السلال.

قطع الاتصال وإلغاء التثبيت

• قطع الاتصال في صفحة الوحدة ينهي الاتصال ويحذف مفتاح Webservice الذي أنشأته الوحدة. يبقى مفتاح API صالحًا - انقر Connect مجددًا بالمفتاح نفسه (الوحدة 1.2.1 أو أحدث).
• قطع الاتصال في Joryio يُبطل مفتاح API فورًا: في المرة التالية التي ترسل فيها الوحدة حدثًا تتوقف وتعرض تنبيهًا، والاتصال بهذا المفتاح يعرض «This key was revoked when the store was disconnected in Joryio». أنشئ مفتاحًا جديدًا للاتصال مجددًا. يحذف Joryio نسخته من مفتاح Webservice؛ أما المفتاح نفسه فيبقى في PrestaShop حتى تنقر Disconnect في صفحة الوحدة أو تلغي تثبيت الوحدة.
• إلغاء تثبيت الوحدة في Module Manager. يقطع اتصال المتجر، ويُبطل مفتاح API (الوحدة 1.2.1 أو أحدث)، ويحذف مفتاح Webservice الذي أنشأته، ويزيل جداول الوحدة وملف joryio-sw.js وإعداداتها. تبقى رموز القسائم التي أنشأها Joryio في المتجر كقواعد سلة.

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

فشل الربط: Webservice

• تشغّل الوحدة Webservice عند الربط. إذا أُوقف مرة أخرى (Advanced Parameters → Webservice)، يتوقف الاستيراد الأولي وSync now عن العمل.
• تزيل بعض الاستضافات ترويسة Authorization قبل وصولها إلى PHP. عندها يرسل Joryio المفتاح كمعامل ws_key، وهو ما يقبله PrestaShop أيضًا. إذا رُفض الاثنان، تحققوا من قواعد الخادم أو إضافة الحماية الخاصة بـ /api/.

فشل الربط: عنوان المتجر

• استخدموا عنوان https النهائي للمتجر. يُرفض عنوان المتجر الذي يعيد التوجيه (مثلًا من http:// أو إلى www.).
• يجب أن يكون العنوان عامًا. تُرفض العناوين المحلية وعناوين الشبكات الخاصة وعناوين .local.

لا يصل شيء إلى Joryio

• تحققوا من قائمة الانتظار في صفحة الوحدة: الأحداث المنتظرة وغير المسلّمة وآخر خطأ.
• اضبطوا مهمة cron، خصوصًا في متجر هادئ.

إشعارات الويب: لا يظهر طلب الإذن

• افتحوا https://your-shop/joryio-sw.js: يجب أن يُظهر نصًا برمجيًا يبدأ بـ // Joryio web push. إذا لم يكن كذلك، اتبعوا إعداد إشعارات الويب.
• أبقوا Storefront tracking وIn-app messages مفعّلين، وأنشئوا رسالة In-App لطلب الاشتراك في الإشعارات في Joryio.

لا تُنشأ رموز القسائم

• "PrestaShop refused coupon access": حدّثوا الوحدة إلى 1.1.0 أو أحدث، أو انقروا Connect مرة أخرى.
• برنامج لمنتجات أو فئات مختارة يحتاج إلى الوحدة 1.1.0 أو أحدث في المتجر.

إرسال نموذج لا يصل

تحققوا من أن النموذج مفعّل وأن حقل بريد إلكتروني أو هاتف مربوط فيه بالاسم الدقيق للحقل، وأن Save messages مفعّل لجهة الاتصال المختارة في نموذج الاتصال، وأن cron يعمل (راجعوا لا شيء يصل إلى Joryio). يتطلب الاشتراك في قائمة موافقةً أيضًا: في وضع الموافقة، يجب تحديد المربع.

"مفتاح API غير صالح"

• يجب أن يبدأ المفتاح بـ jry_ps_ وأن يطابق المفتاح المعروض في صفحة PrestaShop في Joryio.
• Disconnect في صفحة الوحدة يحتفظ بالمفتاح (الوحدة 1.2.1 أو أحدث): انقر Connect مجددًا به. قطع الاتصال في Joryio أو إلغاء تثبيت الوحدة يُبطله - ويذكر الاتصال ذلك؛ أنشئ مفتاحًا جديدًا والصقه قبل أن تنقر Connect مجددًا.