الحوسبة السحابية وبدائلها الأدلة التقنية

UnifiedPush: إشعارات Android دون Google

كيف يصل إشعار تطبيقك إلى هاتف Android عبر موزع وسيرفر تختارهما أنت، بتجربة على هاتف حقيقي مع ntfy وما الذي يوقف الإشعارات في الخلفية.

UnifiedPush: إشعارات Android دون Google

إذا كان عندك تطبيق Android لموظفين ميدانيين على أجهزة تديرها مؤسستك، أو تطبيق محادثة يستخدمه أشخاص اختاروا هواتف دون خدمات Google، أو أردت ببساطة أن يصل إشعار تطبيقك من سيرفرك إلى الهاتف دون أن يمر على حساب عند أحد، فالطريق المعتاد مغلق: Firebase Cloud Messaging واختصاراً FCM يعمل فقط حيث توجد خدمات Google Play، ويمر فيه كل إشعار عبر Google. وفي مقال إشعارات Push بدون Firebase عرفنا أن UnifiedPush هو الطريق إلى Android دون Google، وجربنا الجزء الذي على السيرفر بسكربت يمثل الهاتف، أما في هذا المقال فالهاتف حقيقي: Android 15 في المحاكي Emulator، عليه تطبيق ntfy موزعاً Distributor، وتطبيق مثال من مشروع UnifiedPush نفسه فيه مكتبة الموصل Connector Library، والرسالة تخرج من سيرفرنا بتشفير كتبناه بأيدينا وتظهر في شريط الإشعارات. وهذا يكشف ما لا يكشفه أي سكربت: قيود Android على العمل في الخلفية، ومن يوقظ من، وما الذي يحدث عندما يتوقف شيء في الطريق.

وسوف نناقش في هذا المقال ما يلي:

  • الأطراف الأربعة في UnifiedPush، ولماذا يحتاج Android إلى تطبيق موزع واحد بدل أن يحمل كل تطبيق اتصاله.
  • مواصفة Android بالأسماء التي ستراها في السجلات Logs: REGISTER وNEW_ENDPOINT وMESSAGE ورفاقها.
  • مكتبة الموصل الرسمية والكلاس PushService كما يكتبها تطبيقك.
  • مختبر كامل: سيرفر ntfy خاص، وتطبيق ntfy على الهاتف، وتطبيق UP-Example، والإرسال من سيرفر تطبيق بالمعيار Web Push.
  • ما الذي أوقف الإشعارات في المختبر وكيف حللناه، وماذا يحدث في وضع Doze وعند إيقاف التطبيق بالقوة وعند رسالة أكبر من 4096 بايت.
  • موزع FCM المضمن Embedded FCM Distributor للمستخدمين الذين لا موزع عندهم، والتطبيقات التي تدعم UnifiedPush اليوم.

لماذا يحتاج Android إلى موزع؟ Why a Distributor

الإشعار الفوري Push Notification يحتاج اتصالاً مفتوحاً دائماً من الهاتف إلى سيرفر ما، فإذا أغلق التطبيق يجب أن يبقى أحد ما يستمع. ونظام Android منذ الإصدار 6 يقيد هذا بشدة بوضع Doze وقيود البطارية التي شرحناها في دورة حياة تطبيق الجوال، والاستثناء الوحيد المريح هو خدمات Google Play، التي تحمل اتصالاً واحداً معفى من القيود لكل التطبيقات على الهاتف، وهذا هو FCM. وأي تطبيق آخر يريد اتصالاً دائماً يجب أن يعمل كخدمة في المقدمة Foreground Service، أي أن يظهر للمستخدم إشعار دائم يقول إن التطبيق يعمل، ولو فعل ذلك كل تطبيق لامتلأ شريط الإشعارات وفرغت البطارية.

وفكرة UnifiedPush أن يتكرر ما تفعله خدمات Google Play، لكن باختيار المستخدم: تطبيق واحد على الهاتف اسمه الموزع Distributor يحمل اتصالاً دائماً واحداً بسيرفر إشعارات Push Server يختاره المستخدم أو مؤسسته، وكل التطبيقات التي تدعم UnifiedPush تستقبل عبره. والصورة التالية تبين الأطراف الأربعة:

سيرفر التطبيق Application Server يرسل بطلب POST إلى سيرفر الإشعارات ntfy، الذي يرسل عبر JSON stream أو WebSocket إلى تطبيق الموزع ntfy على هاتف Android وفيه اتصال دائم واحد لكل التطبيقات كخدمة في المقدمة، والموزع يمرر الرسالة MESSAGE إلى تطبيقك الذي يحمل مكتبة الموصل والمفتاحين ويفك الرسالة بحسب RFC 8291، وخط متقطع من تطبيقك إلى سيرفر التطبيق يبين أن العنوان والمفتاحين يصلان مرة واحدة عند التسجيل
سيرفرك يرسل إلى عنوان، ولا يعرف أي موزع خلفه
  • سيرفر التطبيق Application Server: سيرفرك أنت، مثل سيرفر Matrix أو Mastodon أو تطبيقك الخاص، ويرسل الرسالة إلى العنوان الذي أعطاه الهاتف.
  • سيرفر الإشعارات Push Server: يستقبل الرسالة من سيرفرك ويحفظها ويمررها إلى الموزع المتصل به، وفي مختبرنا هو ntfy على سيرفرنا، وقد شرحنا تثبيته في إشعارات فورية إلى هاتفك مع ntfy.
  • الموزع Distributor: تطبيق على الهاتف يحمل الاتصال، وفي المختبر تطبيق ntfy ل Android.
  • الموصل Connector: مكتبة داخل تطبيقك تتحدث مع الموزع، وتولد مفتاحي التشفير، وتفك الرسالة.

والجميل في التصميم أن الرسالة بين سيرفرك وسيرفر الإشعارات هي رسالة Web Push عادية مشفرة بالمعيار RFC 8291، أي الرسالة نفسها التي نرسلها إلى Chrome وFirefox، فسيرفرك لا يحتاج كوداً خاصاً ب UnifiedPush، وإنما يرسل إلى عنوان آخر، وهذا ما سوف نثبته في المختبر بالملف نفسه الذي أرسلنا به إلى المتصفحات في المقال السابق.

مواصفة Android: ما الذي يمر بين تطبيقك والموزع؟ Android Spec

التطبيق والموزع تطبيقان مختلفان على الهاتف، ويتحدثان برسائل البث Broadcast Intents في Android، وكل رسالة لها اسم وحقول محددة في مواصفة Android بالإصدار AND_3.1.0. ولن تكتب هذه الرسائل بيدك، لأن مكتبة الموصل تكتبها، لكنك سوف تراها في السجلات عند كل مشكلة، لذلك هذه أهمها:

الرسالةمن وإلىما تحمله ومعناها
REGISTERتطبيقك إلى الموزعتوكن Token عشوائي حتى 100 بايت، ومفتاح VAPID اختياري، ووصف قصير يعرضه الموزع
NEW_ENDPOINTالموزع إلى تطبيقكعنوان الإرسال حتى 1000 بايت، ويرسل عند التسجيل وعند تغير العنوان وعند عودة السيرفر
MESSAGEالموزع إلى تطبيقكالبايتات المشفرة كما وصلت، من 1 إلى 4096 بايت
MESSAGE_ACKتطبيقك إلى الموزعتأكيد الاستلام إذا أرسل الموزع معرفاً للرسالة
REGISTRATION_FAILEDالموزع إلى تطبيقكمع سبب: INTERNAL_ERROR أو NETWORK أو ACTION_REQUIRED أو VAPID_REQUIRED
UNREGISTER وUNREGISTEREDفي الاتجاهينإلغاء التسجيل من التطبيق، أو إعلان الموزع أن التسجيل انتهى
TEMP_UNAVAILABLEالموزع إلى تطبيقكسيرفر الإشعارات متوقف مؤقتاً، مع موزع بديل اختياري
RAISE_TO_FOREGROUNDالموزع يربط خدمة في تطبيقكيرفع تطبيقك إلى أهمية المقدمة 5 ثوان حتى يستطيع أن يعمل

وفي المواصفة تفاصيل تفسر ما سوف تراه في المختبر:

  • هوية التطبيق Identity: كيف يعرف الموزع أي تطبيق يسجل؟ في Android 14 (SDK 34) وما بعده يرسل التطبيق البث بالعلامة FLAG_SHARE_IDENTITY فيعرف الموزع اسم الحزمة Package Name، وقبله يرسل PendingIntent يستخرج منه الموزع الاسم. وفي سجلنا ستجد السطر «Package name retrieved with shared identity».
  • رفع التطبيق إلى المقدمة: لا يستطيع تطبيق في الخلفية أن يفعل شيئاً يذكر في Android الحديث، لذلك تلزم المواصفة الموزع أن يرفع تطبيقك إلى أهمية المقدمة 5 ثوان عند كل رسالة، إما بواجهات خاصة بالنظام أو بأن يربط Bind خدمة في تطبيقك اسمها RaiseToForegroundService، وهذا ما رأيناه في السجل حرفياً.
  • الأولوية: الترويسة Urgency من RFC 8030 تعمل هنا أيضاً، والمواصفة تحدد أن الرسالة بأولوية very-low تصل عندما يكون الهاتف على الشاحن وعلى Wi-Fi، وlow على أحدهما، وnormal في غيرهما، وhigh حتى مع البطارية المنخفضة.
  • الانتهاء: الموزع يرسل UNREGISTERED إذا لم يؤكد تطبيقك أي رسالة 30 يوماً، بعد أن يرسل له NEW_ENDPOINT للتأكد أنه حي.

مكتبة الموصل في تطبيقك Connector Library

من جهة تطبيقك يكفي أن تضيف مكتبة الموصل الرسمية org.unifiedpush.android:connector، وأحدث إصداراتها 3.3.6 بتاريخ 18 نوفمبر 2026، ثم تكتب كلاساً يرث من PushService وتعلنه في ملف Manifest بالفعل org.unifiedpush.android.connector.PUSH_EVENT. والكود التالي من تطبيق المثال الرسمي، وهو التطبيق نفسه الذي ثبتناه في المختبر بالإصدار 2.3.1، وحذفنا منه أجزاء وضع المطور Developer Mode:

class PushServiceImpl : PushService() {
    private val context = this
    override fun onMessage(message: PushMessage, instance: String) {
        val params = decodeMessage(message.content.toString(Charsets.UTF_8))
        notify(context, params)
    }

    override fun onNewEndpoint(endpoint: PushEndpoint, instance: String) {
        Log.d(TAG, "New Endpoint (temp=${endpoint.temporary}): ${endpoint.url}")
        ApplicationServer(context).storeEndpoint(endpoint.url)
        endpoint.pubKeySet?.let {
            ApplicationServer(context).storeWebPushKeys(
                it.auth,
                it.pubKey
            )
        }
        Events.emit(Events.Type.UpdateUi)
    }

    override fun onRegistrationFailed(reason: FailedReason, instance: String) {
        Toast.makeText(context, "Registration Failed: $reason", Toast.LENGTH_SHORT).show()
        if (reason == FailedReason.VAPID_REQUIRED) {
            if (vapidImplementedForSdk()) {
                val store = Store(context)
                store.distributorRequiresVapid = true
                ApplicationServer(context).genVapidKey()
                UnifiedPush.register(context, instance, vapid = store.vapidPubKey)
            } else {
                Toast.makeText(context, "Distributor requires VAPID but it isn't implemented for old Android versions.", Toast.LENGTH_SHORT).show()
                UnifiedPush.removeDistributor(context)
            }
        } else {
            UnifiedPush.removeDistributor(context)
        }
    }

    override fun onUnregistered(instance: String) {
        // Remove the endpoint on the application server
        ApplicationServer(context).storeEndpoint(null)
        Events.emit(Events.Type.UpdateUi)
    }
}

في الكود أعلاه لاحظ التالي:

  • onNewEndpoint هو المكان الذي ترسل فيه العنوان والمفتاحين pubKey وauth إلى سيرفرك، وهذا يقابل الطلب /subscribe في المتصفح تماماً، والمكتبة هي التي ولدت المفتاحين وحفظتهما.
  • onMessage يصله المحتوى مفكوكاً، فالمكتبة تفك الرسالة بحسب RFC 8291 قبل أن تستدعيه، والحقل message.decrypted يخبرك هل نجح الفك.
  • onRegistrationFailed بالسبب VAPID_REQUIRED يعني أن الموزع لا يقبل التسجيل دون مفتاح VAPID، فيعيد التطبيق التسجيل بمفتاح، ومع غيره من الأسباب يزيل الموزع ويترك المستخدم يختار غيره.
  • onUnregistered هو اللحظة الوحيدة التي يعرف فيها تطبيقك أن العنوان انتهى، والتعليق في الكود يقول ما يجب أن يحدث: احذفه من سيرفر التطبيق، وسوف نرى في المختبر لماذا هذا السطر أهم مما يبدو.

واختيار الموزع نفسه سطر واحد عند التشغيل: الدالة tryUseCurrentOrDefaultDistributor تستخدم الموزع المحفوظ أو الافتراضي، ثم تستدعي register، وإذا كان على الهاتف أكثر من موزع تستطيع أن تعرض للمستخدم قائمة الموزعين بالدالة getDistributors، كما في توثيق المكتبة.

المختبر: هاتف Android حقيقي وسيرفر ntfy خاص Lab

المختبر من ثلاثة أجزاء: سيرفر ntfy بالإصدار 2.38.1 في Container على جهازنا، ومحاكي Android بالإصدار 35.4.9 يشغل Android 15 بصورة نظام فيها خدمات Google Play، وسيرفر تطبيق صغير ب Node.js يرسل بالتشفير الذي كتبناه في قسم الإرسال. وثبتنا على الهاتف تطبيقين من مصادر مفتوحة: ntfy بالإصدار 1.25.2 من F-Droid، وتطبيق المثال UP-Example بالإصدار 2.3.1 من صفحة إصداراته في Codeberg.

سيرفر ntfy موزعاً خاصاً

ملف الإعداد التالي يجعل ntfy سيرفراً خاصاً لا يقرأ فيه أحد ولا يكتب إلا بإذن، ويفعل خيار تحديد المعدل بحسب المشترك:

# ntfy as a self-hosted UnifiedPush server for the Android lab
base-url: "http://127.0.0.1:18600"
listen-http: ":80"
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
visitor-subscriber-rate-limiting: true
log-level: "debug"

ثم الحسابات والصلاحيات، كما في مثال UnifiedPush في توثيق ntfy: أي أحد يكتب في المواضيع التي تبدأ ب up دون حساب، لأن سيرفرات التطبيقات لا تعرف حسابات ntfy أصلاً، والهاتف يقرأ بحساب phone:

docker exec -e NTFY_PASSWORD='Phone-Lab-2026' lab-ntfy ntfy user add phone
docker exec lab-ntfy ntfy access phone 'up*' read-write
docker exec lab-ntfy ntfy access '*' 'up*' write-only
docker exec lab-ntfy ntfy access
user phone (role: user, tier: none)
- read-write access to topic up*
user * (role: anonymous, tier: none)
- write-only access to topic up*
- no access to any (other) topics (server config)

ولاحظ أننا أعطينا الهاتف read-write وليس read-only كما في المقال السابق، والسبب في الخيار visitor-subscriber-rate-limiting: التوثيق يقول إن الرسائل إلى مواضيع UnifiedPush تحسب على أول مشترك في الموضوع، أي على الهاتف وليس على سيرفر التطبيق، وإن تسجيل هذا المشترك يحتاج صلاحية القراءة والكتابة معاً. وفائدة الخيار أن سيرفر Mastodon مثلاً الذي يرسل لآلاف المستخدمين عبر سيرفرك لا يستهلك حد الرسائل اليومي كله باسمه.

والهاتف في المحاكي لا يرى 127.0.0.1 على جهازك، لذلك حولنا المنفذ بالأمر adb reverse، فيصبح العنوان نفسه صالحاً من الجهاز ومن الهاتف، ثم ثبتنا التطبيقين:

adb -s emulator-5600 reverse tcp:18600 tcp:18600
adb -s emulator-5600 install -r ntfy-1.25.2.apk
adb -s emulator-5600 install -r up-example-2.3.1.apk

وفي تطبيق ntfy غيرنا من الإعدادات السيرفر الافتراضي Default Server إلى http://127.0.0.1:18600، لأن الموزع يسجل التطبيقات على سيرفره الافتراضي، وأضفنا الحساب phone من «Manage users». وأول ما عرضه التطبيق عند فتحه طلب إذن الإشعارات، ثم شريط أحمر يقول «Battery optimization should be off for the app to avoid notification delivery issues»، وهذا الشريط سوف يكون سبب أول مشكلة واجهتنا.

التسجيل: ماذا رأى السجل؟

فتحنا UP-Example، فطلب إذن الإشعارات أيضاً، ثم ضغطنا «Register». ولأن ntfy هو الموزع الوحيد المثبت سجلت المكتبة عنده مباشرة دون أن تسأل، وظهر في الشاشة العنوان والمفتاحان، كما في الصورة التالية، والسجل من الأمر adb logcat مصفى على وسوم المكتبة والموزع:

D/UnifiedPush( 5674): Found distributor with package name io.heckel.ntfy
D/UnifiedPush( 5674): Found distributor with package name org.unifiedpush.example
D/UnifiedPush( 5674): Generating WebPushKeys
D/NtfyUpBroadcastRecv( 4364): Registering org.unifiedpush.example. Package name retrieved with shared identity
D/NtfyUpBroadcastRecv( 4364): REGISTER received for app org.unifiedpush.example (connectorToken=fee44ccf-f13a-4f4d-95cb-a1ef6dcec8dc)
D/NtfyUpBroadcastRecv( 4364): Adding subscription with for app org.unifiedpush.example (connectorToken fee44ccf-f13a-4f4d-95cb-a1ef6dcec8dc): Subscription(id=39003966, baseUrl=http://127.0.0.1:18600, topic=upe0D6CsSqeFs0, instant=true, …)
D/NtfyUpDistributor( 4364): Sending NEW_ENDPOINT to org.unifiedpush.example (token=fee44ccf-f13a-4f4d-95cb-a1ef6dcec8dc): http://127.0.0.1:18600/upe0D6CsSqeFs0?up=1
D/NtfySubscriberMgr( 4364): Enqueuing work to refresh subscriber service
D/UnifiedPush( 5674): getWebPushKeys: keys found
D/NtfySubscriberMgr( 4364): ServiceStartWorker: Starting foreground service (work ID: ed9f8f29-32ff-4c08-ace2-7eee00d3564c)
W/NtfySubscriberMgr( 4364): ServiceStartWorker: Failed to start foreground service: startForegroundService() not allowed due to mAllowStartForeground false: service io.heckel.ntfy/.service.SubscriberService

في السجل أعلاه لاحظ التالي:

  • المكتبة وجدت موزعين: ntfy، وتطبيق المثال نفسه، لأن الإصدار 2.x من المثال يحمل موزعاً داخلياً سوف نرى دوره في قسم FCM.
  • «Generating WebPushKeys»: المكتبة ولدت زوج المفاتيح والسر auth على الهاتف قبل أن ترسل REGISTER، فالمفتاح الخاص لا يغادر الهاتف.
  • الموزع عرف التطبيق بالهوية المشتركة كما في المواصفة، وأنشأ موضوعاً عشوائياً upe0D6CsSqeFs0 على السيرفر، وأرسل العنوان كاملاً في NEW_ENDPOINT، وفي آخره ?up=1 الذي يعرف به ntfy أن الرسالة UnifiedPush فيتعامل معها كبايتات.
  • السطر الأخير هو المشكلة، ونعود إليه بعد قليل.
لقطتان من Android: الأولى شاشة تطبيق UP-Example بعد التسجيل وفيها Endpoint بالعنوان http://127.0.0.1:18600/upiCeCo4NNvI7z?up=1 وAuth وP256dh ورابط Test page وزرا Unregister وSend notification، والثانية شريط الإشعارات وفيه إشعار من UP-Example نصه طلبك رقم 1042 خرج للتوصيل، وتحته في قسم Silent إشعار ntfy الدائم Listening for incoming notifications وSubscribed to one topic
العنوان والمفتاحان كما يراها تطبيقك، والرسالة الأولى مع إشعار ntfy الدائم

المشكلة الأولى: الموزع لم يفتح الاتصال

أرسلنا أول رسالة من سيرفر التطبيق إلى العنوان، فكان الرد من ntfy كما يلي:

{"status":507,"text":"{\"code\":50701,\"http\":507,\"error\":\"cannot publish to UnifiedPush topic without previously active subscriber\"}","bytes":146,"location":null} 75 ms

وسجل ntfy قال topic_subscribers=0، أي أن الهاتف لم يتصل بالموضوع أصلاً. والسبب في السطر الأخير من سجل Android: عندما وصل REGISTER كان تطبيق ntfy في الخلفية، فحاول أن يبدأ خدمته في المقدمة التي تحمل الاتصال، فرفض النظام بالرسالة «startForegroundService() not allowed due to mAllowStartForeground false». وهذا قيد في Android منذ الإصدار 12: التطبيق في الخلفية لا يستطيع أن يبدأ خدمة في المقدمة إلا في حالات معدودة. وعندما فتحنا تطبيق ntfy بأيدينا بدأت الخدمة، وظهر في السجل «Opening subscription connection to http://127.0.0.1:18600/upiCeCo4NNvI7z/json?since=none» ثم «state=CONNECTED»، ونجح الإرسال.

والحل الدائم هو بالضبط ما كان الشريط الأحمر يطلبه: إعفاء ntfy من تحسين البطارية Battery Optimization. وفي المحاكي يكفي الأمر التالي، وعلى هاتف حقيقي يفعلها المستخدم من الزر «FIX NOW» في التطبيق، أو تفرضها المؤسسة على أجهزتها من نظام إدارة الأجهزة MDM:

adb -s emulator-5600 shell dumpsys deviceidle whitelist +io.heckel.ntfy
Added: io.heckel.ntfy

ثم ألغينا التسجيل وسجلنا من جديد والتطبيقان في الخلفية، فكان السجل هذه المرة:

D/NtfyUpBroadcastRecv( 4364): REGISTER received for app org.unifiedpush.example (connectorToken=c5a02eee-5c00-4904-9bc7-3a427c7778ea)
D/NtfyUpDistributor( 4364): Sending NEW_ENDPOINT to org.unifiedpush.example (token=c5a02eee-5c00-4904-9bc7-3a427c7778ea): http://127.0.0.1:18600/upSS7gmAISQ1Ko?up=1
D/NtfySubscriberMgr( 4364): Enqueuing work to refresh subscriber service
D/NtfySubscriberMgr( 4364): ServiceStartWorker: Starting foreground service (work ID: a56a5d9e-6366-4143-8341-531af9f39ab9)
D/NtfyJsonConnection( 4364): [http://127.0.0.1:18600/upSS7gmAISQ1Ko] Starting connection for subscriptions: {upSS7gmAISQ1Ko=30119438}

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

لقطتان من تطبيق ntfy على Android: الأولى شاشة Subscribed topics وفيها شريط أحمر Battery optimization should be off for the app to avoid notification delivery issues مع أزرار ASK LATER وDISMISS وFIX NOW، والثانية قائمة المواضيع وفيها موضوع 127.0.0.1:18600/upiUjy5we7WDKc وتحته org.unifiedpush.example (UnifiedPush)
الشريط الأحمر في ntfy هو حل المشكلة الأولى، والموضوع يظهر باسم التطبيق الذي سجله

الإرسال من سيرفر التطبيق

سيرفر التطبيق في المختبر سكربت صغير يستخدم ملف webpush-raw.mjs الذي شرحناه سطراً سطراً في مقال إشعارات المتصفح Web Push وVAPID من هذه المرحلة، أي التشفير بحسب RFC 8291 وتوقيع VAPID بوحدة node:crypto فقط. ولم نستخدم مكتبة web-push هنا لسبب عملي رأيناه في المقال السابق: المكتبة ترسل عبر HTTPS دائماً، وسيرفر ntfy في المختبر على HTTP، أما fetch في Node.js فيرسل إلى العنوان كما هو:

// The app server side of UnifiedPush: the same Web Push request, sent to the ntfy endpoint the phone registered
import { send, vapidKeys } from './webpush-raw.mjs';
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
if (!existsSync('vapid.json')) writeFileSync('vapid.json', JSON.stringify(vapidKeys()));
const keys = JSON.parse(readFileSync('vapid.json', 'utf8'));
const sub = JSON.parse(readFileSync(process.argv[2], 'utf8'));
const text = process.argv[3] || 'رسالة جديدة في المحادثة';
const opts = JSON.parse(process.argv[4] || '{}');
const t0 = Date.now();
console.log(JSON.stringify(await send(sub, text, keys, { trace: true, ...opts })), `${Date.now() - t0} ms`);

والاشتراك في الملف up-sub.json هو ما عرضه التطبيق على الشاشة، بالصيغة نفسها التي يرسلها المتصفح:

{"endpoint":"http://127.0.0.1:18600/upiCeCo4NNvI7z?up=1","keys":{"p256dh":"BFUzXhuQMlFw1J-WQ0V6nho_Y5tS2WvzfF-SRBBkk8cYCcoX1reT8qfAndtMtXwgEFJF2EI74QQNn6L6ZGRcVX4","auth":"tj2_3TMLLvE-i-D7yBJ98w"}}
node up-send.mjs up-sub.json 'طلبك رقم 1042 خرج للتوصيل'
{
  ecdhSecret: '13c8ed4afb7277e8…',
  ikm: '2966e568a12aa043…',
  cek: '34fe187df9e5b8446ddf5c3e013421c2',
  nonce: '9f2043095700001d1125e154',
  header: 86,
  body: 59
}
{"status":200,"text":"{\"id\":\"1KDnHVLCyUZF\",\"time\":1795136321,\"expires\":1795179521,\"event\":\"message\",\"topic\":\"upiCeCo4NNvI7z\",\"message\":\"l5Fre2uVgNRTwwbAVGOMRQAAEABBBKpIN1GjkaW3t6G/rKoKEs2IT3zT+ThcpyXduLr6Va4XLnZ1Hv9g0OiLcD","bytes":145,"location":null} 94 ms

وفي الهاتف كان السجل:

11-20 03:58:41.239 D/NtfyUpDistributor( 4364): Sending MESSAGE to org.unifiedpush.example (token=9fa3a71d-5bd2-4fe4-913a-938b8e435831): 145 bytes
11-20 03:58:41.258 I/NtfyUpRaiseFg( 4364): Found foreground process: io.heckel.ntfy
11-20 03:58:41.274 D/NtfyUpRaiseFg( 4364): Binding to org.unifiedpush.example
11-20 03:58:41.398 D/NtfyUpRaiseFg( 4364): onServiceConnected ComponentInfo{org.unifiedpush.example/org.unifiedpush.android.connector.internal.RaiseToForegroundService}
11-20 03:58:41.398 D/NtfyUpRaiseFg( 4364): Sending msg for org.unifiedpush.example
11-20 03:58:41.565 D/UnifiedPush( 5674): getWebPushKeys: keys found

في المخرج أعلاه لاحظ التالي:

  • ntfy رد ب 200 ومعه الرسالة كما حفظها، والحقل message فيه البايتات المشفرة بترميز base64، فسيرفر الإشعارات نفسه لا يرى النص، حتى لو كان سيرفرك.
  • بداية النص المشفر l5Fre2uVgNRTwwbAVGOMRQAAEAB هي ترويسة aes128gcm: أول 16 بايت ملح، ثم AAAQAA وهي حجم السجل 4096، ثم BB أي بايت الطول 65 وبداية المفتاح العام المؤقت 04، فالرسالة هي نفسها التي نرسلها إلى Chrome.
  • 145 بايت من السيرفر إلى الموزع إلى التطبيق دون تغيير، والموزع ربط الخدمة RaiseToForegroundService في تطبيقنا كما تطلب المواصفة، ثم فك التطبيق الرسالة وعرضها، وكل ذلك في أقل من نصف ثانية بعد وصولها إلى ntfy.

والصورة التالية تجمع التسجيل والرسالة كما ظهرت في السجلات:

مخطط تسلسلي بأربعة أعمدة: تطبيقك الموصل، وتطبيق ntfy الموزع، وسيرفر ntfy، وسيرفر التطبيق، والأسهم بالترتيب: REGISTER من التطبيق إلى الموزع، ثم NEW_ENDPOINT بالعنوان، ثم GET /upe0D6/json من الموزع إلى السيرفر وتحته تحتاج Foreground Service، ثم التطبيق يرسل العنوان والمفتاحين إلى سيرفره، ثم POST 145 bytes بالرد 200 من سيرفر التطبيق إلى ntfy، ثم event message بترميز base64 إلى الموزع، ثم MESSAGE 145 bytes، ثم bind RaiseToForegroundService، وأخيراً فك التشفير ثم الإشعار
الأسماء من المواصفة، والأرقام من السجل الحقيقي

ماذا يحدث إذا…؟ أربع تجارب على الهاتف What If

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

التطبيق ألغى التسجيل، وسيرفرك لم يعرف

ضغطنا «Unregister» في التطبيق، فكان سجل الهاتف:

D/UnifiedPush( 5674): Deleting WebPushKeys
D/NtfyUpBroadcastRecv( 4364): UNREGISTER received (connectorToken=9fa3a71d-5bd2-4fe4-913a-938b8e435831)
D/NtfyUpBroadcastRecv( 4364): Removing subscription 54204495 with connectorToken 9fa3a71d-5bd2-4fe4-913a-938b8e435831
D/NtfyUpDistributor( 4364): Sending UNREGISTERED to org.unifiedpush.example (token=9fa3a71d-5bd2-4fe4-913a-938b8e435831)
D/NtfySubscriberService( 4364): Stopping the foreground service
D/NtfyJsonConnection( 4364): [http://127.0.0.1:18600/upiCeCo4NNvI7z] Connection fully SHUT DOWN

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

{"status":200,"text":"{\"id\":\"opcKRW3sT3Ef\",\"time\":1795136374,\"expires\":1795179574,\"event\":\"message\",\"topic\":\"upiCeCo4NNvI7z\",\"message\":\"mWRIFFb7y516y2D/cIUriAAAEABBBIH6YnQsNUAQjDnn5EXL11F/slvD5Nj3hIg7J4D2N0UMUTGEBxpYtW1rju","bytes":135,"location":null} 77 ms

الرد 200، فسيرفر ntfy قبل الرسالة وحفظها 12 ساعة لموضوع لن يقرأه أحد. والسبب أن ntfy لا يعرف أن الهاتف ألغى، فهو يعرف فقط أن المشترك قطع الاتصال، وهذا يحدث كل يوم عندما يدخل الهاتف مصعداً. وبحسب توثيق ntfy لا يرد السيرفر ب 410 إلا إذا بقي الموضوع دون مشترك أربعة أيام، مع الخيار visitor-subscriber-rate-limiting. والنتيجة العملية: الطريق الوحيد ليعرف سيرفرك فوراً هو السطر في onUnregistered الذي رأيناه في كود المكتبة، أي أن يرسل التطبيق إلى سيرفره «احذف هذا العنوان»، وإلا ظل سيرفرك يرسل أربعة أيام إلى عنوان ميت، وهو ما رأيناه بالضبط مع المتصفحات في مقال Web Push من هذه المرحلة.

الهاتف في وضع Doze العميق

أدخلنا الهاتف في وضع Doze العميق بالقوة، وهو الوضع الذي يدخله الهاتف المتروك على الطاولة دون شاحن، ثم أرسلنا رسالة بأولوية normal:

adb -s emulator-5600 shell dumpsys battery unplug
adb -s emulator-5600 shell dumpsys deviceidle force-idle
adb -s emulator-5600 shell dumpsys deviceidle get deep
node up-send.mjs up-sub2.json 'رسالة والجهاز في Doze' '{"urgency":"normal"}'
Now forced in to deep idle mode
IDLE
{"status":200, … "bytes":138} 112 ms
11-20 04:00:44.541 D/NtfyUpDistributor( 4364): Sending MESSAGE to org.unifiedpush.example (token=c5a02eee-5c00-4904-9bc7-3a427c7778ea): 138 bytes
11-20 04:00:44.623 D/NtfyUpRaiseFg( 4364): onServiceConnected ComponentInfo{org.unifiedpush.example/org.unifiedpush.android.connector.internal.RaiseToForegroundService}
11-20 04:00:44.955 D/UnifiedPush( 5674): getWebPushKeys: keys found

وصلت الرسالة والهاتف ما زال في حالة IDLE، والسبب أن ntfy معفى من تحسين البطارية بالأمر الذي نفذناه في حل المشكلة الأولى، فاتصاله بالشبكة لم يقطع، وهذا بالضبط ما تحصل عليه خدمات Google Play لنفسها. ولاحظ أن هذا الإعفاء نفسه هو ثمن UnifiedPush على البطارية: اتصال دائم واحد، وليس اتصالاً لكل تطبيق، لكنه اتصال تدفع أنت ثمنه بدل Google.

التطبيق موقوف بالقوة

في Android لا يستقبل التطبيق الذي أوقفه المستخدم بالقوة من الإعدادات أي رسالة بث Broadcast حتى يفتحه بيده، وهذا ما يقلق كل من يبني على الرسائل بين التطبيقات. فأوقفنا UP-Example بالأمر am force-stop وأرسلنا:

D/NtfyUpDistributor( 4364): Sending MESSAGE to org.unifiedpush.example (token=c5a02eee-5c00-4904-9bc7-3a427c7778ea): 148 bytes
D/NtfyUpRaiseFg( 4364): Binding to org.unifiedpush.example
D/WM-ForceStopRunnable( 6455): Application was force-stopped, rescheduling.
D/NtfyUpRaiseFg( 4364): onServiceConnected ComponentInfo{org.unifiedpush.example/org.unifiedpush.android.connector.internal.RaiseToForegroundService}
D/NtfyUpRaiseFg( 4364): Sending msg for org.unifiedpush.example
D/UnifiedPush( 6455): DBStore version 1
D/UnifiedPush( 6455): getWebPushKeys: keys found
D/NtfyUpRaiseFg( 4364): Timeout expired, unbinding

وصلت الرسالة، ورقم العملية تغير من 5674 إلى 6455، أي أن Android شغل التطبيق من جديد، والذي أيقظه هو ربط الخدمة RaiseToForegroundService من الموزع وليس رسالة البث، فالمكتبة في الإصدار 3 تستقبل الرسالة عبر خدمة مربوطة. واستغرق ذلك قرابة ثانية بين إرسال الموزع ووصولها، لأن التطبيق بدأ من الصفر، ثم فك الموزع الربط بعد خمس ثوان بالضبط كما تقول المواصفة. ولا تعتبر هذا ضماناً على كل الأجهزة، فبعض الشركات المصنعة تضيف قيوداً أشد من Android نفسه، لكنه يعني أن المواصفة الحالية تعالج الحالة التي كانت أكبر نقطة ضعف في الإصدارات الأولى.

مفتاح auth خاطئ، ورسالة أكبر من الحد

أرسلنا رسالة إلى العنوان الصحيح لكن بسر auth خاطئ، كما يحدث عندما يحفظ سيرفرك مفاتيح تسجيل قديم بالعنوان الجديد:

D/NtfyUpDistributor( 4364): Sending MESSAGE to org.unifiedpush.example (token=c5a02eee-5c00-4904-9bc7-3a427c7778ea): 127 bytes
D/UnifiedPush( 6455): getWebPushKeys: keys found
W/UnifiedPush( 6455): Could not decrypt message, trying with plain text. Cause: error:1e000065:Cipher functions:OPENSSL_internal:BAD_DECRYPT

ntfy قبل الرسالة ب 200 كالعادة، ووصلت إلى الهاتف، وفشل الفك، فعرض التطبيق «Could not decrypt content.» كما في الصورة الأخيرة من المختبر، وتطبيقك في الإنتاج قد لا يعرض شيئاً. ثم جربنا الحد: RFC 8030 والمواصفة تقولان إن الرسالة المشفرة حتى 4096 بايت، أي 3993 بايت من النص، فأرسلنا 3993 ثم 3994:

{"status":200, … "bytes":4096,…}
D/NtfyUpDistributor( 4364): Sending MESSAGE to org.unifiedpush.example (token=c5a02eee-…): 4096 bytes
D/UnifiedPush( 6455): getWebPushKeys: keys found
{"status":200, … "bytes":4097,…}
D/NtfyUpDistributor( 4364): Sending MESSAGE to org.unifiedpush.example (token=c5a02eee-…): 4096 bytes
W/UnifiedPush( 6455): Could not decrypt message, trying with plain text. Cause: error:1e000065:Cipher functions:OPENSSL_internal:BAD_DECRYPT
صفان: في الأعلى نص 3993 بايت يصبح بعد التشفير 4096 بايت ويرد ntfy ب 200 ويرسل MESSAGE 4096 بايت فيفك الهاتف الرسالة وتصل، وفي الأسفل نص 3994 بايت يصبح 4097 بايت ويرد ntfy ب 200 أيضاً لكنه يرسل MESSAGE 4096 بايت فيظهر على الهاتف BAD_DECRYPT وCould not decrypt، وملاحظة أن خدمة Google ردت 400 على الحجم نفسه
بايت واحد زائد: قبول من السيرفر، ورسالة لا تفك على الهاتف

وهذه أخطر نتيجة في المختبر: ntfy قبل الرسالة الأكبر من الحد بالرد 200، ثم أوصل إلى الموزع 4096 بايت فقط، أي أن آخر بايت من وسم التحقق في AES-GCM سقط، ففشل الفك على الهاتف. وخدمة Google في المقال السابق ردت على الحجم نفسه بالرفض 400، فعرف السيرفر أن رسالته خاطئة، أما هنا فلا يعرف أحد شيئاً إلا من سجل الهاتف. والقاعدة: افحص حجم النص في سيرفرك قبل التشفير، وارفض ما زاد على 3993 بايت، أو أرسل إشارة قصيرة يطلب بعدها التطبيق التفاصيل من سيرفرك، ولا تعتمد على أن سيرفر الإشعارات سوف يرفض.

والصورة التالية تجمع ما رأيناه عن الخلفية في Android:

أربعة مربعات: في الأعلى مربع أحمر التسجيل وتطبيق ntfy في الخلفية وفيه رسالة startForegroundService not allowed وأن السيرفر رد 507 والحل فتح ntfy أو إعفاؤه من تحسين البطارية، وبجانبه مربع أخضر بعد الإعفاء والاتصال يفتح مع التسجيل مباشرة، وفي الأسفل ثلاثة مربعات: الجهاز في Doze العميق ووصلت الرسالة لأن الموزع معفى، وتطبيقك موقوف بالقوة والموزع ربط خدمة التطبيق فأيقظه، والموزع متوقف فلا اتصال ولا إشعارات وntfy يرد على سيرفرك ب 200 فلا يعتبر القبول وصولاً
الحلقة الضعيفة ليست سيرفرك، وإنما بقاء الموزع حياً على الهاتف

موزع FCM المضمن: للمستخدمين الذين لا موزع عندهم

أكبر عائق أمام UnifiedPush في تطبيق عام أن أغلب مستخدمي Android لن يثبتوا تطبيقاً إضافياً لأجل تطبيقك. ولهذا يقدم المشروع مكتبة اسمها embedded_fcm_distributor وأحدث إصداراتها 3.1.0، تضع داخل تطبيقك موزعاً احتياطياً يعمل عبر FCM نفسه، فإذا وجدت المكتبة موزعاً مثبتاً استخدمته، وإلا استخدمت الموزع المضمن. وتطبيق المثال يأتي بنسختين: main التي جربناها، وfcm التي فيها هذا الموزع، فثبتنا نسخة fcm وعطلنا ntfy بالأمر pm disable-user io.heckel.ntfy وسجلنا:

D/UnifiedPush( 7549): Generating WebPushKeys
D/UP-FCMD ( 7549): New intent for d0exxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
D/UP-FCMD ( 7549): Registering to the embedded distributor
D/UnifiedPush( 7549): getWebPushKeys: keys found
D/UnifiedPush( 7549): Binding to PushService
D/PushServiceImpl( 7549): New Endpoint (temp=false): https://fcm.distributor.unifiedpush.org/wpfcm?t=e6TZXJBoYt4:APA91bGQ6aO283MM3Qse9LT-yeprdQzeQZS8JXpm_pMglhmzdMjoz_RLMtQGhoVEJD7B9o4prjkremwa_uBvA4ntB9v4eAC09U75RRwi3Sv5vO04bKeu0Nzr96RL55EH3bLd2nz7K9zJ

والعنوان هذه المرة على بوابة fcm.distributor.unifiedpush.org، وفي معامل t توكن FCM للجهاز. وأرسلنا إليه بالسكربت نفسه وبالسطر نفسه، دون أي تغيير في سيرفر التطبيق:

{"status":201,"text":"","bytes":135,"location":null} 876 ms

ووصلت الرسالة وفكها التطبيق كما في الصورة التالية. وهذا هو المعنى العملي للتصميم: سيرفرك يرسل Web Push إلى عنوان، والعنوان قد يكون ntfy على سيرفرك أو بوابة تترجم الرسالة إلى FCM، وسيرفرك لا يعرف الفرق ولا يحتاج أن يعرفه. وعندما أعدنا تفعيل ntfy وسجلنا من جديد اختارت المكتبة ntfy تلقائياً، فالموزع المثبت يقدم على المضمن.

لقطتان من شريط إشعارات Android: الأولى إشعار من UP-Example نصه عبر موزع FCM المضمن، والثانية إشعاران من UP-Example الأول Could not decrypt content بعد رسالة بمفتاح auth خاطئ والثاني نصه بعد إيقاف التطبيق بالقوة
الرسالة عبر الموزع المضمن، والرسالة بمفتاح خاطئ التي لم تفك

لكن انتبه لما تعنيه هذه الطريق: الرسالة تمر ببوابة يديرها مشروع UnifiedPush ثم بخدمة Google، وهي مشفرة طوال الطريق فلا تقرأ أي منهما النص، لكن كلتيهما ترى العنوان والحجم والتوقيت، كما في جدول من يرى ماذا في المقال السابق. والموزع المضمن يعمل بمشروع Firebase يملكه صاحب التطبيق، فتطبيق المثال يستخدم مشروع المثال، وتطبيقك يحتاج مشروعك وملف إعداده، أي أنك لم تخرج من Firebase كلياً، وإنما جعلته طريقاً احتياطياً لمن لا موزع عنده بدل أن يكون الطريق الوحيد.

ولاحظ في سجل التسجيل عبر الموزع المضمن العبارة New Endpoint (temp=false). فالمواصفة تعرف حالة اسمها TEMP_UNAVAILABLE: إذا توقف سيرفر الإشعارات الذي يعتمد عليه الموزع، يستطيع الموزع أن يقترح على تطبيقك موزعاً بديلاً مؤقتاً، فيصل إلى تطبيقك عنوان مؤقت يعرف من هذا الحقل، ثم يعود العنوان الأصلي عندما يرجع السيرفر ويرسل الموزع NEW_ENDPOINT من جديد. ومن جهة سيرفرك هذا يعني شيئين: أن العنوان قد يتغير في أي وقت دون أن يفتح المستخدم التطبيق، فاجعل onNewEndpoint يرسل التحديث إلى سيرفرك كل مرة يستدعى، حتى لو كان العنوان نفسه، وأن سيرفرك قد يحمل لكل مستخدم أكثر من عنوان في فترة الانتقال، فلا تفترض أن لكل جهاز صفاً واحداً إلى الأبد، وإنما احذف القديم عند وصول الجديد للتوكن نفسه، كما يفعل الطلب الذي يرسل العنوانين القديم والجديد في حدث pushsubscriptionchange عند المتصفحات.

الموزعون والتطبيقات التي تدعم UnifiedPush

صفحة الموزعين في موقع المشروع تعرض اليوم عدة تطبيقات تؤدي الدور نفسه بطرق مختلفة، والصورة التالية تلخصها:

هاتف في الوسط عليه تطبيقك مع مكتبة الموصل وtryUseCurrentOrDefaultDistributor، وعلى اليسار ثلاثة موزعين بالأخضر: ntfy بسيرفر عام أو سيرفرك، وNextPush تطبيق داخل Nextcloud عندك، وSunup فوق autopush-rs من Mozilla، وعلى اليمين Conversations عبر حساب XMPP وبروكسي، وgCompat-UP عبر خدمات Google، وموزع FCM مضمن داخل تطبيقك إذا لم يوجد غيره، وملاحظة أن المكتبة اختارت ntfy المثبت وعند تعطيله استخدمت الموزع المضمن
الأخضر يمكن أن يعمل على سيرفرك بالكامل
  • ntfy: الأكثر انتشاراً، ويعمل مع السيرفر العام ntfy.sh أو مع سيرفرك كما في المختبر.
  • NextPush: تطبيق داخل Nextcloud، فإذا كان عندك سيرفر Nextcloud أصلاً لا تحتاج سيرفراً جديداً.
  • Sunup: مبني على autopush-rs، أي الكود المفتوح لخدمة الإشعارات التي يستخدمها Firefox نفسه، ويعمل مع سيرفرها الافتراضي أو سيرفرك.
  • Conversations: تطبيق محادثة XMPP يستخدم اتصاله الدائم بحساب XMPP للإشعارات أيضاً، عبر بروكسي إعادة الكتابة Rewrite Proxy يمكن استضافته.
  • gCompat-UP: موزع يعتمد على خدمات Google لمن عنده خدمات Google ويريد واجهة UnifiedPush.

ومن جهة التطبيقات، فصفحة التطبيقات تعرض أكثر من خمسين تطبيقاً ل Android تدعم UnifiedPush، أغلبها تطبيقات محادثة وشبكات اجتماعية مفتوحة: عملاء Matrix مثل Element وFluffyChat وSchildiChat، وعملاء Mastodon مثل Tusky وFedilab وPachli، وMolly وJami وDAVx⁵ وNextcloud Talk، ومتصفحا Fennec وIronFox. فإذا كان عندك سيرفر Matrix كالذي شرحناه في Matrix مع Element فإشعارات موظفيك تستطيع أن تمر كلها عبر ntfy على سيرفرك، وعلى سطح المكتب في Linux يعمل UnifiedPush أيضاً عبر ناقل الرسائل D-Bus بحسب مواصفة D-Bus، ومن تطبيقاته NeoChat وTokodon.

كيف يتصل الموزع بسيرفره؟ JSON Stream أو WebSocket

في السجل الذي رأيناه عند فتح الاتصال سطر يستحق التوقف: connectionProtocol=jsonhttp، أي أن تطبيق ntfy يفتح طلب HTTP عادياً إلى المسار /upiCeCo4NNvI7z/json ويتركه مفتوحاً، والسيرفر يكتب فيه سطر JSON لكل رسالة، وهذا ما يسمى تدفق JSON أو JSON Stream، وهو أبسط الطرق وأكثرها توافقاً مع أي Reverse Proxy. ومع ذلك عرض التطبيق في المختبر شريطاً ثانياً يقول: «Switching to WebSockets is the recommended way to connect to your server, and could improve battery life, but may require additional config in your proxy». والفرق بين الطريقتين عملي: اتصال WebSocket يسمح للتطبيق أن يرسل نبضات صغيرة Ping ويعرف بسرعة أن الاتصال انقطع، فيقلل محاولات إعادة الاتصال الطويلة التي تستهلك البطارية، لكنه يحتاج أن يمرر ال Reverse Proxy الترويستين Upgrade وConnection ويرفع مهلة القراءة، وهذا ما شرحناه في قسم الإنتاج في دليل ntfy. والقاعدة: ابدأ بالتدفق إذا كان ال Proxy عندك لا يعرف WebSocket، وانتقل إلى WebSocket بعد أن تجرب الإعداد على هاتف واحد يومين كاملين، وراقب في سجلات ntfy عدد مرات إعادة الاتصال لكل جهاز.

وفي الحالتين، تذكر أن كل هاتف يحمل اتصالاً مفتوحاً دائماً بسيرفرك، فألف هاتف تعني ألف اتصال مفتوح على ntfy وعلى ال Reverse Proxy أمامه. وntfy خفيف في هذا، فقد رأينا في دليل ntfy أنه يعمل بعشرات الميجابايت من الذاكرة RAM، لكن حدود الملفات المفتوحة File Descriptors في النظام وفي ال Proxy تصبح هي الحد، فارفعها قبل أن تفرض الموزع على أجهزة المؤسسة كلها.

هل الكتابة للجميع في المواضيع up* آمنة؟ Security

أعطينا في المختبر صلاحية الكتابة في كل المواضيع التي تبدأ ب up لأي أحد دون حساب، وقد يبدو هذا غريباً في سيرفر خاص يبدأ إعداده ب deny-all. والإجابة في طبيعة العنوان نفسه: المواصفة تسمي العنوان «capability URL»، أي أن معرفة العنوان هي الصلاحية، وتوصي بأن يحمل قرابة 160 بت من العشوائية، فالموضوع upSS7gmAISQ1Ko لم يختره أحد، وإنما ولده الموزع، ولا يعرفه إلا الهاتف وسيرفر التطبيق الذي سجل عنده الهاتف. ومن يكتب في موضوع لا يملكه يحتاج أولاً أن يخمن اسمه، ولو خمنه فلن يستطيع أن يكتب رسالة يقبلها التطبيق، لأن الرسالة يجب أن تكون مشفرة بالمفتاح العام للهاتف، والتطبيق الذي استلم بايتات لا تفك يرميها كما رأينا في تجربة المفتاح الخاطئ.

وما الذي تضيفه VAPID هنا؟ المواصفة تسمح لتطبيقك أن يرسل مع REGISTER المفتاح العام VAPID لسيرفره، وهو 87 بايت بترميز base64url، فيستطيع الموزع وسيرفره أن يرفضا أي رسالة غير موقعة بالمفتاح الخاص لسيرفرك، وإذا كان الموزع يطلب ذلك يرد على التسجيل دونه ب REGISTRATION_FAILED والسبب VAPID_REQUIRED، وهذا ما يعالجه كود المثال في onRegistrationFailed. وntfy في المختبر لم يطلب VAPID، فقبل رسائلنا الموقعة وغير الموقعة، وهذا يعني أن حماية الموضوع عنده هي العشوائية والتشفير فقط. والنصيحة العملية: أرسل VAPID دائماً من سيرفرك، فهو لا يكلفك شيئاً، ويجعل الانتقال إلى موزع يطلبه دون تغيير، ولا تعط أحداً صلاحية القراءة في up* إلا حسابات الأجهزة، لأن القراءة تكشف التوقيت والحجم حتى لو بقي المحتوى مشفراً.

ماذا يرى كل طرف في الطريق؟ Privacy

الخروج من FCM قرار يتخذ غالباً لسبب يتعلق بالبيانات، لذلك هذا جدول دقيق لما رأيناه في المختبر في الطريقين، طريق ntfy على سيرفرنا وطريق الموزع المضمن:

الطرفعبر ntfy على سيرفركعبر الموزع المضمن
سيرفر التطبيقالنص، والعنوان، والمفتاحانالنص، والعنوان، والمفتاحان
سيرفر الإشعاراتntfy عندك: بايتات مشفرة بترميز base64، والموضوع والتوقيتبوابة UnifiedPush ثم Google: الحجم والتوقيت وتوكن FCM للجهاز
تطبيق الموزعntfy على الهاتف: البايتات المشفرة واسم الحزمةداخل تطبيقك نفسه
تطبيقكالنص بعد الفكالنص بعد الفك

ولاحظ أن الفرق بين العمودين ليس في المحتوى، فالمحتوى مشفر في الحالتين من سيرفرك إلى تطبيقك، وإنما في البيانات الوصفية Metadata: من يعرف أن هذا الهاتف يستقبل رسالة من تطبيقك في هذه اللحظة. ففي العمود الأول لا يعرف ذلك أحد خارج سيرفراتك، وفي الثاني يعرفه مشروع UnifiedPush وGoogle، وهذا هو بالضبط ما تخفيه UnifiedPush عندما تعمل على سيرفرك.

تجربة المستخدم في تطبيقك Onboarding

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

  • اسأل المكتبة أولاً: الدالة getDistributors تعيد الموزعين المثبتين، فإذا وجدت واحداً استخدمه دون سؤال كما فعلت المكتبة مع ntfy، وإذا وجدت أكثر من واحد اعرض قائمة يختار منها المستخدم، وإذا لم تجد أحداً فاستخدم الموزع المضمن إن كان في تطبيقك، أو اشرح للمستخدم ما الذي يحتاجه.
  • اعرض رسالة للموزع: المواصفة تسمح لتطبيقك أن يرسل مع REGISTER وصفاً قصيراً حتى 100 بايت يعرضه الموزع، مثل اسم الحساب، فيعرف المستخدم في قائمة ntfy أي تسجيل لأي حساب، بدل أن يرى اسم الحزمة وحده كما في صورة المختبر.
  • اشرح البطارية بكلمات المستخدم: «حتى تصلك الرسائل وهاتفك في جيبك، افتح تطبيق ntfy واضغط FIX NOW»، ثم تحقق بنفسك: إذا لم يصل إلى تطبيقك NEW_ENDPOINT مع اتصال فعلي خلال دقيقة، أو إذا رد سيرفرك ب 507 على أول رسالة اختبار، فاعرض الشرح مرة ثانية.
  • أرسل رسالة اختبار: زر «إرسال إشعار تجريبي» في إعدادات تطبيقك يطلب من سيرفرك أن يرسل، فيعرف المستخدم ويعرف سيرفرك أن الطريق كاملاً يعمل، وهذا ما يفعله زر «Send notification» في تطبيق المثال.

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

كم يكلف تشغيل الموزع؟ Resources

قد يتساءل البعض: إذا كان كل هاتف يحمل اتصالاً دائماً وخدمة في المقدمة، فكم تكلف هذه الخدمة على الهاتف وعلى السيرفر؟ وقسنا في المختبر الطرفين في اللحظة التي كان فيها الهاتف متصلاً ومسجلاً. فعلى السيرفر كان Container ntfy يستخدم 26.56 ميجابايت من الذاكرة، وعلى الهاتف أعاد الأمر dumpsys meminfo io.heckel.ntfy القيمة TOTAL PSS: 38992 كيلوبايت، أي قرابة 38 ميجابايت لتطبيق ntfy كله بخدمته في المقدمة، وهو رقم صغير في هاتف حديث، والأهم أنه يدفع مرة واحدة مهما كان عدد التطبيقات التي تستقبل عبره، وهذه هي فكرة الموزع من الأصل. أما البطارية فلا تقاس بدقة في محاكي، والذي يحددها عملياً هو عدد مرات إعادة الاتصال، لذلك كانت توصية WebSocket في القسم السابق، ولذلك أيضاً لا تجعل TTL قصيرة جداً في رسائلك ولا Urgency عالية لكل شيء، فكل رسالة عاجلة تعني إيقاظاً للهاتف.

الإشارة ثم الجلب: نمط يحل نصف المشكلات Signal Then Fetch

أغلب المشكلات التي رأيناها في المختبر لها حل واحد: لا تحمل البيانات في الإشعار. فالرسالة الكبيرة التي قصها ntfy، والمحتوى الذي يمر بالبوابة في الموزع المضمن، والتحديثات المتتالية للشيء نفسه، كلها تختفي إذا كان الإشعار إشارة صغيرة فيها معرف الشيء فقط، مثل {"type":"order","id":1042}، ثم يطلب التطبيق التفاصيل من سيرفرك بطلب HTTPS عادي بعد أن يستيقظ. والنمط نفسه هو ما يستخدمه تطبيق ntfy على iOS كما شرحنا في دليل ntfy، وما تستخدمه تطبيقات Matrix التي ترسل في الإشعار معرف الحدث فقط. وله ثمنان يجب أن تعرفهما: طلب شبكة إضافي بعد كل إشعار، وهذا يعني أن الإشعار لا يعرض نصاً مفيداً إذا لم يستطع التطبيق الوصول إلى سيرفرك في تلك اللحظة، لذلك اجعل في الإشارة نصاً عاماً قصيراً يعرض إذا فشل الجلب، مثل «لديك تحديث على طلبك»، وتذكر أن الخمس ثوان التي يرفع فيها الموزع تطبيقك إلى المقدمة هي الوقت المتاح للجلب كله.

كيف تختبر هذا الطريق آلياً؟ Testing

المختبر نفسه يصلح أساساً لاختبار آلي في خط CI، فكل ما فعلناه كان أوامر adb وسكربتات: تشغيل المحاكي دون نافذة بالخيار -no-window، وتثبيت ntfy وتطبيقك، وضبط الموزع، ثم إعفاؤه من تحسين البطارية، ثم إرسال رسالة من سيرفر الاختبار وانتظار سطر «keys found» أو سطر من تطبيقك في logcat. والأمر الأخير مهم لأنه يختبر ما لا يختبره أي اختبار وحدة: أن الرسالة وصلت إلى الهاتف وفكت فعلاً. وأضف حالات الفشل التي رأيناها اختباراً لكل منها، رسالة أكبر من الحد، ومفتاح خاطئ، وعنوان بعد إلغاء التسجيل، حتى تعرف يوم يتغير سلوك ntfy أو المكتبة في إصدار قادم. وقد شرحنا تشغيل المحاكي في خطوط الاختبار وأدوات قيادة الواجهة في اختبار تطبيقات الجوال مع Appium وMaestro.

ما الذي يتغير في سيرفر التطبيق؟ Application Server

من جهة سيرفرك UnifiedPush هو Web Push، فكل ما في مقال Web Push وVAPID من هذه المرحلة ينطبق هنا كما هو: التشفير، وتوقيع VAPID إذا طلبه الموزع، والترويسات TTL وUrgency وTopic، وجدول الاشتراكات. والفروق التي رأيناها في المختبر:

الحالةالمتصفح عبر خدمة GoogleUnifiedPush عبر ntfy
رسالة 4097 بايت400، والسيرفر يعرف200، والرسالة تقص ولا تفك
إلغاء الاشتراك410 بعد ثوان أو دقائق200 حتى أربعة أيام، ثم 410 مع تحديد المعدل بالمشترك
الموزع لم يتصل بعدلا تنطبق507 cannot publish to UnifiedPush topic without previously active subscriber
مفتاح خاطئ201، والمتصفح يرمي الرسالة200، والتطبيق يكتب BAD_DECRYPT
البروتوكولHTTPS دائماًالعنوان كما أعطاه الموزع، وفي الإنتاج HTTPS خلف Reverse Proxy

وأضف إلى منطق التنظيف الرد 507: لا تحذف الاشتراك بسببه، لأنه يعني أن الهاتف لم يتصل بعد، وأعد المحاولة لاحقاً، وراقب نسبته، فإذا كانت عالية في مستخدمين جدد فهذه علامة على أن تطبيق الموزع لا يعمل في الخلفية عندهم، أي المشكلة الأولى في المختبر. وفي الإنتاج اجعل ntfy خلف Reverse Proxy بشهادة صالحة كما في دليل ntfy، وراقبه كما تراقب قاعدة البيانات، لأنه أصبح جزءاً من مسار كل إشعار لكل تطبيق على هواتف موظفيك.

متى تستخدم UnifiedPush؟ Decision Table

الحالةالقراروالسبب
تطبيق داخلي على أجهزة تديرها المؤسسةUnifiedPush مع ntfy على سيرفرك، والموزع مفروض بنظام MDM ومعفى من تحسين البطاريةالطريق كله على سيرفراتك، وتتحكم في إعداد كل جهاز
تطبيق عام لعامة الناسمكتبة الموصل مع الموزع المضمن عبر FCMمن عنده موزع يستقبل عبره، والبقية عبر FCM كما كانوا
مستخدمون بهواتف دون خدمات GoogleUnifiedPush، والموزع الذي يختارونهFCM لا يعمل عندهم أصلاً
سيرفر Matrix أو Mastodon لمؤسستكntfy على سيرفرك موزعاً لعملاء Matrix وMastodonالتطبيقات تدعمه اليوم دون كود منك
iPhoneلا ينطبقلا يوجد موزع على iOS، والطريق إلى iPhone يمر عبر APNs دائماً

أخطاء شائعة Common Mistakes

  • ترك الموزع تحت تحسين البطارية: لا يبدأ اتصاله من الخلفية، والرسائل ترد 507، وتطبيقك لا يرى أي خطأ.
  • إعطاء الهاتف صلاحية قراءة فقط مع visitor-subscriber-rate-limiting: تسجيل المشترك الأول يحتاج قراءة وكتابة على المواضيع up*.
  • تجاهل onUnregistered: سيرفرك يرسل أربعة أيام إلى عنوان ميت، والرد 200 طوال الوقت.
  • الاعتماد على رفض السيرفر للرسائل الكبيرة: ntfy قبل 4097 بايت وقصها، فافحص الحجم قبل الإرسال.
  • حفظ مفاتيح تسجيل قديم مع عنوان جديد: الرسالة تصل ولا تفك، فاجعل العنوان والمفتاحين صفاً واحداً يستبدل كاملاً عند onNewEndpoint.
  • إزالة FCM من تطبيق عام: أغلب المستخدمين لا موزع عندهم، فأبق الموزع المضمن.
  • ntfy على HTTP في الإنتاج: مكتبات Web Push في أغلب اللغات ترسل عبر HTTPS فقط، كما رأينا في المقال السابق.

قائمة تحقق Checklist

  • ntfy أو موزع آخر على سيرفرك، خلف Reverse Proxy بشهادة، ومراقب.
  • المواضيع up* مكتوبة للجميع، ومقروءة بحسابات الأجهزة.
  • في تطبيقك: مكتبة الموصل، والموزع المضمن للتطبيقات العامة، وشاشة إعداد تشرح إعفاء الموزع من تحسين البطارية.
  • onNewEndpoint يرسل العنوان والمفتاحين إلى سيرفرك، وonUnregistered يحذفها.
  • سيرفر التطبيق يفحص الحجم، ولا يحذف عند 507، ويحذف عند 404 و410.
  • اختبار حقيقي دوري على جهاز أو محاكي يستقبل رسالة ويؤكد استلامها.

الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • UnifiedPush يكرر فكرة خدمات Google Play: اتصال دائم واحد للهاتف كله، لكن عبر موزع وسيرفر يختارهما المستخدم أو مؤسسته.
  • من جهة سيرفرك هو Web Push نفسه، والسكربت الذي أرسل إلى ntfy على سيرفرنا أرسل دون تغيير إلى بوابة FCM المضمنة.
  • الحلقة الضعيفة هي الموزع على الهاتف: تحت تحسين البطارية لم يفتح اتصاله، وبعد الإعفاء وصلت الرسائل حتى في Doze العميق وإلى تطبيق موقوف بالقوة.
  • ntfy يقبل ب 200 ما لا يصل: رسالة لعنوان ألغي، ورسالة أكبر من 4096 بايت تقص ولا تفك، فسيرفرك يجب أن يعرف ذلك بنفسه.
  • للتطبيق العام اجمع الموصل مع الموزع المضمن، وللتطبيق الداخلي على أجهزة تديرها اجعل ntfy على سيرفرك الطريق الوحيد.
دليلإشعارات Push بدون Firebase: ما يستبدل وما يبقى عند Appleما الذي تستطيع أن تخرج منه Firebase في إشعارات الويب وAndroid وiPhone، مع مختبر يرسل Web Push بمفاتيحك وUnifiedPush عبر ntfy على سيرفرك.دليلإشعارات المتصفح Web Push وVAPID دون خدمة خارجيةكيف تطلب إذن الإشعارات في اللحظة الصحيحة، وتشفر الرسالة وتوقعها بيدك بحسب RFC 8291 وRFC 8292، وتعرف متى يموت الاشتراك حتى حين ترد الخدمة بالقبول.دليلإشعارات فورية من سيرفرك إلى هاتفك مع ntfyكيف تشغل سيرفر ntfy خاصاً، وتصلك على هاتفك رسالة عندما يمتلئ القرص أو تفشل النسخة الاحتياطية أو ينتهي النشر.دليلntfy أم Gotify أم Novu؟ مقارنة على تنبيه واحدأرسلنا تنبيه فشل النسخة الاحتياطية نفسه إلى ntfy وGotify وNovu، وقسنا زمن وصوله وذاكرة كل أداة وقرصها، لتعرف أيها لتنبيهات فريقك وأيها لإشعارات عملائك.دليلكيف تعمل الإشعارات الفورية Push Notifications؟كيف يصل الإشعار إلى تطبيق مغلق عبر خدمات Apple وGoogle، وما الذي تراه هذه الخدمات من بيانات مستخدميك.دليلMatrix مع Element: محادثة مشفرة بين مؤسستينشغلنا سيرفرين من Synapse متحدين في Docker، أحدهما للشركة والآخر لمكتب التدقيق، وفتحنا بينهما محادثة مشفرة تحققنا منها برموز Emoji، ثم فتشنا قاعدة بيانات كل سيرفر لنرى ما يعرفه.

سجل التحديثات

  • 20 نوفمبر 2026: كتابة المقال، وتنفيذ المختبر على Android 15 في المحاكي 35.4.9 مع ntfy 1.25.2 موزعاً وUP-Example 2.3.1 بنسختي main وfcm، وسيرفر ntfy 2.38.1 في Docker، والإرسال بتشفير RFC 8291 مكتوب بوحدة node:crypto في Node.js 22.14.0.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.