المشاكل الشائعة والأخطاء في إعداد التقارير

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

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

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

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

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

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

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

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

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

في Chrome وFCM

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

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

  • في حال عدم تحديد عنوان Authorization في الطلب المُرسَل إلى FCM
  • لا يتطابق مفتاح التطبيق المستخدَم للاشتراك مع المفتاح المستخدَم لتوقيع عنوان التفويض.
  • تاريخ انتهاء الصلاحية غير صالح في رمز 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 لمعرفة ما إذا كان رمز الحالة مذكورًا مع سيناريو يوضّح الحالات التي يمكن فيها استخدام رمز الحالة هذا.

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

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

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

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

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

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

سجلّات Chrome GCM الداخلية

  1. أرسِل رسالة فورية، وابحث ضمن "سجلّ تعذُّر فك تشفير الرسائل".

سجلّ فك تشفير GCM internals

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

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

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

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

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

سجلّ الرسائل الواردة في GCM

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

حالة اتصال GCM internals

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

الإبلاغ عن تقارير الأخطاء

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

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

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

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

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

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

Code labs