المشاكل الشائعة والأخطاء المتعلقة بالإبلاغ

عند مواجهة مشكلة في إرسال الإشعارات الفورية على الويب، قد يكون من الصعب تصحيح أخطاء المشكلة أو الحصول على مساعدة. يوضّح هذا المستند بعض المشاكل الشائعة والإجراءات التي يجب اتّخاذها في حال رصد خطأ في Chrome أو Firefox.

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

هناك مرحلتان مختلفتان يجب التحقّق منهما عند تطوير إشعارات الدفع على الويب واختبارها، لكل منهما مجموعة من المشاكل الشائعة:

  • إرسال رسالة: تأكَّد من إرسال الرسائل بنجاح. من المفترض أن يظهر لك رمز HTTP‏ 201. إذا لم تكن :
    • التحقّق من أخطاء التفويض: إذا ظهرت لك رسالة خطأ تتعلّق بالتفويض، يُرجى الاطّلاع على قسم "مشاكل التفويض".
    • أخطاء أخرى في واجهة برمجة التطبيقات: إذا تلقّيت استجابة برمز حالة غير 201، راجِع قسم رموز حالة HTTP للحصول على إرشادات حول سبب المشكلة.
  • تلقّي رسالة: إذا كان بإمكانك إرسال رسالة بنجاح، ولكن لم يتم استلام الرسالة على المتصفّح:

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

قبل البدء، أودّ الإشارة إلى أنّ Firefox و Mozilla AutoPush Service يتضمّنان رسائل خطأ رائعة. إذا واجهت مشكلة ولم تكن متأكّدًا من سببها، يمكنك اختبار الإجراء في Firefox لمعرفة ما إذا كانت ظهرت رسالة خطأ أكثر فائدة.

مشاكل التفويض

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

إنّ أسهل طريقة لتفعيل ميزة "الدفع" في كلّ من Firefox وChrome هي توفير applicationServerKey في طلب subscribe(). الجانب السلبي هو أنّ أي تناقض بين مفاتيح الواجهة الأمامية والخادم سيؤدي إلى خطأ في التفويض.

على Chrome و‏FCM

بالنسبة إلى Chrome الذي يستخدم خدمة المراسلة عبر السحابة الإلكترونية من Firebase (FCM) كخدمة دفع، ستتلقّى UnauthorizedRegistration استجابة من FCM لمجموعة من الأخطاء المختلفة، وكلها تتعلّق بمفاتيح خادم التطبيق.

سيظهر لك خطأ UnauthorizedRegistration في أيّ من الحالات التالية:

  • إذا تعذّر عليك تحديد عنوان Authorization في الطلب المُرسَل إلى خدمة "إشعارات Google من خادم Firebase"
  • لا يتطابق مفتاح تطبيقك المستخدَم لإشتراك المستخدم مع المفتاح المستخدَم لتوقيع رأس Authorization.
  • تاريخ انتهاء الصلاحية غير صالح في رمز JWT، أي أنّ تاريخ انتهاء الصلاحية يتجاوز 24 ساعة أو انتهت صلاحية رمز JWT.
  • تم تنسيق رمز JWT بشكل غير صحيح أو يحتوي على قيم غير صالحة.

يظهر ردّ الخطأ الكامل على النحو التالي:

<html>
 
<head>
   
<title>UnauthorizedRegistration</title>
 
</head>
 
<body bgcolor="#FFFFFF" text="#000000">
   
<h1>UnauthorizedRegistration</h1>

   
<h2>Error 400</h2>
 
</body>
</html>

إذا ظهرت لك رسالة الخطأ هذه في Chrome، ننصحك بتجربة Firefox لمعرفة ما إذا كان سيقدّم المزيد من الإحصاءات حول المشكلة.

Firefox وMozilla AutoPush

يقدّم Firefox وMozilla AutoPush مجموعة من رسائل الخطأ الواضحة بشأن مشاكل Authorization.

سيصلك أيضًا استجابة خطأ Unauthorized من Mozilla AutoPush في حال عدم تضمين العنوان Authorization في طلب إعلام العميل.

{
 
"errno": 109,
 
"message": "Request did not validate missing authorization header",
 
"code": 401,
 
"more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
 
"error": "Unauthorized"
}

إذا انتهت صلاحية JWT، ستتلقّى أيضًا خطأ Unauthorized مع رسالة توضّح أنّ الرمز المميَّز انتهت صلاحيته.

{
 
"code": 401,
 
"errno": 109,
 
"error": "Unauthorized",
 
"more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
 
"message": "Request did not validate Invalid bearer token: Auth expired"
}

إذا اختلفت مفاتيح خادم التطبيق بين وقت اشتراك المستخدم ووقت توقيع عنوان التفويض، سيتم عرض Not Found خطأ:

{
 
"errno": 102,
 
"message": "Request did not validate invalid token",
 
"code": 404,
 
"more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
 
"error": "Not Found"
}

أخيرًا، إذا كانت لديك قيمة غير صالحة في JWT (على سبيل المثال، إذا كانت قيمة "alg" هي قيمة غير متوقّعة)، ستتلقّى الخطأ التالي من Mozilla AutoPush:

{
 
"code": 401,
 
"errno": 109,
 
"error": "Unauthorized",
 
"more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
 
"message": "Request did not validate Invalid Authorization Header"
}

رموز حالة HTTP

هناك مجموعة من المشاكل التي يمكن أن تؤدي إلى ظهور رمز استجابة غير 201 من خدمة الإرسال الفوري. في ما يلي قائمة برموز حالة HTTP ومعنى كل منها في ما يتعلّق بإشعارات الدفع على الويب.

رمز الحالة الوصف
429 عدد الطلبات كبير جدًا. وصل خادم التطبيقات إلى الحد الأقصى لمعدّل مع خدمة الإرسال الفوري. يجب أن يتضمّن الردّ من الخدمة رأس Retry-After لتحديد المدة التي يمكن خلالها تقديم طلب آخر.
400 الطلب غير صالح. أحد العناوين غير صالح أو معدّ بتنسيق غير سليم.
404 غير موجودة في هذه الحالة، عليك حذف PushSubscription من الخلفية والانتظار إلى أن تتوفر فرصة لإعادة اشتراك المستخدم.
410 تمّت إزالة المحتوى. لم يعُد الاشتراك صالحًا ويجب إزالته من الجانب الخلفي. يمكن إعادة إنتاج هذا الخطأ عن طريق استدعاء unsubscribe()‎ على PushSubscription‎.
413 حجم الحمولة كبير جدًا. الحد الأدنى لحجم الحمولة التي يجب أن تسمح بها خدمة الإرسال الفوري هو 4096 بايت (أو 4 كيلوبايت). ويمكن أن يؤدي أي حجم أكبر إلى ظهور هذا الخطأ.

إذا لم يكن رمز حالة HTTP مُدرَجًا في هذه القائمة ولم تكن رسالة الخطأ مفيدة، اطّلِع على مواصفات بروتوكول Web Push Protocol لمعرفة ما إذا كان يتم الإشارة إلى رمز الحالة مع سيناريو يوضّح حالات استخدام رمز الحالة هذا.

مشكلة في تشفير الحمولة

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

في هذه الحالة، من المفترض أن تظهر لك رسالة خطأ فيconsole DevTools في Firefox على النحو التالي:

أدوات مطوّري البرامج في Firefox مع رسالة فك التشفير

للتحقّق مما إذا كانت هذه هي المشكلة في Chrome، اتّبِع الخطوات التالية:

  1. انتقِل إلى about://gcm-internals وانقر على زر "بدء التسجيل".

سجلّ وظائف GCM الداخلية في Chrome

  1. شغِّل رسالة فورية، وابحث ضمن "سجلّ أخطاء فك تشفير الرسائل".

سجلّ فك تشفير العناصر الداخلية في GCM

في حال حدوث مشكلة في فك تشفير الحمولة، سيظهر لك خطأ يشبه الخطأ المعروض أعلاه. (لاحظ الرسالة AES-GCM decryption failed في عمود التفاصيل).

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

مشكلة في الاتصال

إذا لم تتلقّ حدث دفع في Worker الخدمة ولم يكن هناك أي أخطاء في فك التشفير، قد يتعذّر على المتصفّح الاتصال بخدمة دفع.

في Chrome، يمكنك التحقّق مما إذا كان المتصفّح يتلقّى الرسائل من خلال فحص "سجلّ تلقّي الرسائل" في about://gcm-internals.

تتلقّى العناصر الداخلية لخدمة GCM سجلّ الرسائل.

إذا لم تصلك الرسالة في الوقت المناسب، تأكَّد من أنّ حالة اتصال المتصفّح هي CONNECTED:

حالة الاتصال في الوظائف الداخلية لخدمة GCM

إذا كان غير "مرتبط"، قد تحتاج إلى حذف ملفك التجاري الحالي وإنشاء ملف جديد. إذا استمرت المشكلة، يُرجى إرسال تقرير خطأ كما هو مقترَح أدناه.

الإبلاغ عن الأخطاء

إذا لم تساعدك أي من الخطوات السابقة في حلّ مشكلتك ولم تظهر أي إشارة على سبب هذه المشكلة، يُرجى إبلاغنا بالمشكلة في المتصفّح الذي تواجه فيه مشكلة:

بالنسبة إلى Chrome، يمكنك إبلاغنا بالمشكلة على الرابط التالي: https://bugs.chromium.org/p/chromium/issues/list بالنسبة إلى Firefox، عليك إبلاغنا بالمشكلة على الرابط التالي: https://bugzilla.mozilla.org/

لتقديم تقرير جيد عن الخطأ، يجب تقديم التفاصيل التالية:

  • المتصفحات التي تم اختبارها (مثل الإصدار 50 من Chrome والإصدار 51 من Chrome والإصدار 50 من Firefox والإصدار 51 من Firefox)
  • مثال PushSubscription يوضّح المشكلة
  • أدرِج أي أمثلة على الطلبات (أي محتوى طلبات الشبكة إلى خدمة إعلام فوري، بما في ذلك العناوين).
  • أدرِج أيضًا أي أمثلة على الردود الواردة من طلبات الشبكة.

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

الخطوات التالية

الدروس التطبيقية حول الترميز