إذن تشغيل الإشعارات

يتيح الإصدار 13 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 33) والإصدارات الأحدث إذن التشغيل لإرسال إشعارات غير معفاة (بما في ذلك الخدمات التي تعمل في المقدّمة (FGS)) من تطبيق: POST_NOTIFICATIONS. يساعد هذا التغيير المستخدمين في التركيز على الإشعارات الأكثر أهمية بالنسبة إليهم.

ننصحك بشدة باستهداف الإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث في أقرب وقت ممكن للاستفادة من ميزات التحكّم والمرونة الإضافية التي توفّرها هذه الميزة. إذا واصلت استهداف الإصدار 12L (المستوى 32 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم، ستفقد بعض المرونة في ما يتعلّق بطلب الإذن في سياق وظائف تطبيقك.

تضمين الإذن في نموذج البيان

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

يظهر الإذن الذي عليك تحديده في ملف بيان التطبيق في مقتطف الرمز التالي:

<manifest ...>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    <application ...>
        ...
    </application>
</manifest>

تعتمد إمكانات التطبيق على اختيار المستخدم في مربّع حوار الأذونات

في مربّع الحوار هذا، تتوفّر للمستخدمين الإجراءات التالية:

• انقر على السماح
• انقر على عدم السماح
• مرِّر سريعًا بعيدًا عن مربّع الحوار بدون الضغط على أي من الزرّين

توضِّح الأقسام التالية سلوك تطبيقك استنادًا إلى الإجراء الذي يتّخذه المستخدم.

ينقر المستخدم على "السماح"

إذا اختار المستخدم الخيار السماح، يمكن لتطبيقك إجراء ما يلي:

• إرسال إشعارات تم السماح بجميع قنوات الإشعارات.
• نشر إشعارات ذات صلة بالخدمات التي تعمل في المقدّمة تظهر هذه الإشعارات في درج الإشعارات.

ينقر المستخدم على "عدم السماح"

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

مرّر المستخدم سريعًا بعيدًا عن مربّع الحوار

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

التأثيرات على التطبيقات المثبَّتة حديثًا

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

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

• إذا كان تطبيقك يستهدف الإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث، سيتحكّم تطبيقك بشكل كامل في وقت عرض مربّع حوار الأذونات. استغِل هذه الفرصة لتوضيح سبب احتياج التطبيق إلى هذا الإذن للمستخدمين، وتشجيعهم على منحه.
• إذا كان تطبيقك يستهدف المستوى 12L من واجهة برمجة التطبيقات (المستوى 32 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم، يعرض النظام مربّع حوار الأذونات عند بدء تطبيقك لنشاط ما لأول مرة بعد إنشاء قناة إشعارات، أو عندما يبدأ تطبيقك نشاطًا ثم ينشئ قناة الإشعارات الأولى. يحدث ذلك عادةً عند بدء تشغيل التطبيق. في التطبيقات ذات النشاط الفردي، مثل معظم تطبيقات Compose، يعرض النظام مربع الحوار عند بدء MainActivity.

تأثيرات التحديثات على التطبيقات الحالية

للحدّ من المشاكل المرتبطة بإذن إرسال الإشعارات، يمنح النظام تلقائيًا الإذن مسبقًا لجميع التطبيقات المؤهَّلة عندما يرقّي المستخدم جهازه إلى الإصدار 13 من نظام التشغيل Android أو إصدار أحدث. بعبارة أخرى، يمكن لهذه التطبيقات مواصلة إرسال الإشعارات إلى المستخدمين، ولن تظهر للمستخدمين مطالبة بمنح إذن التشغيل.

متطلبات الأهلية لمنح الأذونات مسبقًا

لكي يكون تطبيقك مؤهَّلاً للحصول على إذن تلقائي مسبق، يجب أن يتضمّن قناة إشعارات حالية وألا يكون المستخدم قد أوقف إشعاراته بشكل صريح على جهاز يعمل بالإصدار 12L أو إصدار أقدم.

إذا أوقف المستخدم الإشعارات لتطبيقك على جهاز يعمل بالإصدار 12L أو إصدار أقدم، سيظل هذا الإيقاف ساريًا عند ترقية الجهاز إلى الإصدار Android 13 أو إصدار أحدث.

الإعفاءات

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

جلسات الوسائط

يُستثنى من هذا التغيير في السلوك الإشعارات ذات الصلة بجلسات الوسائط.

التطبيقات التي تم ضبط إعداداتها لإدارة المكالمات الهاتفية ذاتيًا

إذا كان تطبيقك يضبط نفسه لإدارة المكالمات الهاتفية ذاتيًا، لن تحتاج إلى إذن POST_NOTIFICATIONS لكي يرسل تطبيقك إشعارات تستخدم نمط الإشعارات Notification.CallStyle.

يعتبر النظام أنّ تطبيقك قد أعدّ نفسه لإدارة المكالمات الهاتفية ذاتيًا إذا كان يتبع ما يلي:

1. توضّح هذه السمة إذن MANAGE_OWN_CALLS.
2. تنفّذ هذه الفئة واجهة ConnectionService.
3. يتم التسجيل لدى مقدّم خدمة الاتصالات على الجهاز من خلال الاتصال بالرقم registerPhoneAccount().

اختبار تطبيقك

يمكنك تقييم تأثير إذن إرسال الإشعارات في تطبيقك عند استخدامه لأول مرة على جهاز يعمل بنظام التشغيل Android 13 أو إصدار أحدث. تتيح لك مجموعات أوامر Android Debug Bridge (ADB) التالية محاكاة التسلسلات الأكثر شيوعًا لخيارات المستخدمين وعمليات ترقية الأجهزة بدون الحاجة إلى إعادة ضبط جهاز الاختبار:

• تم تثبيت التطبيق حديثًا على جهاز يعمل بالإصدار 13 من نظام التشغيل Android أو إصدار أحدث:

  adb shell pm revoke PACKAGE_NAME android.permission.POST_NOTIFICATIONS
  adb shell pm clear-permission-flags PACKAGE_NAME \
    android.permission.POST_NOTIFICATIONS user-set
  adb shell pm clear-permission-flags PACKAGE_NAME \
    android.permission.POST_NOTIFICATIONS user-fixed

• يظل المستخدم يتلقّى الإشعارات إذا تم تثبيت التطبيق على جهاز يعمل بالإصدار 12L أو إصدار أقدم، ثم تمت ترقية الجهاز إلى نظام التشغيل Android 13 أو إصدار أحدث:

  adb shell pm grant PACKAGE_NAME android.permission.POST_NOTIFICATIONS
  adb shell pm set-permission-flags PACKAGE_NAME \
    android.permission.POST_NOTIFICATIONS user-set
  adb shell pm clear-permission-flags PACKAGE_NAME \
    android.permission.POST_NOTIFICATIONS user-fixed

• إذا أوقف المستخدم الإشعارات يدويًا عند تثبيت التطبيق على جهاز يعمل بالإصدار 12L أو إصدار أقدم، ثم تمت ترقية الجهاز إلى الإصدار Android 13 أو إصدار أحدث:

  adb shell pm revoke PACKAGE_NAME android.permission.POST_NOTIFICATIONS
  adb shell pm set-permission-flags PACKAGE_NAME \
    android.permission.POST_NOTIFICATIONS user-set
  adb shell pm clear-permission-flags PACKAGE_NAME \
    android.permission.POST_NOTIFICATIONS user-fixed

أفضل الممارسات

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

تعديل إصدار حزمة تطوير البرامج (SDK) المستهدَف في تطبيقك

لمنح تطبيقك المزيد من المرونة بشأن وقت ظهور مربّع حوار الأذونات، حدِّث تطبيقك لكي يستهدف الإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث.

الانتظار قبل عرض طلب الحصول على إذن إرسال الإشعارات

قبل أن تطلب من المستخدمين منح أي أذونات، دعهم يتعرّفون على تطبيقك.

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

• ينقر المستخدم على زر "جرس التنبيه".
• يختار المستخدم متابعة حساب شخص ما على وسائل التواصل الاجتماعي.
• يرسل المستخدم طلبًا لتوصيل الطعام.

يعرض الشكل 1 سير عمل مقترَحًا لطلب إذن تلقّي الإشعارات. ما لم تعرض الدالة shouldShowRequestPermissionRationale() القيمة true، لن يحتاج تطبيقك إلى عرض الشاشة الوسطى التي تتضمّن نص العنوان "تلقّي إشعارات". في Compose، يمكنك العثور على Activity من خلال الوصول إلى LocalContext.current وتحويله إلى Activity.

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

طلب الإذن في Compose

لطلب الإذن ضمن واجهة مستخدم Compose، استخدِم واجهة برمجة التطبيقات rememberLauncherForActivityResult() مع العقد ActivityResultContracts.RequestPermission().

يوضّح المقتطف التالي كيفية طلب إذن إرسال الإشعارات استجابةً لتفاعل المستخدم:

val context = LocalContext.current
val permissionLauncher = rememberLauncherForActivityResult(
    ActivityResultContracts.RequestPermission()
) { isGranted ->
    if (isGranted) {
        // Permission granted, you can now send notifications.
    } else {
        // Permission denied, handle accordingly.
    }
}

// ... in your UI ...
Button(onClick = {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        permissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
    }
}) {
    Text("Enable Notifications")
}

طلب الإذن في السياق

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

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

التحقّق مما إذا كان بإمكان تطبيقك إرسال الإشعارات

قبل أن يرسل تطبيقك إشعارًا، تأكَّد مما إذا كان المستخدم قد فعّل الإشعارات لتطبيقك. ولإجراء ذلك، استدعِ الدالة areNotificationsEnabled().

استخدام الإذن بمسؤولية

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