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

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

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

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

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

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

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

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

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

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

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

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

يختار المستخدم "السماح"

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

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

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

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

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

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

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

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

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

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

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

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

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

في هذه الحالة، يعتبر النظام تطبيقك "تطبيقًا حاليًا"، لذا يمنح النظام الإذن تلقائيًا لتطبيقك حتى يتمكّن من مواصلة إرسال الإشعارات.

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

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

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

الإعفاءات

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

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

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

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

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

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

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

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

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

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

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 أو إصدار أقدم، ثم تمت ترقية الجهاز إلى الإصدار 13 من نظام التشغيل Android أو إصدار أحدث:
```
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 أو إصدار أقدم، ثم تمت ترقية الجهاز إلى الإصدار 13 من نظام التشغيل Android أو إصدار أحدث:
```
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.

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

بعد تسجيل المستخدم الدخول، تظهر له دعوة لتلقّي إشعارات بشأن تعديلات الرحلة. بعد أن يضغط المستخدم على زر "موافق"، يطلب التطبيق الإذن الجديد، ما يؤدي إلى ظهور مربّع حوار النظام — **الشكل 1.** سير عمل مقترَح يستند إلى المستخدم لطلب إذن إرسال الإشعارات لا تكون الشاشة الوسطى ضرورية إلا إذا عرضت الدالة `shouldShowRequestPermissionRationale()` القيمة `true`.

طلب الإذن

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

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

Kotlin

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().

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

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