DEV Community

Cover image for android_special_permissions: واجهة واحدة لصلاحيات الوصول الخاص في Android
Abdeldjalil Chougui
Abdeldjalil Chougui

Posted on Originally published at abdeldjalilchougui.biz

android_special_permissions: واجهة واحدة لصلاحيات الوصول الخاص في Android

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

بالنسبة لمطوّر Flutter، هذا يعني ثلاث مهام منفصلة لكل صلاحية: معرفة إن كان الوصول ممنوحًا، وإيجاد شاشة الإعدادات الصحيحة لهذا الإصدار من Android، ومعرفة ما حدث عندما يعود المستخدم. ولكل صلاحية طريقة فحص خاصة، وintent خاص، ومستوى API خاص. الإضافة android_special_permissions تضع كل ذلك خلف واجهة (API) صغيرة واحدة.

ماذا تقدّم

حالة 13 صلاحية خاصة. الدالة status() تُرجع granted أو denied أو notApplicable. القيمة الأخيرة تعني أن مستوى API في الجهاز لا يحتوي هذا الزر أصلًا. القائمة تشمل usageAccess وoverlay وaccessibilityService وnotificationListener وignoreBatteryOptimizations وexactAlarm وinstallUnknownApps وallFilesAccess وwriteSettings وdoNotDisturb وfullScreenIntent وpictureInPicture وbackgroundLocation.

أدقّ شاشة إعدادات متاحة. الدالة openSettings() تجرّب الشاشة الخاصة بتطبيقك حيث يدعمها Android، ثم القائمة العامة، ثم صفحة معلومات التطبيق (App info)، ثم الصفحة الرئيسية للإعدادات. كل intent مرشّح يُفحص بـ resolveActivity قبل تشغيله، فلا ينهار الاستدعاء على جهاز تنقصه إحدى الشاشات.

افتح، انتظر، أعد الفحص. الدالة request() تفتح الشاشة، تنتظر حتى يعود تطبيقك إلى الواجهة، تفحص الحالة من جديد وتُرجعها. تعتمد على ربط ActivityAware ومراقب لدورة الحياة (lifecycle observer)، وتصمد أمام تغيّرات الإعداد (configuration changes)، وتفشل بالخطأ activityNotAttached إذا اختفت الـ activity. وإذا كانت الحالة granted أو notApplicable من البداية، ترجع فورًا دون فتح أي شيء.

أدوار التطبيق الافتراضي. الدالتان roleStatus() وrequestRole() تغطيان أدوار الهاتف (dialer) والرسائل (SMS) والشاشة الرئيسية (home) والمتصفح والمساعد عبر RoleManager. وrequestRole() تنتظر نتيجة الـ activity.

اكتشاف خدمة الوصول (accessibility service). يحفظ Android الخدمات المفعّلة في ENABLED_ACCESSIBILITY_SERVICES، واسم المكوّن قد يُكتب بصيغة قصيرة (pkg/.Svc) أو طويلة (pkg/pkg.Svc). الإضافة تقرأ الصيغتين.

لا صلاحيات من عندها. الإضافة لا تصرّح بأي شيء في الـ manifest الخاص بها. تطبيقك يصرّح فقط بالصلاحيات التي يحتاجها فعلًا.

طريقة الاستعمال

أضِفها من GitHub:

dependencies:
  android_special_permissions:
    git: https://github.com/AbdeldjalilChougui/android_special_permissions
Enter fullscreen mode Exit fullscreen mode

قيمة minSdk للإضافة هي 21. في ملف AndroidManifest.xml لتطبيقك، صرّح بالصلاحيات التي تقف خلف أنواع الوصول التي تستعملها، مثل PACKAGE_USAGE_STATS للوصول إلى بيانات الاستعمال أو SYSTEM_ALERT_WINDOW للرسم فوق التطبيقات. من دون هذا التصريح، أغلب شاشات الإعدادات لن تُظهر تطبيقك في قائمتها. وفي الـ README جدول فيه سطر الـ manifest لكل صلاحية.

ثم في Dart:

import 'package:android_special_permissions/android_special_permissions.dart';

final permissions = AndroidSpecialPermissions();

Future<void> ensureUsageAccess() async {
  final status = await permissions.status(SpecialPermission.usageAccess);
  if (status == SpecialPermissionStatus.denied) {
    // Opens "Usage access", waits for the user to return, re-checks.
    final after = await permissions.request(SpecialPermission.usageAccess);
    print('usage access: ${after.name}');
  }
}

Future<void> batteryAndRoles() async {
  // Direct "allow" dialog if REQUEST_IGNORE_BATTERY_OPTIMIZATIONS is declared,
  // otherwise the list screen.
  await permissions.request(SpecialPermission.ignoreBatteryOptimizations);

  final sms = await permissions.roleStatus(AndroidRole.sms);
  if (sms == SpecialPermissionStatus.denied) {
    await permissions.requestRole(AndroidRole.sms);
  }
}
Enter fullscreen mode Exit fullscreen mode

لخدمة الوصول أو مستمع الإشعارات (notification listener)، مرّر اسم صنف الخدمة في serviceClassName، إما بالاسم الكامل أو نسبيًّا بنقطة في البداية ('.MyAccessibilityService').

الأخطاء لها أنواع محددة:

try {
  await permissions.request(SpecialPermission.exactAlarm);
} on SpecialPermissionException catch (e) {
  if (e.code == SpecialPermissionErrorCode.activityNotAttached) {
    // No foreground activity, or it was destroyed while waiting.
  }
}
Enter fullscreen mode Exit fullscreen mode

لا يمكن أن ينتظر أكثر من استدعاء واحد لـ request() أو requestRole() في الوقت نفسه. الاستدعاء الثاني يفشل بالخطأ requestInProgress.

كيف تبدو كل صلاحية

في الـ README جدول كامل: سطر الـ manifest، وإصدار Android الذي يوجد فيه الزر، وما يراه المستخدم، وملاحظة عن Google Play. هذه بعض الأسطر التي يحسن أن تعرفها قبل البدء:

  • overlay موجودة من API 23. ومن Android 11 فصاعدًا يتجاهل النظام عنوان الحزمة (package URI) ويعرض قائمة كل التطبيقات.
  • exactAlarm موجودة من API 31، وهي مرفوضة افتراضيًّا في Android 14 وما بعده للتثبيتات الجديدة.
  • allFilesAccess موجودة من API 30 وتحتاج تصريحًا (declaration) في Play، وهي مخصصة لمديري الملفات والنسخ الاحتياطي ومضادات الفيروسات وما يشبهها.
  • ignoreBatteryOptimizations لها سلوكان. request() تعرض نافذة النظام المباشرة، وهذه تحتاج REQUEST_IGNORE_BATTERY_OPTIMIZATIONS ومقيّدة في Play. وopenSettings() تعرض قائمة "Battery optimization"، ولا تحتاج أي صلاحية.
  • fullScreenIntent موجودة من API 34. تُمنح تلقائيًّا لتطبيقات الاتصال والمنبّهات فقط، وباقي التطبيقات عليها أن ترسل المستخدم إلى الإعدادات.
  • الأدوار تحتاج API 29 أو أحدث. ويرفض Android أدوار home وbrowser وassistant إذا لم يصرّح التطبيق بالـ intent filters المناسبة.

ملاحظات Play في ذلك الجدول هي تلخيص المؤلف وقت الكتابة. المرجع المعتمد هو مركز سياسات Play، فراجعه قبل النشر.

الموقع في الخلفية

ACCESS_BACKGROUND_LOCATION صلاحية runtime عادية، لذلك تكتفي الإضافة بإعطاء حالتها. أما request() وopenSettings() فترميان الخطأ notSupported معها. يشرح الـ README المسار على خطوتين باستعمال permission_handler: اطلب الموقع في الواجهة أولًا، ثم اشرح لماذا تحتاجه طول الوقت واطلب Permission.locationAlways. في Android 11 وما بعده، الخطوة الثانية ترسل المستخدم إلى صفحة الموقع الخاصة بالتطبيق. وفي API 21 إلى 28 لا توجد صلاحية خلفية منفصلة، فتكون الحالة notApplicable.

ما يجب معرفته

  • Android فقط. على المنصات الأخرى كل الحالات notApplicable ولا يُفتح شيء.
  • notApplicable تعني "لا يوجد زر". في API 21 و22، الصلاحيات التي خلف overlay وwriteSettings وأمثالهما تُمنح عند التثبيت إذا صُرّح بها. الإضافة لا تُبلّغ عن ذلك.
  • الصلاحية غير المصرّح بها تُقرأ denied، وقد لا تُظهر شاشة الإعدادات تطبيقك.
  • request() تكتمل عند أول عودة للتطبيق بعد توقفه المؤقت. إن عاد المستخدم من طريق آخر، تحصل على الحالة في تلك اللحظة.
  • قد يقتل Android عملية تطبيقك. عند سحب بعض أنواع الوصول يقتل Android التطبيق (لوحظ ذلك مع "Install unknown apps" على المحاكي، وAndroid يوثّق الشيء نفسه لـ "Alarms & reminders"). عندها لا يكتمل request() المعلّق أبدًا، فأعد فحص الحالة عند التشغيل التالي.
  • تطبيقات الإعدادات تختلف بين المصنّعين. سلسلة البدائل تنتهي دائمًا عند معلومات التطبيق ثم الصفحة الرئيسية للإعدادات، لكن الشاشة الأدقّ قد تكون غائبة في بعض الأجهزة.
  • شاشتان لهما وضع خاص. صفحة تفاصيل خدمة الوصول تحتاج صلاحية نظام لا تملكها التطبيقات العادية، فتحصل هذه على شاشة Accessibility العامة. وشاشة picture-in-picture ليست action عامًّا في الـ SDK؛ الإضافة تجرّبها فقط إذا وُجدت، وتنتقل إلى البديل في غير ذلك.
  • حالة picture-in-picture هي حالة AppOps. لا تتحقق من أن إحدى الـ activities عندك تصرّح بـ supportsPictureInPicture.
  • واجهات التطبيق الافتراضي القديمة غير مغطّاة. الأدوار تعمل من API 29.
  • ما تم اختباره. واجهة Dart لها اختبارات بـ MethodChannel وهمي، ومنطق Kotlin الخالص (تحليل أسماء المكوّنات، قواعد مستويات API، ترتيب بدائل الـ intents، تتبّع العودة) له اختبارات JUnit. ولتطبيق المثال اختبار تكامل على المحاكي يبدّل كل وصول عبر adb ويتحقق من كل حالة، وكل شاشة إعدادات، ودورة request() كاملة. الاختبار تم على محاكي Android (صورة Pixel 10، API 37). لم تُختبر الإضافة بعد على هاتف حقيقي ولا على تطبيقات إعدادات المصنّعين.

لماذا بنيتها

نافذة صلاحيات runtime مشكلة محلولة في Flutter. أما أنواع الوصول الخاص فلا تغطيها تلك النافذة، وكل واحد منها بحث صغير قائم بذاته: أي قيمة في AppOps أو Settings تُقرأ، وأي intent يُرسل، وهل يُحترم عنوان الحزمة في هذا الإصدار من Android، وما العمل إن لم توجد الشاشة. ثم يأتي الجزء الذي يتجاوزه أغلب الكود: معرفة متى عاد المستخدم وماذا اختار.

أردت مكانًا واحدًا لهذه المعرفة. enum واحد للصلاحيات، ونوع حالة واحد فيه notApplicable صريحة، وسلسلة بدائل تنتهي دائمًا عند شاشة ما، وrequest() تُرجع الحالة الجديدة ليكمل التطبيق عمله. وجدول ملاحظات سياسة Play موجود في الـ README للسبب نفسه: عدة أنواع من هذا الوصول تحتاج تصريحًا في Play، والأفضل أن تعرف ذلك قبل كتابة الميزة.

الكود

الكود، وجدول الصلاحيات الكامل، وتطبيق المثال، والاختبارات موجودة على GitHub: https://github.com/AbdeldjalilChougui/android_special_permissions. الرخصة MIT، والـ issues والـ pull requests مرحّب بها.


نُشر في الأصل على abdeldjalilchougui.biz.

Top comments (0)