تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تحديد ما إذا كان تطبيقك قد سبق له الحصول على الإذن

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

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

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

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

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

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

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

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

طلب الأذونات

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

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

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

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

‫androidx.activity، الإصدار 1.2.0 أو الإصدارات الأحدث
‫androidx.fragment، الإصدار 1.3.0 أو إصدار أحدث

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

لطلب إذن واحد، استخدِم الرمز RequestPermission.
لطلب أذونات متعددة في الوقت نفسه، استخدِم RequestMultiplePermissions.

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

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

احتفظ بمرجع إلى القيمة المعروضة من registerForActivityResult()، والتي تكون من النوع ActivityResultLauncher.
لعرض مربّع حوار أذونات النظام عند الضرورة، استدعِ طريقة 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.
    }
}

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

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

الموقع الجغرافي أثناء ظهور التطبيق على الشاشة

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

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

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

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

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


<service
    android:name="MyNavigationService"
    android:foregroundServiceType="location" ... >
    
</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 API. في ما يلي بعض الأمثلة:

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

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

على الإصدار 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، انتقِل إلى صفحة مرجع واجهة برمجة التطبيقات الخاصة بالأذونات.

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

الخيار المسمّى "هذه المرة فقط" هو الزر الثاني من بين ثلاثة أزرار في مربّع الحوار. — **الشكل 2.** مربّع حوار النظام الذي يظهر عندما يطلب تطبيق إذنًا لمرة واحدة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

adb shell install -g PATH_TO_APK_FILE

مراجع إضافية

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

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

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

تقديم أذونات التطبيقات

طلب أذونات خاصة