تكامل Magento

اربط متجر Magento 2 باستخدام امتداد Joryio Connect. زامن المنتجات والطلبات والعملاء والسلات، وتتبع سلوك واجهة المتجر، واسترد السلات المتروكة.

الميزات

• امتداد مثبت عبر Composer - وحدة Magento 2 أصلية، من دون الحاجة إلى OAuth
• مزامنة تلقائية - تتدفق المنتجات والطلبات والعملاء والسلات إلى Joryio كل دقيقة
• استيراد تاريخي - تُستورد المنتجات والعملاء والطلبات الحالية (آخر 90 يومًا افتراضيًا) عند الربط
• استرداد السلات المتروكة - اكتشف السلات المتروكة وأرسل روابط استرداد تعيد السلة
• تتبع واجهة المتجر - مشاهدات الصفحات والمنتجات والفئات والإضافة إلى السلة وأحداث إتمام الشراء
• التقاط الهوية - تعرّف تلقائي على العملاء من تسجيل الدخول والاشتراك في النشرة وإتمام الشراء
• إسناد الإيرادات - تُنسب الطلبات إلى الحملة أو الرحلة التي أدت إليها
• مشغلات الكتالوج - تدعم تحديثات المخزون والسعر مشغلات العودة إلى المخزون وانخفاض السعر

المتطلبات المسبقة

• Magento Open Source أو Adobe Commerce بالإصدار 2.4.x
• وصول إلى سطر الأوامر لخادم Magento مع Composer
• إعداد وتشغيل Magento cron؛ إذ يسلّم الامتداد الأحداث عبر cron، وهذا مطلوب
• وصول HTTPS صادر من خادم Magento إلى Joryio

خطوات الإعداد

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

1. في Joryio، انتقل إلى الإعدادات → التكاملات → Magento.
2. انسخ عنوان URL للخادم. إنه عنوان المنطقة التي يوجد فيها حساب Joryio الخاص بك، مثل https://api-eu1.joryio.com. ابتداءً من الإصدار 1.4.1 للامتداد لا توجد قيمة افتراضية، لذا الصق هذه القيمة تمامًا.
3. انقر إنشاء مفتاح API وانسخ المفتاح (يبدأ بـ jry_mg_). عندما تفتح هذه الصفحة مجددًا لاحقًا تعرض المفتاح نفسه مخفيًا - انقر أيقونة العين لرؤيته. يبقى المفتاح كما هو حتى يُقطع اتصال المتجر.

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

نزّل ملف zip للامتداد (joryio-connect-magento2.zip) بواسطة زر تنزيل الامتداد في صفحة تكامل Magento في لوحة التحكم، ثم فك ضغطه وشغّل هذه الأوامر من جذر Magento:

composer config repositories.joryio path /path/to/joryio-connect
composer require joryio/module-connect
bin/magento module:enable Joryio_Connect
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

بدلًا من ذلك (من دون Composer): فك ضغط الملف إلى app/code/Joryio/Connect وشغّل أوامر bin/magento نفسها.

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

1. في لوحة إدارة Magento، انتقل إلى Stores → Configuration → Joryio.
2. الصق عنوان URL للخادم ومفتاح API من الخطوة 1.
3. انقر Connect.

ينشئ الامتداد تلقائيًا رمز وصول لتكامل Magento ويشاركه بأمان مع Joryio؛ لا تحتاج إلى إنشاء أي رموز يدويًا. تتحقق Joryio من الاتصال وتبدأ فورًا مزامنة تاريخية كاملة (المنتجات ثم العملاء ثم الطلبات؛ آخر 90 يومًا افتراضيًا).

عند انتهاء العملية، تعرض صفحة إدارة Magento ولوحة تحكم Joryio الحالة Connected.

السماح برموز وصول OAuth كرموز Bearer

يقرأ Joryio واجهة REST API لمتجرك برمز الوصول الخاص بتكامل "Joryio"، ويُرسل كرمز Bearer. ابتداءً من Magento 2.4.4 لا يقبل Magento ذلك إلا عندما يكون الإعداد Stores → Configuration → Services → OAuth → Consumer Settings → Allow OAuth Access Tokens to be used as standalone Bearer tokens على Yes (القيمة الافتراضية No). عندما يكون على No، يشرح Connect (الامتداد v1.4.1 أو أحدث) ذلك ويسأل قبل تفعيله - لا يُنشأ شيء قبل أن تؤكد. إنه إعداد على مستوى المتجر كله: ينطبق على رموز الوصول لكل التكاملات في متجرك. يمكنك أيضًا ضبطه على Yes بنفسك ثم النقر على Connect.

إذا فشل الاتصال فلا يبقى شيء خلفه: يُحذف تكامل "Joryio" الذي أنشأه Connect (والتكامل المتبقي من اتصال سابق يُلغى رمزه)، ويُعاد إيقاف إعداد Bearer الذي فعّله Connect. تعرض الرسالة السبب الذي يقدمه Joryio - راجع فشل الاتصال.

ما الذي يُزامن

البيانات	الكيفية	الوقت
المنتجات	استيراد تاريخي + تحديثات لحظية (بما فيها تغيرات المخزون والسعر)	عند الربط، ثم باستمرار
العملاء	استيراد تاريخي + تحديثات لحظية	عند الربط، ثم باستمرار
الطلبات	استيراد تاريخي (آخر 90 يومًا افتراضيًا) + تحديثات لحظية	عند الربط، ثم باستمرار
السلات	تتبع لحظي + كشف التخلي	باستمرار
الهوية	تسجيل الدخول والاشتراك في النشرة وEmail إتمام الشراء	باستمرار

تُدرج التحديثات اللحظية محليًا في طابور متجرك ويسلمها إلى Joryio cron يعمل مرة كل دقيقة؛ لذلك يعد cron السليم في Magento ضروريًا. تغذي تحديثات المخزون والسعر أيضًا مشغلات الكتالوج (العودة إلى المخزون وانخفاض السعر).

حذف عميل في متجرك لا يحذف جهة الاتصال في Joryio. لمحو بيانات شخص ما، استخدم حذف البيانات في جهة الاتصال.

المنتجات والمخزون والفئات

• المنتجات القابلة للتهيئة (configurable) منتج واحد في Joryio. تصبح منتجاتها الفرعية (مثل كل مقاس أو لون) متغيّرات له عندما تكون مضبوطة على Not Visible Individually؛ والمنتج الفرعي المعروض بمفرده أيضًا يبقى منتجًا كذلك. يعرض المنتج أدنى سعر بين منتجاته الفرعية، ويكون متوفرًا عندما يتوفر أيٌّ منها، وكميته هي مجموع كمياتها. يحمل كل متغيّر خياراته (مثل Color: Red)، وحذف منتج فرعي يزيله من المنتج.
• يُقرأ المخزون من مصادرك عندما يستخدم المتجر Multi-Source Inventory ‏(MSI)، وإلا فمن إعدادات مخزون المنتج؛ ومع MSI تُطرح الكميات المحجوزة لطلبات لم تُشحن بعد (لما يصل إلى 2,000 منتج في كل مزامنة - يعرض الباقي كمية المصدر حتى تحديثه التالي). المنتج الذي لا يُدار مخزونه يظهر متوفرًا بدون كمية.
• تُزامن الفئات بأسمائها (عدا الفئة الجذرية للمتجر).
• تحمل سطور الطلب لمنتج قابل للتهيئة اسم المنتج ورمز SKU للمتغيّر الذي اشتراه العميل.
• مبالغ القسائم: يُبلغ Magento عن خصم واحد لكل قواعد أسعار السلة في الطلب. عندما تكون القسيمة القاعدة الوحيدة، يكون مبلغها هو خصم الطلب. ومع عدة قواعد، يعرض Joryio مبلغ القسيمة فقط عندما يكون كل سطر مخفّض قد خُفّض بقاعدة واحدة؛ وإلا يذكر الطلب أن المتجر لم يُبلغ عنه.

تتطلب الفئات ومخزون MSI وتحديثات المتغيّرات من الامتداد الإصدار 1.4.4 من الامتداد - راجع الترقية إلى 1.4.4.

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

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

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

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

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

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

الاستردادات والإلغاءات

يصبح الاسترداد في طلب Magento حدث Order Refunded واحدًا بالمبلغ المسترد، وكل طلب ملغى حدث Order Cancelled واحدًا، لكي تتمكن الرحلة من التفاعل معهما. يبلغ الامتداد عن الإلغاءات والاستردادات الكاملة (الحالة closed) لحظة حدوثها؛ أما مذكرة الائتمان (credit memo) الجزئية فتُلتقط في المرة التالية التي تُزامن فيها الطلبات. راجع أحداث الاسترداد والإلغاء.

كيف تحدّث بيانات المتجر جهة الاتصال

تحدّث الطلبات وعمليات الدفع وتحديثات العملاء من متجرك جهة الاتصال المطابقة في Joryio:

• الهاتف - الدفع كضيف: الدفع من متسوق غير مسجّل الدخول إلى المتجر لا يستبدل أبدًا الهاتف الحالي لجهة الاتصال. بل يملأ الهاتف فقط عندما لا يكون لجهة الاتصال هاتف - فعند الدفع كضيف يمكن لأي شخص كتابة أي بريد إلكتروني.
• الهاتف - العملاء المسجّلون الدخول: طلب العميل المسجّل الدخول، والتغييرات على حساب العميل في المتجر، تحدّث هاتف جهة الاتصال.
• الأسماء تتحدّث من الطلبات ومن تحديثات العملاء.
• رقم العميل في المتجر: يأتي رقم عميل Magento لجهة الاتصال من بيانات حساب العميل (تحديثات العملاء واستيراد العملاء وطلبات العملاء المسجّلين الدخول)، وليس أبدًا من الدفع كضيف. وعندما يحمل الحساب بريدًا إلكترونيًا مختلفًا، ينتقل الرقم إلى جهة الاتصال صاحبة ذلك البريد.
• يحتفظ الطلب بالهاتف المكتوب عند الدفع في عنوان الفوترة والشحن الخاص به، مهما حدث لجهة الاتصال.
• موافقة SMS المقدَّمة عند الدفع برقم مختلف عن رقم جهة الاتصال لا تؤدي إلى اشتراك رقم جهة الاتصال.
• طرق أخرى لتغيير هاتف جهة الاتصال: الدفع مع تسجيل الدخول أو حساب العميل في المتجر، أو الـ SDK أو الـ API من موقعك أو تطبيقك (مثلًا بعد تسجيل دخول الشخص)، أو الاستيراد، أو تعديل جهة الاتصال في Joryio.

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

يضيف الامتداد مقتطف تتبع خفيفًا إلى واجهة متجرك (مفعل افتراضيًا؛ يمكنك إيقافه من Stores → Configuration → Joryio). يُخزَّن كل حدث باسمه القياسي (عمود يُخزَّن باسم)، وهو الاسم نفسه الذي تستخدمه تكاملات WooCommerce و Shopify وحزم SDK:

الحدث	يُخزَّن باسم	متى يُرسل
Page View	Page Viewed	كل زيارة صفحة
Product Viewed	Product Viewed	صفحة منتج. يحمل حالة المخزون: in_stock (true أو false) و stock_status (in_stock أو out_of_stock)
Category Viewed	Product List Viewed	صفحة فئة، مع category_id و category_name وعنوان الصفحة (الامتداد v1.1.1 أو أحدث)
Add to Cart	Product Added	كل إضافة: زر AJAX، ونموذج منتج يعيد تحميل الصفحة، والنقل من قائمة الأمنيات إلى السلة. يسجّل Magento الإضافة ويرسلها متصفح المتسوق مرة واحدة (الامتداد v1.1.1 أو أحدث). إعادة الطلب من My Account لا تُحسب
Checkout Started	Checkout Started	صفحة إتمام الشراء، مرة واحدة لكل سلة. إعادة تحميلها ليست بداية ثانية
Identify	$identify	التقاط Email

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

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

تحمل أحداث المنتج product_id و variant_id (الخيار المحدد لمنتج configurable) و quantity و price و currency وحالة المخزون.

يلتقط المقتطف أيضًا معاملات UTM ومعرّفات نقرات Joryio من روابط حملاتك، حتى تُنسب الطلبات إلى الحملة أو الرحلة التي أدت إلى البيع. راجع إسناد الإيرادات.

Content Security Policy

بدءًا من الإصدار 1.4.6 من الامتداد، لا يحتوي مقتطف التتبع على أي سكربت مضمَّن (inline): إنه ملف يُقدَّم من متجرك (Joryio_Connect/js/tracking.js)، وإعداداته كتلة بيانات داخل الصفحة. يفرض Magento 2.4.7 والإصدارات الأحدث Content Security Policy صارمة على صفحات إتمام الشراء والدفع، وهي تحظر السكربتات المضمَّنة - مع الإصدار 1.4.5 أو أقدم، لم تكن صفحة إتمام الشراء ترسل Checkout Started ولا identify من حقل البريد الإلكتروني ولا Page View. لا شيء يحتاج إلى 'unsafe-inline'. يضيف الامتداد *.joryio.com وsdk.joryio.com إلى السياسة للسكربتات واستدعاءات API؛ إذا لم يكن Server URL الخاص بك على joryio.com، فأضف مضيفه إلى سياستك بنفسك. بعد ترقية متجر في وضع production، شغّل bin/magento setup:static-content:deploy حتى يُنشر الملف الجديد.

بعد تغيير الإعدادات

إعدادات المقتطف - Server URL وInject Tracking Snippet وإعدادات رسائل in-app وإشعارات Web Push - جزء من كل صفحة، لذلك تحتفظ ذاكرة التخزين المؤقت للصفحة الكاملة في Magento بالقيم التي خُزّنت بها الصفحة. بدءًا من الإصدار 1.4.6 من الامتداد، تمسح Save Config وConnect وDisconnect الصفحات المخزنة التي تحمل المقتطف فقط، في ذاكرة الصفحات المؤقتة الخاصة بـ Magento وفي Varnish، وتترك بقية الذاكرة المؤقتة كما هي. مع الإصدار 1.4.5 أو أقدم، شغّل bin/magento cache:flush بعد تغيير هذه الإعدادات. لا يمسح Magento ذاكرة CDN أو proxy مؤقتة أمامه: امسحها بنفسك بعد تغيير Server URL. وحتى ذلك الحين، لا ترسل الصفحة المخزنة القديمة شيئًا في متصفح حمّل صفحة حديثة من قبل - ولا ترسل أبدًا إلى العنوان القديم. قد يستمر Magento في عرض One or more of the Cache Types are invalidated: Page Cache بعد Save Config: يضع Magento هذه العلامة على ذاكرة الصفحات المؤقتة بعد كل حفظ للإعدادات، أيًّا كان القسم. الصفحات التي تحمل المقتطف مُسحت بالفعل؛ حدّث Page Cache من System > Cache Management في الوقت الذي يناسبك.

مشاهدات الصفحات وحزمة SDK للويب. يُرسَل حدث Page View دائمًا من مقتطف التتبع. يوقف trackPageViews: false في إعدادات SDK للويب الخاصة بالمقتطف المشاهدات التلقائية الخاصة بالـ SDK نفسه فقط، حتى تُحسب كل صفحة مرة واحدة.

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

بدءًا من الإصدار 1.4.21 من الامتداد، يحتوي Stores → Configuration → Joryio على Recognise visitors by the email they type. يكون مفعّلًا افتراضيًا، والامتداد الأقدم يتصرّف كأنه مفعّل. القيمة المُبلَّغ عنها هي قيمة Default Config.

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

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

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

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

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

رسائل in-app وإشعارات Web Push

ابتداءً من الإصدار v1.3.0 من الامتداد، يحمّل مقتطف التتبع في متجرك أيضًا حزمة Joryio للويب (SDK) من https://sdk.joryio.com/web/1/joryio.min.js (أحدث إصدار من 1.x). تذهب طلبات البيانات الخاصة بها إلى Server URL الذي ضبطته، مثل المقتطف. الإعدادات موجودة في Stores → Configuration → Joryio → In-app messages and web push:

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

المتاجر التي تُحدّث من إصدار أقدم تحصل على القيم الافتراضية نفسها. يحمّل مقتطف التتبع حزمة SDK، لذا أبقِ Inject Tracking Snippet مفعّلًا. يسمح الامتداد بـ *.joryio.com في Content Security Policy الخاصة بـ Magento للسكربتات وطلبات API.

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

Web Push. لا يقبل المتصفح service worker الخاص بالإشعارات إلا من عنوان متجرك نفسه. عند تفعيل Web push، يجيب الامتداد على https://your-store/joryio-sw.js (مسار في Magento يغطي المتجر كله)، وهو يحمّل الـ worker المستضاف لدى Joryio. إعدادات nginx وApache القياسية في Magento تمرّر هذا العنوان إلى Magento؛ إذا كان خادمك يقدّم ملفات .js من القرص مباشرة، فأضف إعادة توجيه (rewrite) من /joryio-sw.js إلى /joryio/sw/index. يُطلب من المتسوقين الاشتراك عبر رسالة in-app لطلب الاشتراك في الإشعارات، لذا أبقِ رسائل in-app مفعّلة وفعّل Web Push للتطبيق في Joryio أيضًا. عند إيقاف Web Push يقدّم العنوان نفسه worker يزيل نفسه من متصفحات الزوار.

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

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

يُرسَل اشتراك النشرة الإخبارية في Magento إلى Joryio (الإضافة بالإصدار v1.1.0 أو أحدث) ويُطبَّق على اشتراك البريد الإلكتروني لجهة الاتصال:

في Magento	في Joryio
Subscribed	اشتراك في البريد الإلكتروني. من ألغى اشتراكه يُعاد اشتراكه فقط في الحالات الواردة في ما تفعله موافقة المتجر أو إلغاؤه؛ وإلا فيمكنه إعادة الاشتراك بنفسه من مركز التفضيلات.
Unsubscribed	إلغاء الاشتراك في البريد الإلكتروني - ما لم يسجّل Joryio تغييرًا أحدث لجهة الاتصال.
Not Activated أو Unconfirmed	لا تغيير.

كل طريقة يتغيّر بها الوضع تُحتسب: مربع "Sign Up for Newsletter" في نموذج التسجيل وصفحة الحساب، ولوحة إدارة المتجر، والـ API، ورابط إلغاء الاشتراك في نشراتك. يشترك الاستيراد التاريخي العملاء الذين يعرضهم Magento كمشتركين؛ ولا يلغي اشتراك أحد، لأن API الخاص بـ Magento لا يميّز بين "لم يشترك قط" و"ألغى الاشتراك". يُسجَّل كل تغيير في سجل اشتراك جهة الاتصال (المصدر magento_newsletter) مع مستوى الموافقة (مؤكدة عند تفعيل Need to Confirm في Magento) ووقت تسجيل Magento للتغيير.

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

من يُحتسب فورًا: يُحتسب الاشتراك في النشرة فورًا لمشترٍ معروف (لدى Joryio طلب من جهة الاتصال) أو لمن هو مشترك بالفعل في البريد الإلكتروني أو SMS، وكذلك عندما يؤكده Magento - أي عندما يكون Need to Confirm مفعّلًا وينقر المتسوق رسالة التأكيد من Magento. لا يتحقق Magento من أي عنوان عند التسجيل أو في صفحة الحساب أو في لوحة الإدارة أو عبر الـ API، لذا يبقى أي شخص آخر - بما في ذلك الاستيراد التاريخي - معلّقًا حتى طلبه هو مع تحديد المربع أو نقره على رسالة التأكيد من Joryio، ما لم تختر احتسابه فورًا: راجع موافقات المتسوقين الجدد. يُطبَّق إلغاء الاشتراك فورًا دائمًا.

مربع الموافقة عند الدفع

لا يحتوي Magento على مربع للنشرة الإخبارية عند الدفع. للسؤال هناك، فعّل Stores → Configuration → Joryio → Marketing Consent Checkbox → Show the Checkbox at Checkout. يظهر المربع أسفل طرق الدفع.

الإعداد	الافتراضي	ملاحظات
Show the Checkbox at Checkout	No
Checkbox Text	"Yes, I'd like to receive news and offers by email"	يُسجَّل النص الذي رآه المتسوّق بالضبط مع اختياره.
Ticked by Default	No	غير مستحسن - وفق اللائحة العامة لحماية البيانات (الاتحاد الأوروبي والمملكة المتحدة) لا يُعدّ المربع المحدد مسبقًا موافقة صالحة.
SMS Consent Checkbox	No	مربع ثانٍ للرسائل النصية بنص خاص به. يُسجَّل هاتف الفوترة.

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

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

الإضافة 1.4.14 أو أحدث: Stores → Configuration → Joryio → Marketing Consent Checkbox → When a Shopper Ticks the Checkout Opt-In.

الخيار	ما يحدث
Only when the order is placed (الافتراضي)	يصل الاختيار إلى Joryio مع الطلب. المتسوق الذي يحدّد المربع ثم يغادر لا يُشترك.
Record consent immediately	يصل التحديد إلى Joryio فور قيام المتسوق به، قبل الطلب. يُحتسب المشترون والمشتركون المعروفون فورًا؛ ويُحتسب الضيف الجديد بعد طلبه أو بعد تأكيده عبر البريد الإلكتروني (أدناه). إذا ألغى المتسوق تحديد المربع مرة أخرى في نفس عملية الدفع، يُسحب ذلك التحديد - هو وحده: يبقى أي اشتراك قدّمه في مكان آخر. ويحمل حدث السلة المتروكة أيضًا المربع كما تركه المتسوق.

من يُحتسب فورًا مع Record consent immediately (1.4.16 أو أحدث):

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

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

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

• إرسال رابط تأكيد بالبريد الإلكتروني إلى الضيوف الجدد - معطّل افتراضيًا، لأن العنوان كُتب عند الدفع ولم يتحقق منه أحد بعد. عند التفعيل، يتلقى الضيف الجديد المعلّق رسالة واحدة؛ ورابطها يشركه (المصدر double_opt_in). وتستخدم قالب تأكيد double opt-in إذا اخترت واحدًا.

• تحديدات الموافقة لكل متسوق في الساعة - الافتراضي 3، لكل عنوان IP ولكل عملية دفع ولكل بريد إلكتروني. يتم تجاهل التحديدات التي تتجاوز الحد ولا يحمل حدث السلة المتروكة لتلك العملية أي موافقة؛ ويظل الطلب يسجّل الاختيار. وللامتداد الحد نفسه (Opt-In Ticks per Shopper per Hour، الافتراضي 3) ويوقف مثل هذا التحديد قبل إرساله.

• لا تُحتسب إلا علامة يضعها المتسوق بنفسه، في الخيارين. المربع المعروض محددًا مسبقًا (Ticked by Default) لا يُحتسب إلا بعد أن يتفاعل معه المتسوق: إذا لم يلمسه، فليس موافقة - لا فورًا ولا مع الطلب. إزالة العلامة ثم وضعها مرة أخرى تُحتسب.

• يُرسل كل تغيير مرة واحدة؛ فتح صفحة الدفع أو إعادة تحميلها لا يرسل شيئًا.

• من ألغى اشتراكه لا يُعاد اشتراكه إلا كما هو موضح في ما تفعله موافقة المتجر أو إلغاؤه. إزالة العلامة لا تلغي اشتراك أحد أبدًا - إنها تسحب فقط العلامة التي وُضعت في صفحة الدفع تلك.

• يجب أن يعرف المتجر بريد المتسوق الإلكتروني عند وضع العلامة (يطلبه Magento قبل خطوة الدفع). إن لم يعرفه بعد، ينتقل الاختيار مع السلة المتروكة أو مع الطلب.

صياغة الموافقة واللائحة العامة لحماية البيانات (GDPR)

مع Record consent immediately، يكون التحديد موافقة تسويقية بحد ذاته - غير مرتبط بعملية شراء. اجعل نص المربع يوضح ما يوافق المتسوق على تلقيه وعبر أي قناة (مثل "Yes, I'd like to receive news and offers by email")، واترك المربع غير محدد افتراضيًا ومنفصلًا عن قبول شروطك، واذكره في إشعار الخصوصية. يسجّل Joryio مع كل تحديد النص المعروض والوقت والمتجر وعملية الدفع وعنوان IP الخاص بالمتسوق. يبقى تحديد الضيف الجديد معلّقًا حتى طلبه أو تأكيده، فلا يتلقى أحد تسويقًا لأن شخصًا آخر كتب عنوانه؛ ولا يُرسل بريد التأكيد إلا إذا فعّلته. ويصل تذكير السلة المتروكة عندها إلى المتسوق المشترك كرسالة تسويقية.

معروضة في Joryio، تُضبط في الامتداد

تعرض التكاملات → Magento → الإعدادات إعدادات الموافقة عند الدفع الخاصة بالامتداد في بطاقة Store checkout opt-in (set in your store)، للقراءة فقط: Show the Checkbox at Checkout وTicked by Default وWhen a Shopper Ticks the Checkout Opt-In، مع إصدار الامتداد ووقت آخر إبلاغ عنها. تغييرها يتم في Magento فقط، ضمن Stores → Configuration → Joryio → Marketing Consent Checkbox؛ ولا يغيّرها Joryio أبدًا. تُعرض قيم Default Config - ولا يُعرض store view يتجاوز إحداها. مع Record consent immediately، تعرض البطاقة أيضًا إعدادات Joryio التي تحدد حينها ما يفعله التحديد: Opt-ins from new shoppers وبريد التأكيد والحد في الساعة.

الامتداد بالإصدار 1.4.17 أو أحدث يُبلغ عنها مع كل طلب يرسله إلى Joryio - السلال والسلال المتروكة والطلبات والعملاء والمنتجات وغيرها - ومرة أخرى عند حفظ أحدها. يظهر أي تغيير، مثل إصدار جديد للامتداد بعد التحديث، من الطلب التالي؛ ويُسجَّل الإبلاغ الذي لم يتغير من جديد مرة واحدة في الساعة على الأكثر، لذا قد يكون عمر آخر إبلاغ حتى ساعة. مع امتداد أقدم تعرض البطاقة Not reported yet - update the plugin.

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

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

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

يغطي كل موافقة تصل من دون طلب: الاشتراك في النشرة من نموذج التسجيل وصفحة الحساب ولوحة الإدارة والـ API، والاستيراد التاريخي، ومع Record consent immediately - التحديد عند الدفع أيضًا. وفي الحالتين:

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

هذا ليس الإعداد نفسه When a Shopper Ticks the Checkout Opt-In في الإضافة: ذلك الإعداد يحدد متى يُرسَل التحديد عند الدفع - مع الطلب أو فور حدوثه؛ وهذا الإعداد يحدد ما تفعله الموافقة المبكرة من متسوق جديد. مع Only when the order is placed، يأتي التحديد عند الدفع مع الطلب ويُحتسب دائمًا، لذا يغطي هذا الإعداد موافقات التسجيل والحساب فقط.

ما تفعله موافقة المتجر أو إلغاؤه

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

• الإعداد موجود في التكاملات → Magento → الإعدادات، واحد لكل اتصال متجر، معطّل افتراضيًا. يمكن للمسؤولين فقط تغييره، ويُسجَّل كل تغيير في سجل التدقيق.
• إعادة الاشتراك تخص جهة الاتصال هذه وحدها؛ وتبقى جهات الاتصال الأخرى بالبريد أو الهاتف نفسه غير مشتركة. ويذكر سجل جهة الاتصال السبب، مثل أُعيد الاشتراك عبر صفحة الدفع في المتجر (عميل مسجّل الدخول) بعد إلغاء الاشتراك عبر صفحة التفضيلات.
• SMS: عند تفعيل التأكيد المزدوج (double opt-in) لـ SMS، ترسل إعادة الاشتراك رسالة واحدة "رد بـ YES" وتبقى جهة الاتصال قيد الانتظار حتى ترد. ولا تعود جهة اتصال أرسلت STOP إلا بهذه الطريقة - وعند إيقاف التأكيد المزدوج لـ SMS لا تعيد موافقة المتجر اشتراكها أبدًا.
• موافقة المتجر تشترك في القناة لا في قائمة: القائمة التي تتطلب التأكيد المزدوج ترسل رسالة التأكيد عند انضمام الشخص إليها.

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

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

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

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

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

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

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

تعرض Stores → Configuration → Joryio → Event Queue عدد الأحداث المنتظرة وقيد إعادة المحاولة وغير المسلَّمة، وآخر خطأ، وآخر تسليم ناجح. يعيد Retry now إرسال كل حدث منتظر أو غير مسلَّم. ابتداءً من الإصدار 1.4.4، يُنهي حفظ Server URL أو API key جديد، أو Connect ناجح، أو Test Connection ناجح التوقف فورًا: تُرسل الأحداث المنتظرة في التشغيل التالي (خلال دقيقة) ويُمسح الخطأ القديم.

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

• قطع الاتصال في لوحة إدارة Magento ينهي الاتصال: يتوقف Joryio عن المزامنة، ويُلغى رمز الوصول لتكامل "Joryio" في Magento، وتُحفظ الأحداث المنتظرة جانبًا (بعد إعادة الاتصال يرسلها Retry now). يبقى مفتاح API صالحًا - انقر Connect مجددًا بالمفتاح نفسه (الامتداد v1.4.3 أو أحدث؛ الإصدارات الأقدم كانت تُبطله).
• قطع الاتصال في Joryio (الإعدادات → التكاملات → Magento) يُبطل مفتاح API فورًا: في المرة التالية التي يرسل فيها الامتداد حدثًا يتوقف ويعرض تنبيهًا. الاتصال بهذا المفتاح يعرض عندها «This key was revoked when the store was disconnected in Joryio»، وتشرح صفحة Magento في Joryio سبب عدم وجود مفتاح. أنشئ مفتاحًا جديدًا للاتصال مجددًا. لإلغاء رمز وصول Magento أيضًا، انقر Disconnect في لوحة إدارة Magento.
• متجر واحد، مساحة عمل واحدة. لا يمكن ربط متجر مرتبط بمساحة عمل في Joryio بمساحة عمل أخرى: يعرض الربط «This store is already connected to another Joryio workspace.» اقطع اتصاله أولًا في مساحة العمل الأخرى.
• إلغاء التثبيت باستخدام bin/magento module:uninstall Joryio_Connect (عند التثبيت عبر composer) أو bin/magento module:uninstall --non-composer Joryio_Connect (عند التثبيت في app/code). يقطع اتصال المتجر، ويُبطل مفتاح API (v1.4.3 أو أحدث)، ويحذف تكامل "Joryio" ويزيل جداول الامتداد وإعداداته. حذف الملفات دون module:uninstall لا يفعل شيئًا من ذلك - انقر Disconnect أولًا.

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

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

ما يفعله رابط الاسترداد (https://your-store.com/joryio/cart/restore?token=...) يعتمد على من يفتحه (الإضافة v1.4.8 أو أحدث). يحتفظ Magento بسلة حساب العميل فقط ما دام ذلك العميل مسجّل الدخول، لذلك:

• العميل نفسه، مسجّل الدخول - تعود سلته المحفوظة.
• لا أحد مسجّل الدخول (الحالة المعتادة: فُتح الرابط من بريد على جهاز آخر) - تُنسخ المنتجات، بخياراتها وكمياتها ورمز الخصم إن كان لا يزال صالحًا، إلى سلة في هذا المتصفح، مع الملاحظة "Sign in to use your saved details at checkout." عند تسجيل الدخول بعد ذلك تبقى سلة واحدة؛ ولا تتضاعف الكميات أبدًا.
• سلة زائر - تُنسخ المنتجات أيضًا، دون اسم الزائر وبريده وعناوينه، فلا يكشف الرابط المُعاد توجيهه بيانات أحد.
• عميل آخر مسجّل الدخول - يُرفض بالرسالة "This cart belongs to a different account. Sign out to open it as a guest." لا يُضاف شيء إلى سلته ولا يُذكر اسم أحد.
• عميل مسجّل الدخول يفتح سلة زائر، أو في سلة هذا المتصفح منتجات بالفعل - تسأل صفحة "Add these products from your saved cart to your current cart?"؛ لا يُضاف شيء حتى النقر على Add to my cart.
• السلة طُلبت بالفعل - "You already completed this order."
• فُتح الرابط مرة أخرى - يذهب المتصفح نفسه إلى السلة التي لديه؛ ويحصل متصفح أو جهاز آخر على سلة جديدة بالمنتجات المحفوظة (أدناه). سلة العميل التي انتقلت إليه عند تسجيل الدخول تعرض "This link was already used - sign in to see your cart."

لا يغيّر الرابط أبدًا سلة قائمة لشخص آخر: إذا حمّله موقع آخر كصورة أو إطار فلا يفعل شيئًا، والإضافة إلى سلة قائمة تتطلب التأكيد دائمًا. إذا أُرسل التأكيد بعد انتهاء جلسة الصفحة، يرى المتسوّق "Your session has expired. Please open the cart link again." ولا يتغيّر شيء.

لا يُفتح الرابط إلا في عرض المتجر (store view) الذي حُفظت فيه السلة (الإضافة v1.4.10 أو أحدث): في عرض متجر آخر للمتجر نفسه يعرض "This cart was saved in another of our stores. Please open the link from your email again." ولا يغيّر شيئًا. تظل الروابط المرسلة من v1.4.9 وما قبلها تعمل، مع الفحص نفسه، حتى 31 يناير 2027.

لا تظهر "Your cart has been restored." إلا عندما تعرض صفحة السلة المنتجات. المنتجات التي لم يعد شراؤها ممكنًا تُستبعد ويُذكر اسمها. يُحتسب الطلب المُنشأ من سلة منسوخة في Joryio استردادًا لتلك السلة، حتى لو أتمّ المتسوّق الشراء كزائر ببريد آخر.

كانت الإضافة v1.4.7 وما قبلها تعرض "Your cart has been restored." فوق سلة فارغة عندما لا يكون العميل مسجّل الدخول - حدّث إلى v1.4.8.

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

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

• فتح الرابط يعرض صفحة قصيرة، "Restoring your saved cart..."، لا تُخزَّن مؤقتاً ولا تُفهرس أبداً. يستعيد السكربت فيها السلة ثم ينتقل إلى صفحة السلة؛ ومن دون سكربت ينقر المتسوق Restore my cart. المعاينة أو الماسح الذي لا يشغّل السكربت لا يستعيد شيئاً. وتبقى صفحة التأكيد أعلاه بانتظار نقرة المتسوق.
• سلة واحدة لكل رابط، في كل متصفح - تُحفظ السلة التي استعادها الرابط مع المتصفح الذي استُعيدت فيه (ملف تعريف ارتباط). فتح الرابط نفسه مرة أخرى في ذلك المتصفح (مثلاً بعد انتهاء جلسته) يعيد السلة نفسها بدلاً من نسخة جديدة، لمدة 7 أيام: Stores > Configuration > Joryio > Tracking > Recovery Link Reuses Its Cart For (days)، من 1 إلى 30. أما المتصفح أو الجهاز الآخر - أو الماسح الذي شغّل الصفحة فعلاً - فلا يحصل على تلك السلة أبداً: يحصل على سلة جديدة فيها منتجات السلة المحفوظة ورمز الخصم فقط، فلا يظهر أي شيء كتبه أحد عند الدفع في متصفح ما في متصفح آخر. بعد ذلك يتذكر الرابط سلة أحدث متصفح. تظل السلتان محسوبتين على أنهما السلة المحفوظة نفسها: الطلب من أي منهما استرداد واحد، ولا يُرسل إلا تذكير واحد بأن السلة "تُركت مرة أخرى" لكل سلة أصلية.
• تم الطلب بالفعل - عندما تصبح السلة التي استعادها الرابط طلباً، يعرض الرابط "You already completed this order." ولا يستعيد شيئاً.
• 10 عمليات استعادة كحد أقصى لكل رابط في الساعة - بعدها، "Too many attempts with this cart link. Please try again later."

النسخ التي أنشأتها الإصدارات السابقة بالفعل لا تزال تحصل على تذكير واحد كحد أقصى لكل سلة أصلية (سلة مستعادة تُركت مرة أخرى). كما يزيل bin/magento setup:upgrade إلى 1.4.18 العلامات المتبقية على السلال المستعادة التي طُلبت بالفعل ويكمل سلتها الأصلية؛ وتُكتب الأعداد في var/log/joryio.log.

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

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

سلة مستعادة تُركت مرة أخرى

بدءاً من الإضافة 1.4.13، لا تضع استعادة السلة أي علامة ترك. النسخة المستعادة التي يتركها المتسوق مرة أخرى يُبلَّغ عنها مرة واحدة أخرى بعد وقت الترك المعتاد، مع reabandonedAfterRecovery: true وoriginalSessionId في حدث Cart Abandoned؛ وأي نسخة خاملة أخرى من السلة الأصلية نفسها خلال 30 يوماً لا يُبلَّغ عنها. السلة التي كانت فيها منتجات واستقبلت المنتجات المحفوظة سلة عادية. الطلب من أي نسخة يُحتسب استعادة واحدة للسلة الأصلية. راجع السلال.

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

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

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

كانت الإصدارات 1.4.8 إلى 1.4.12 تضع على السلة المستعادة علامة "تم الإبلاغ" لحظة استعادتها، فلا يتلقى المتسوق الذي تركها مرة أخرى أي تذكير. يزيل bin/magento setup:upgrade إلى 1.4.13 هذه العلامات (فقط تلك التي وُضعت لحظة الاستعادة دون حدث ترك وراءها) ويكتب الأعداد في var/log/joryio.log.

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

أحداث عالقة / لا يصل شيء إلى Joryio

السبب في أغلب الحالات هو عدم تشغيل Magento cron. يضع الامتداد الأحداث محليًا في طابور ويسلمها cron كل دقيقة؛ ومن دون cron لا يُرسل شيء.

• تحقق من إعداد cron: bin/magento cron:install (أو افحص crontab).
• شغله يدويًا للاختبار: bin/magento cron:run.
• افحص var/log/joryio.log في جذر Magento بحثًا عن أخطاء التسليم.
• افحص Stores → Configuration → Joryio → Event Queue (الامتداد v1.4.0 أو أحدث): يعرض الأحداث المنتظرة وتلك التي لم تُسلَّم، مع آخر خطأ. راجع التسليم وإعادة المحاولة.

فشل الاتصال

ابتداءً من الإصدار 1.4.2 للامتداد، يختبر Connect أولًا رمز الوصول الجديد على متجرك كما ستفحصه واجهة REST API في Magento: إعداد Bearer الخاص بـ OAuth لعرض المتجر الذي يستدعيه Joryio، وفحص Magento نفسه للرمز، وصلاحيات تكامل "Joryio"، وطلبًا من خادمك إلى عنوان URL لمتجره. عندما يفشل أحدها يتوقف Connect قبل إشراك Joryio ويذكر السبب؛ ولا يبقى شيء خلفه. تُكتب النتيجة أيضًا في var/log/joryio.log (السطر الذي يبدأ بـ Joryio connect self-test). بجانب الأزرار، تعرض صفحة الإعدادات ما إذا كان إعداد Bearer مفعّلًا بالفعل.

تقول الرسالة	ما العمل
الإعداد "Allow OAuth Access Tokens to be used as standalone Bearer tokens" على No لعرض المتجر الذي يستدعيه Joryio	اضبطه على Yes - وافحص أيضًا مستويي الموقع وعرض المتجر، فالقيمة هناك تتقدم على Default Config. راجع السماح برموز وصول OAuth كرموز Bearer
تنقص تكامل "Joryio" هذه الصلاحيات	شغّل bin/magento setup:upgrade وbin/magento cache:flush ثم انقر Connect مجددًا. تحقق في System → Extensions → Integrations → Joryio → API من تحديد الموارد المذكورة
يجيب على عنوان URL لمتجرك تثبيت Magento آخر	عنوان URL الأساسي في Stores → Configuration → General → Web يشير إلى نسخة أخرى من المتجر (مثل staging). أصلحه ثم اتصل
خادم الويب يزيل ترويسة Authorization	راجع «ترويسة Authorization تُزال» أدناه
رُفض طلب بالرمز الجديد إلى rest/V1/store/storeConfigs	وحدة أمان أو جدار حماية أو قاعدة في خادم الويب أمام REST API في Magento ترفضه. اسمح بطلبات /rest/ مع ترويسة Authorization
يقبل المتجر الرمز من خادمه، لكنه رفضه عندما اتصل Joryio	شيء أمام المتجر يعامل الطلبات القادمة من الخارج بشكل مختلف (جدار حماية، CDN، WAF، حماية من الروبوتات). اسمح بمرور طلبات /rest/ مع ترويسة Authorization
حدّث امتداد Joryio Connect إلى 1.4.2 أو أحدث	امتدادك أقدم. حدّثه (أدناه) وانقر Connect مجددًا
تعذّر على Joryio الوصول إلى متجرك	يجب أن يكون عنوان URL للمتجر عامًا ويعمل، مع شهادة HTTPS صالحة. تُرفض العناوين الخاصة والداخلية
This store is already connected to another Joryio workspace	اقطع اتصاله أولًا في مساحة العمل الأخرى - راجع قطع الاتصال وإلغاء التثبيت
مفتاح API غير صالح	انسخ مفتاح API وعنوان URL للخادم مجددًا من الإعدادات → التكاملات → Magento في Joryio. لا يعرف المفتاحَ إلا خادمُ منطقته

ترويسة Authorization تُزال. لا يبلّغ Connect عن ذلك إلا عندما يصل طلبه هو إلى متجرك من دون الترويسة. غالبًا ما يزيلها Apache الذي يشغّل PHP كـ CGI أو FastCGI. ملف .htaccess الخاص بـ Magento نفسه يمررها؛ إذا استُبدل ملفك أو تجاهله مزوّد الاستضافة، فأضف ما يلي إلى .htaccess في المجلد الجذر لـ Magento (وفي pub/ إذا كان هو جذر الموقع):

RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

الترقية إلى 1.4.2: استبدل ملفات الامتداد بملف zip للإصدار v1.4.2 من لوحة تحكم Joryio، ثم شغّل bin/magento setup:upgrade وbin/magento setup:di:compile (في وضع production) وbin/magento cache:flush. كان الإصداران 1.4.0 و1.4.1 يُفقدان تكامل "Joryio" صلاحياته في كل مرة يفعّلانه فيها أو يوقفانه؛ يعيدها setup:upgrade، ويعيد Connect استخدام التكامل الموجود ويصدر رمزًا جديدًا ويفعّله - لا حاجة إلى حذفه. في Stores → Configuration → Joryio تحقق من Server URL، وانقر Save Config ثم Connect.

الترقية إلى 1.4.4

استبدل ملفات الامتداد بملف zip للإصدار v1.4.4 من لوحة تحكم Joryio، ثم شغّل bin/magento setup:upgrade وbin/magento setup:di:compile (في وضع production) وbin/magento cache:flush. يتيح setup:upgrade لتكامل "Joryio" قراءة الفئات والمخزون (بما في ذلك مصادر MSI عندما يستخدمها المتجر) - لا حاجة إلى الربط من جديد. بعد ذلك، افتح في Joryio الإعدادات → التكاملات → Magento وانقر مزامنة الكل: تدمج المزامنة المنتجات الفرعية في منتجاتها القابلة للتهيئة وتُكمل المخزون والفئات ومبالغ القسائم لما سبقت مزامنته.

«مفتاح API غير صالح» / عدم تطابق المفتاح

• يجب أن يبدأ المفتاح بـ jry_mg_ وأن يطابق المفتاح الظاهر حاليًا في الإعدادات → التكاملات → Magento في Joryio.
• فتح صفحة الإعداد في Joryio مجددًا لا يغيّر المفتاح - قطع الاتصال وحده يُبطله. إذا اختلف المفتاح في Magento عن الظاهر في Joryio، فالصق الظاهر في Joryio وانقر Connect مجددًا.
• تحقق مرة أخرى من نسخ عنوان URL للخادم حرفيًا.
• قطع الاتصال في لوحة إدارة Magento يحتفظ بالمفتاح (v1.4.3 أو أحدث): انقر Connect مجددًا به. قطع الاتصال في Joryio أو إلغاء تثبيت الامتداد يُبطله - ويذكر الاتصال ذلك؛ أنشئ مفتاحًا جديدًا في الإعدادات → التكاملات → Magento والصقه قبل أن تنقر Connect مجددًا. إذا ظهرت رسالة «This store is already connected to another Joryio workspace» فاقطع اتصاله أولًا في مساحة العمل الأخرى - راجع قطع الاتصال وإلغاء التثبيت.

بيانات تاريخية مفقودة

• لا تُستورد الطلبات الأقدم من نافذة المزامنة (90 يومًا افتراضيًا).
• تعمل المزامنة التاريخية بالترتيب: المنتجات ثم العملاء ثم الطلبات؛ امنح المتجر الكبير وقتًا لإتمامها.

التتبع لا يعمل

• تحقق من تفعيل مفتاح مقتطف التتبع في Stores → Configuration → Joryio.
• يمسح الامتداد 1.4.6 أو أحدث الصفحات المخزنة بنفسه عند حفظ المفتاح؛ مع إصدار أقدم شغّل bin/magento cache:flush (راجع بعد تغيير الإعدادات).
• تحقق من تحميل المقتطف في أدوات مطور المتصفح.

الإضافة إلى السلة مفقودة، والتخزين المؤقت الكامل للصفحات و Varnish

• لا مشكلة مع التخزين المؤقت الكامل للصفحات و Varnish: يحمل المقتطف بيانات الصفحة فقط، وتصل الإضافة إلى السلة إلى المتصفح عبر بيانات العميل الخاصة بـ Magento نفسه (customer/section/load)، التي لا تُخزَّن مؤقتًا أبدًا. لا تضف قاعدة تخزّن هذا العنوان مؤقتًا
• السمات المبنية على Luma و Hyva مدعومة. واجهة headless أو PWA لا تحمّل المقتطف، فأرسل الأحداث باستخدام Web SDK بدلًا من ذلك
• بعد ترقية الامتداد شغّل bin/magento setup:upgrade و bin/magento cache:flush حتى يُسجَّل قسم بيانات العميل الجديد

صفحة الدفع عالقة على مؤشر التحميل، "Mismatched anonymous define()"

• مع الإصدار 1.4.6 من الامتداد، كانت صفحة الدفع في متجر مبني على Luma قد تبقى على مؤشر التحميل حتى إعادة تحميل الصفحة. وظهر في وحدة تحكم المتصفح Mismatched anonymous define() module (من ملف Joryio web SDK) وtemplateEngine must inherit from ko.templateEngine. كان المقتطف يحمّل web SDK بوسم script عادي، وفي صفحة تستخدم RequireJS سجّل ملف SDK نفسه بطريقة نسبها RequireJS إلى إحدى وحدات الدفع الخاصة بـ Magento نفسه
• يحمّل الإصدار 1.4.7 من الامتداد web SDK عبر RequireJS متى وُجد في الصفحة (Luma والسمات المبنية عليه)، وبوسم script عادي فقط حيث لا يوجد (Hyva). قم بالترقية، ثم شغّل bin/magento setup:upgrade وbin/magento setup:static-content:deploy في وضع production وbin/magento cache:flush
• للتحقق: افتح صفحة الدفع ووحدة التحكم مفتوحة - لا تظهر أي من الرسالتين، ويوجد window.joryio.sdk بعد تحميل الصفحة (عند تفعيل رسائل in-app أو Web Push)

سلات الزوار لا تُعلَّم كمتروكة

• يحتفظ Magento بالبريد الإلكتروني للزائر على عنوان الفوترة (أو الشحن) الخاص بالسلة أثناء وجوده في صفحة الدفع، ولا ينسخه إلى السلة نفسها إلا عند تقديم الطلب. كان الإصدار 1.4.6 وما قبله من الامتداد ينظر إلى السلة نفسها فقط، لذلك لم يُعلَّم الزائر الذي أدخل بريده في صفحة الدفع ثم غادر كسلة متروكة أبدًا. بدءًا من 1.4.7 يُحتسب أيضًا البريد الموجود على عنوان الفوترة أو الشحن (أبقِ Track Guest Carts مفعّلًا)
• تُحتسب سلات الزوار من لحظة تثبيت الإصدار 1.4.9 من الامتداد (يسجّلها bin/magento setup:upgrade)؛ ولا تُرسَل سلات الزوار التي بقيت دون تغيير قبل ذلك دفعة واحدة. مع الإصدارين 1.4.7 و1.4.8 لم تُبلَّغ أي سلة زائر عبر البريد الموجود على العنوان (لم يكن وقت البدء يُحفظ) - قم بالترقية إلى 1.4.9. للاختبار: ابدأ عملية دفع جديدة كزائر، وأدخل بريدًا، وغادر، وانتظر مدة الترك مضافًا إليها حتى 15 دقيقة (فاصل cron)
• تُعلَّم السلة كمتروكة مرة واحدة. المتسوّق الذي لم يكتب بريدًا (وليس مسجّل الدخول) لا يمكن الوصول إليه ولا يُرسَل
• بدءًا من 1.4.11 يعرض var/log/joryio.log ذلك: Joryio: guest-cart start time set to <date> UTC (...) (أو already set (<date> UTC), kept.) عند setup:upgrade، وJoryio: cart abandon queued: quote <id>, store <id>. لكل رابط استرداد يُنشأ (معرّفات فقط - دون بريد أو رابط أو رمز)

حظر الإضافة إلى السلة أو التتبع بواسطة حماية البوتات

قد تحظر بعض أدوات الأمان لدى الاستضافة - مثل حماية البوتات في Imunify360 - طلبات المتجر نفسه (الإضافة إلى السلة، ونداءات التتبع) مع الرسالة "Access denied by Imunify360 bot-protection". عندها لا يتلقى Joryio أحداث الإضافة إلى السلة أو عرض الصفحات، وقد يرى المتسوّقون فشل الإضافة إلى السلة. في لوحة تحكم الاستضافة، اسمح بمسارات AJAX الخاصة بالمتجر ومسارات Joryio (/joryio/...، /customer/section/load، /checkout/cart/add)، أو خفّض حساسية حماية البوتات لنطاق المتجر. يمكن لمزوّد الاستضافة إخبارك بالقاعدة التي طُبّقت.