طلب أذونات التشغيل

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

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

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

المبادئ الأساسية

في ما يلي المبادئ الأساسية لطلب الأذونات أثناء وقت التشغيل:

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

سير العمل لطلب الأذونات

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

إذا تبيّن لك أنّ تطبيقك يحتاج إلى تقديم بيان عن أذونات التشغيل وطلبها، أكمِل الخطوات التالية:

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

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

    عليك التحقّق مما إذا كان لديك إذن في كل مرة تُجري فيها عملية تتطلّب هذا الإذن.

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

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

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

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

  8. إذا منح المستخدم الإذن لتطبيقك، يمكنك الوصول إلى data الخاصة بالمستخدم. إذا رفض المستخدم الإذن، يمكنك خفض إصدار تجربته في تطبيقك بشكل ملائم كي يقدّم للمستخدم وظائف بدون المعلومات المحمية بهذا الإذن.

يوضّح الشكل 1 سير العمل ومجموعة القرارات المرتبطة بهذه العملية:

الشكل 1. مخطّط بياني يعرض سير العمل المتعلّق ببيان أذونات وقت التشغيل و طلبها على Android

تحديد ما إذا كان قد سبق أن تم منح تطبيقك الإذن

للتحقّق مما إذا سبق للمستخدم منح تطبيقك إذنًا معيّنًا، نقْل هذا الإذن إلى الأسلوب ContextCompat.checkSelfPermission(). تعرض هذه الطريقة إما PERMISSION_GRANTED أو PERMISSION_DENIED، وذلك حسب ما إذا كان تطبيقك يملك الإذن.

توضيح سبب احتياج تطبيقك إلى الإذن

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

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

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

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

إذا كانت الطريقة ContextCompat.checkSelfPermission() تُرجع PERMISSION_DENIED، اتصل shouldShowRequestPermissionRationale(). إذا كانت هذه الطريقة تعرض القيمة true، عليك عرض واجهة مستخدم تعليمية للمستخدم. في واجهة المستخدم هذه، اشرح سبب احتياج الميزة التي يريد المستخدم تفعيلها إلى إذن معيّن.

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

طلب الأذونات

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

لإجراء ذلك، استخدِم RequestPermission العقد المضمّن في مكتبة AndroidX، حيث تسمح للنظام بإدارة رمز طلب الإذن نيابةً عنك. وبما أنّ استخدام RequestPermission contract يبسط منطقك، فهو الحلول المقترَحة عند الإمكان. ومع ذلك، يمكنك أيضًا إدارة رمز طلب بنفسك إذا لزم الأمر كجزء من طلب الإذن و تضمين رمز الطلب هذا في منطق الاستدعاء الخاص بالإذن.

السماح للنظام بإدارة رمز طلب الإذن

للسماح للنظام بإدارة رمز الطلب المرتبط بطلب الأذونات، أضِف التبعيات على المكتبات التالية في ملفbuild.gradle الوحدة:

يمكنك بعد ذلك استخدام إحدى الفئات التالية:

توضّح الخطوات التالية كيفية استخدام عقد RequestPermission. تتمثّل العملية نفسها تقريبًا في عقد RequestMultiplePermissions.

  1. في منطق إعداد النشاط أو المقتطف، أرسِل عملية تنفيذ ActivityResultCallback في طلب إلى registerForActivityResult(). تحدِّد ActivityResultCallback كيفية تعامل تطبيقك مع استجابة المستخدم لطلب الإذن.

    احتفظ بمرجع إلى القيمة المعروضة من registerForActivityResult()، والتي تكون من النوع ActivityResultLauncher.

  2. لعرض مربّع حوار أذونات النظام عند الضرورة، استخدِم الأسلوب launch() في مثيل ActivityResultLauncher الذي حفظته في الخطوة السابقة.

    بعد استدعاء launch()، يظهر مربّع حوار أذونات النظام. عندما يحدّد المستخدم خيارًا، يستدعي النظام بشكل غير متزامن عملية تنفيذ ActivityResultCallback التي حدّدتها في الخطوة السابقة.

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

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

يوضّح المقتطف التالي من الرمز البرمجي كيفية معالجة استجابة الأذونات:

Kotlin

// Register the permissions callback, which handles the user's response to the
// system permissions dialog. Save the return value, an instance of
// ActivityResultLauncher. You can use either a val, as shown in this snippet,
// or a lateinit var in your onAttach() or onCreate() method.
val requestPermissionLauncher =
    registerForActivityResult(RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Permission is granted. Continue the action or workflow in your
            // app.
        } else {
            // Explain to the user that the feature is unavailable because the
            // feature requires a permission that the user has denied. At the
            // same time, respect the user's decision. Don't link to system
            // settings in an effort to convince the user to change their
            // decision.
        }
    }

Java

// Register the permissions callback, which handles the user's response to the
// system permissions dialog. Save the return value, an instance of
// ActivityResultLauncher, as an instance variable.
private ActivityResultLauncher<String> requestPermissionLauncher =
    registerForActivityResult(new RequestPermission(), isGranted -> {
        if (isGranted) {
            // Permission is granted. Continue the action or workflow in your
            // app.
        } else {
            // Explain to the user that the feature is unavailable because the
            // feature requires a permission that the user has denied. At the
            // same time, respect the user's decision. Don't link to system
            // settings in an effort to convince the user to change their
            // decision.
        }
    });

توضِّح هذه المقتطفات من الرموز البرمجية العملية المقترَحة للتحقّق من إذن وطلب إذن من المستخدم عند الضرورة:

Kotlin

when {
    ContextCompat.checkSelfPermission(
            CONTEXT,
            Manifest.permission.REQUESTED_PERMISSION
            ) == PackageManager.PERMISSION_GRANTED -> {
        // You can use the API that requires the permission.
    }
    ActivityCompat.shouldShowRequestPermissionRationale(
            this, Manifest.permission.REQUESTED_PERMISSION) -> {
        // In an educational UI, explain to the user why your app requires this
        // permission for a specific feature to behave as expected, and what
        // features are disabled if it's declined. In this UI, include a
        // "cancel" or "no thanks" button that lets the user continue
        // using your app without granting the permission.
        showInContextUI(...)
    }
    else -> {
        // You can directly ask for the permission.
        // The registered ActivityResultCallback gets the result of this request.
        requestPermissionLauncher.launch(
                Manifest.permission.REQUESTED_PERMISSION)
    }
}

Java

if (ContextCompat.checkSelfPermission(
        CONTEXT, Manifest.permission.REQUESTED_PERMISSION) ==
        PackageManager.PERMISSION_GRANTED) {
    // You can use the API that requires the permission.
    performAction(...);
} else if (ActivityCompat.shouldShowRequestPermissionRationale(
        this, Manifest.permission.REQUESTED_PERMISSION)) {
    // In an educational UI, explain to the user why your app requires this
    // permission for a specific feature to behave as expected, and what
    // features are disabled if it's declined. In this UI, include a
    // "cancel" or "no thanks" button that lets the user continue
    // using your app without granting the permission.
    showInContextUI(...);
} else {
    // You can directly ask for the permission.
    // The registered ActivityResultCallback gets the result of this request.
    requestPermissionLauncher.launch(
            Manifest.permission.REQUESTED_PERMISSION);
}

إدارة رمز طلب الأذونات بنفسك

كبديل عن السماح للنظام بإدارة رمز طلب الإذن، يمكنك إدارة رمز طلب الإذن بنفسك. لإجراء ذلك، أدرِج رمز الطلب في مكالمة إلى requestPermissions().

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

Kotlin

when {
    ContextCompat.checkSelfPermission(
            CONTEXT,
            Manifest.permission.REQUESTED_PERMISSION
            ) == PackageManager.PERMISSION_GRANTED -> {
        // You can use the API that requires the permission.
        performAction(...)
    }
    ActivityCompat.shouldShowRequestPermissionRationale(
            this, Manifest.permission.REQUESTED_PERMISSION) -> {
        // In an educational UI, explain to the user why your app requires this
        // permission for a specific feature to behave as expected, and what
        // features are disabled if it's declined. In this UI, include a
        // "cancel" or "no thanks" button that lets the user continue
        // using your app without granting the permission.
        showInContextUI(...)
    }
    else -> {
        // You can directly ask for the permission.
        requestPermissions(CONTEXT,
                arrayOf(Manifest.permission.REQUESTED_PERMISSION),
                REQUEST_CODE)
    }
}

Java

if (ContextCompat.checkSelfPermission(
        CONTEXT, Manifest.permission.REQUESTED_PERMISSION) ==
        PackageManager.PERMISSION_GRANTED) {
    // You can use the API that requires the permission.
    performAction(...);
} else if (ActivityCompat.shouldShowRequestPermissionRationale(
        this, Manifest.permission.REQUESTED_PERMISSION)) {
    // In an educational UI, explain to the user why your app requires this
    // permission for a specific feature to behave as expected, and what
    // features are disabled if it's declined. In this UI, include a
    // "cancel" or "no thanks" button that lets the user continue
    // using your app without granting the permission.
    showInContextUI(...);
} else {
    // You can directly ask for the permission.
    requestPermissions(CONTEXT,
            new String[] { Manifest.permission.REQUESTED_PERMISSION },
            REQUEST_CODE);
}

بعد أن يردّ المستخدم على مربّع حوار أذونات النظام، يشغِّل النظام تنفيذ تطبيقك onRequestPermissionsResult(). يُرسِل النظام ردّ العميل إلى مربّع حوار الإذن، بالإضافة إلى رمز الطلب الذي حدّدته، كما هو موضّح في مقتطف الرمز البرمجي التالي:

Kotlin

override fun onRequestPermissionsResult(requestCode: Int,
        permissions: Array<String>, grantResults: IntArray) {
    when (requestCode) {
        PERMISSION_REQUEST_CODE -> {
            // If request is cancelled, the result arrays are empty.
            if ((grantResults.isNotEmpty() &&
                    grantResults[0] == PackageManager.PERMISSION_GRANTED)) {
                // Permission is granted. Continue the action or workflow
                // in your app.
            } else {
                // Explain to the user that the feature is unavailable because
                // the feature requires a permission that the user has denied.
                // At the same time, respect the user's decision. Don't link to
                // system settings in an effort to convince the user to change
                // their decision.
            }
            return
        }

        // Add other 'when' lines to check for other
        // permissions this app might request.
        else -> {
            // Ignore all other requests.
        }
    }
}

Java

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions,
        int[] grantResults) {
    switch (requestCode) {
        case PERMISSION_REQUEST_CODE:
            // If request is cancelled, the result arrays are empty.
            if (grantResults.length > 0 &&
                    grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                // Permission is granted. Continue the action or workflow
                // in your app.
            }  else {
                // Explain to the user that the feature is unavailable because
                // the feature requires a permission that the user has denied.
                // At the same time, respect the user's decision. Don't link to
                // system settings in an effort to convince the user to change
                // their decision.
            }
            return;
        }
        // Other 'case' lines to check for other
        // permissions this app might request.
    }
}

طلب أذونات تحديد الموقع الجغرافي

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

الموقع الجغرافي في المقدّمة

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

  • تتيح ميزة في تطبيق التنقّل للمستخدمين الحصول على اتّجاهات مفصّلة.
  • تتيح ميزة في تطبيق مراسلة للمستخدمين مشاركة موقعهم الجغرافي الحالي مع مستخدم آخر.

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

  • إذا كان هناك نشاط ينتمي إلى تطبيقك مرئيًا

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

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

    <!-- Recommended for Android 9 (API level 28) and lower. -->
<!-- Required for Android 10 (API level 29) and higher. -->
<service
    android:name="MyNavigationService"
    android:foregroundServiceType="location" ... >
    <!-- Any inner elements go here. -->
</service>

يمكنك الإعلان عن الحاجة إلى استخدام الموقع الجغرافي في المقدّمة عندما يطلب تطبيقك إذن ACCESS_COARSE_LOCATION أو إذن ACCESS_FINE_LOCATION ، كما هو موضّح في المقتطف التالي:

<manifest ... >
  <!-- Include this permission any time your app needs location information. -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

رصد الموقع الجغرافي في الخلفية

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

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

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

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

<manifest ... >
  <!-- Required only when requesting background location access on
       Android 10 (API level 29) and higher. -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>

التعامل مع رفض الإذن

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

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

    • عرض رسالة في المكان الذي كان من المفترض أن تظهر فيه نتائج الميزة أو بياناتها
    • عرض زر مختلف يحتوي على رمز خطأ ولون

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

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

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

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

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

لتوفير أفضل تجربة للمستخدم عند طلب أذونات التطبيق، يمكنك أيضًا الاطّلاع على أفضل الممارسات المتعلّقة بأذونات التطبيقات.

فحص حالة الرفض عند الاختبار وتصحيح الأخطاء

لتحديد ما إذا تم رفض أذونات التطبيق نهائيًا (لأغراض تصحيح الأخطاء والاختبار)، استخدِم الأمر التالي:

adb shell dumpsys package PACKAGE_NAME

حيث يكون PACKAGE_NAME هو اسم الحزمة المطلوب فحصها.

يحتوي ناتج الأمر على أقسام تبدو على النحو التالي:

...
runtime permissions:
  android.permission.POST_NOTIFICATIONS: granted=false, flags=[ USER_SENSITIVE_WHEN_GRANTED|USER_SENSITIVE_WHEN_DENIED]
  android.permission.ACCESS_FINE_LOCATION: granted=false, flags=[ USER_SET|USER_FIXED|USER_SENSITIVE_WHEN_GRANTED|USER_SENSITIVE_WHEN_DENIED]
  android.permission.BLUETOOTH_CONNECT: granted=false, flags=[ USER_SENSITIVE_WHEN_GRANTED|USER_SENSITIVE_WHEN_DENIED]
...

يتم وضع علامة على الأذونات التي رفضها المستخدم مرّة واحدة من خلال USER_SET. يتم وضع علامة على الأذونات التي تم رفضها نهائيًا من خلال النقر على رفض مرتين من قِبل USER_FIXED.

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

adb shell pm clear-permission-flags PACKAGE_NAME PERMISSION_NAME user-set user-fixed

PERMISSION_NAME هو اسم الإذن الذي تريد إعادة ضبطه.

للاطّلاع على قائمة كاملة بأذونات تطبيقات Android، انتقِل إلى صفحة مرجع واجهة برمجة التطبيقات للأذونات.

الأذونات لمرة واحدة

الخيار &quot;هذه المرة فقط&quot; هو الزر الثاني من بين ثلاثة أزرار في مربّع الحوار.
الشكل 2. مربّع حوار النظام الذي يظهر عندما يطلب أحد التطبيقات إذنًا لمرة واحدة

اعتبارًا من Android 11 (المستوى 30 من واجهة برمجة التطبيقات)، عندما يطلب تطبيقك إذنًا مرتبطًا بالموقع الجغرافي أو الميكروفون أو الكاميرا، يحتوي مربّع حوار الأذونات الموجَّه للمستخدمين على خيار يُسمى هذه المرة فقط، كما هو موضّح في الشكل 2. إذا اختار المستخدم هذا الخيار في المربّع الحواري، يحصل تطبيقك على إذن مؤقت لمرة واحدة.

يمكن لتطبيقك بعد ذلك الوصول إلى البيانات ذات الصلة لفترة زمنية تعتمد على سلوك تطبيقك وإجراءات المستخدم:

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

إنهاء عملية التطبيق عند إبطال الإذن

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

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

إعادة ضبط الأذونات غير المستخدمة

يقدّم Android عدة طرق لإعادة ضبط أذونات وقت التشغيل غير المستخدَمة إلى حالتها التلقائية، وهي "محظور":

إزالة إذن وصول التطبيق

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

لإزالة إذن التشغيل، نقْل اسم هذا الإذن إلى revokeSelfPermissionOnKill(). لإزالة إذن الوصول إلى مجموعة من أذونات وقت التشغيل في الوقت نفسه، نقْل مجموعة من أسماء الأذونات إلى revokeSelfPermissionsOnKill(). تتم عملية إزالة الأذونات بشكل غير متزامن وتؤدي إلى إنهاء جميع العمليات المرتبطة بـ UID لتطبيقك.

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

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

إعادة ضبط أذونات التطبيقات غير المستخدَمة تلقائيًا

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

طلب أن تصبح المعالِج التلقائي إذا لزم الأمر

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

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

منح جميع أذونات وقت التشغيل لأغراض الاختبار

لمنح جميع أذونات وقت التشغيل تلقائيًا عند تثبيت تطبيق على جهاز محاكاة أو جهاز اختبار، استخدِم الخيار -g للأمر adb shell install ، كما هو موضّح في مقتطف التعليمات البرمجية التالي:

adb shell install -g PATH_TO_APK_FILE

مصادر إضافية

للحصول على معلومات إضافية حول الأذونات، يُرجى قراءة المقالات التالية:

لمعرفة المزيد من المعلومات عن طلب الأذونات، راجِع عيّنات الأذونات.

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

السابق
تقديم أذونات التطبيقات
التالي
طلب أذونات خاصة