تلقي تحديثات المواقع الجغرافية في Android باستخدام Kotlin

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

عندما يطلب أحد التطبيقات التي تعمل بنظام التشغيل Android 11 الوصول إلى الموقع الجغرافي، يتوفر للمستخدمين أربعة خيارات:

• السماح طوال الوقت
• السماح عند استخدام التطبيق فقط (في Android 10)
• مرة واحدة فقط (في نظام التشغيل Android 11)
• رفض

Android 10

Android 11

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

المتطلبات الأساسية

• الدراية بتطوير نظام Android
• بعض دراية الأنشطة والخدمات والأذونات

المهام التي ستنفِّذها

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

المتطلبات اللازمة

• الإصدار 3.4 من "استوديو Android" أو الإصدارات الأحدث لتشغيل الرمز
• جهاز/محاكي يشغّل معاينة مطوّري البرامج للإصدارين 10 و11 من نظام التشغيل Android

نسخ مشروع المشروع للمبتدئين

للبدء في أسرع وقت ممكن، يمكنك البناء على هذا المشروع للمبتدئين. إذا كان لديك Git مثبتًا، يمكنك تشغيل الأمر التالي:

 git clone https://github.com/googlecodelabs/while-in-use-location

يمكنك الانتقال إلى صفحة GitHub مباشرةً.

إذا لم يكن لديك Git، يمكنك الحصول على المشروع كملف zip:

تنزيل الملف بتنسيق zip

استيراد المشروع

افتح "استوديو Android"، واختَر &quot؛افتَح مشروعًا حاليًا في "استوديو Android"، من شاشة الترحيب وافتح دليل المشروع.

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

في الركن العلوي الأيمن من نافذة المشروع، من المفترض أن ترى شيئًا مثل الصورة أدناه إذا كنت في عرض Android. (إذا كنت في عرض المشروع، ستحتاج إلى توسيع المشروع لعرض العنصر نفسه).

هناك مجلدان (base وcomplete). يُعرف كل منهما باسم "module".

تجدر الإشارة إلى أنّ "استوديو Android" قد يستغرق عدة ثوانٍ لتجميع المشروع في الخلفية للمرة الأولى. وخلال هذه الفترة، ستظهر لك الرسالة التالية في شريط الحالة في أسفل "استوديو Android":

انتظر حتى ينتهي "استوديو Android" من فهرسة وإنشاء المشروع قبل إجراء تغييرات على الرمز. سيسمح هذا الإجراء لتطبيق "استوديو Android" بجلب جميع المكوّنات اللازمة.

إذا ظهرت لك رسالة المطالبة هل تريد إعادة التحميل حتى تدخل تغييرات اللغة حيز التنفيذ؟ أو شيء مشابه، اختَر نعم.

فهم مشروع التفعيل

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

وتشمل المكوّنات الأساسية ما يلي:

• MainActivity: واجهة المستخدم للمستخدم للسماح للتطبيق بالوصول إلى موقع الجهاز
  
• LocationService: خدمة تشترك في تغييرات الموقع الجغرافي وتُلغي الاشتراك فيها، وترقّي نفسها إلى خدمة تعمل في المقدّمة (من خلال إشعار) إذا انتقل المستخدم بعيدًا عن نشاط التطبيق. يمكنك إضافة رمز الموقع الجغرافي هنا.
  
• Util: تضيف وظائف الإضافات للفئة Location وتحفظ الموقع الجغرافي في SharedPreferences (طبقة بيانات مبسّطة).

إعداد المحاكي

للحصول على معلومات حول إعداد محاكي Android، راجِع تشغيل على محاكي.

تنفيذ مشروع المبتدئين

شغِّل تطبيقك.

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

3. لاحظ أن التطبيق التالي يظهر على جهازك:

قد تلاحظ عدم ظهور معلومات عن الموقع الجغرافي في شاشة الإخراج. ذلك لم تتم إضافة رمز الموقع الجغرافي حتى الآن.

المفاهيم

يركّز هذا الدرس التطبيقي على شرح كيفية تلقّي آخر المعلومات عن الموقع الجغرافي، ودعم نظام التشغيل Android 10 وAndroid 11 في النهاية.

ولكن قبل البدء في الترميز، من الأفضل مراجعة الأساسيات.

أنواع الوصول إلى الموقع الجغرافي

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

• السماح عند استخدام التطبيق فقط
• يُنصَح باستخدام هذا الخيار لمعظم التطبيقات. يُعرف هذا التطبيق أيضًا باسم &"أثناء الاستخدام&&;أو &&;عرضاً&;في المقدمة فقط"; أُضيف هذا الخيار في Android 10 ولا يسمح لمطوّري البرامج باسترداد الموقع الجغرافي إلا أثناء استخدام التطبيق بشكل نشط. يُعتبَر التطبيق نشطًا في أي من الحالات التالية:
• إذا كان هناك نشاط مرئي.
• يتم تشغيل خدمة تعمل في المقدّمة مع إشعار مستمر.
  
• مرة واحدة فقط
• تمت إضافة الإعداد في الإصدار 11 من نظام التشغيل Android، وهو ما يتطابق مع الإعداد السماح فقط أثناء استخدام التطبيق ولكن لفترة محدودة من الوقت. لمزيد من المعلومات، راجع الأذونات لمرة واحدة.
  
• رفض
• يمنع هذا الخيار الوصول إلى معلومات الموقع الجغرافي.
  
• السماح طوال الوقت
• يسمح هذا الخيار بالوصول إلى الموقع الجغرافي طوال الوقت، ولكنه يتطلب إذنًا إضافيًا لنظام التشغيل Android 10 والإصدارات الأحدث. وعليك أيضًا التأكُّد من امتلاك حالة استخدام صالحة والالتزام ببنود سياسات المواقع الجغرافية. لن تغطي هذا الخيار في هذا الدرس التطبيقي، لأنّه نادرًا ما يتم استخدامه. في حال كانت لديك حالة استخدام صالحة وتريد فهم كيفية التعامل مع الموقع الجغرافي بشكل صحيح طوال الوقت، بما في ذلك الوصول إلى الموقع الجغرافي في الخلفية، يُرجى مراجعة نموذج LocationUpdatesBackgroundKotlin.

الخدمات، وخدمات المقدّمة، والربط

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

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

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

ولمزيد من المعلومات، اطّلِع على نظرة عامة على الخدمات ونظرة عامة على الخدمات المرتبطة.

الأذونات

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

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

الموقع الجغرافي

يمكن للتطبيق الوصول إلى مجموعة خدمات الموقع الجغرافي المتاحة من خلال الصفوف في حزمة com.google.android.gms.location.

اطّلِع على الصفوف الرئيسية:

• FusedLocationProviderClient
• هذا هو المكوّن الرئيسي لإطار عمل الموقع. وبعد إنشاء الفيديو، يمكنك استخدامه لطلب إجراء تعديلات على الموقع الجغرافي والحصول على آخر موقع جغرافي معروف.
  
• LocationRequest
• وهذا عنصر بيانات يحتوي على معلّمات جودة الخدمة للطلبات (فترات زمنية للتعديلات والأولويات والدقة). يتم تمرير هذا إلى FusedLocationProviderClient عندما تطلب تحديثات الموقع الجغرافي.
  
• LocationCallback
• وهذا يُستخدَم لتلقّي الإشعارات عند تغيير الموقع الجغرافي للجهاز أو عند تعذُّر تحديد الموقع الجغرافي له. تم تمرير هذا LocationResult حيث يمكنك الحصول على Location لحفظه في قاعدة البيانات.

الآن وبعد أن تعرفت على الفكرة الأساسية لما تفعله، ابدأ باستخدام الرمز!

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

لتلقّي تعديلات الموقع الجغرافي، يجب أن يتضمن تطبيقك نشاطًا مرئيًا أو خدمة تعمل في المقدّمة (من خلال إشعار).

الأذونات

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

وفي ما يلي النقاط المهمة عن الأذونات (لا يلزم اتخاذ أي إجراء لهذا الجزء):

1. تحديد الإذن الذي تستخدمه في AndroidManifest.xml.
   
2. قبل محاولة الوصول إلى معلومات الموقع الجغرافي، تحقّق مما إذا كان المستخدم قد منحك الإذن بالوصول إلى التطبيق أم لا. وإذا لم يتلقّ تطبيقك إذنًا بعد، يمكنك طلب الوصول إليه.
   
3. التعامل مع خيار الإذن الخاص بالمستخدم. (يمكنك الاطّلاع على هذا الرمز في MainActivity.kt.)

إذا كنت تبحث عن TODO: Step 1.0, Review Permissions في AndroidManifest.xml أو MainActivity.kt، سترى جميع الرموز المكتوبة للأذونات.

لمزيد من المعلومات، راجع نظرة عامة على الأذونات.

والآن، ابدأ في كتابة بعض رموز المواقع الجغرافية.

مراجعة المتغيرات الرئيسية اللازمة لتعديلات المواقع الجغرافية

في وحدة base، ابحث عن TODO: Step 1.1, Review variables في

ملف ForegroundOnlyLocationService.kt.

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

// TODO: Step 1.1, Review variables (no changes).
// FusedLocationProviderClient - Main class for receiving location updates.
private lateinit var fusedLocationProviderClient: FusedLocationProviderClient

// LocationRequest - Requirements for the location updates, i.e., how often you
// should receive updates, the priority, etc.
private lateinit var locationRequest: LocationRequest

// LocationCallback - Called when FusedLocationProviderClient has a new Location.
private lateinit var locationCallback: LocationCallback

// Used only for local storage of the last known location. Usually, this would be saved to your
// database, but because this is a simplified sample without a full database, we only need the
// last location to create a Notification if the user navigates away from the app.
private var currentLocation: Location? = null

مراجعة الإعداد FuseLocationProviderClient

في الوحدة base، ابحث عن TODO: Step 1.2, Review the FusedLocationProviderClient في الملف ForegroundOnlyLocationService.kt. ويجب أن يظهر الرمز كما يلي:

// TODO: Step 1.2, Review the FusedLocationProviderClient.
fusedLocationProviderClient = LocationServices.getFusedLocationProviderClient(this)

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

إعداد LocationRequest

1. في الوحدة base، ابحث عن TODO: Step 1.3, Create a LocationRequest في الملف ForegroundOnlyLocationService.kt.
2. يمكنك إضافة الرمز التالي بعد التعليق.

يضيف رمز إعداد LocationRequest الجودة الإضافية لمَعلمات الخدمة التي تحتاجها لطلبك (الفترات والحد الأقصى لوقت الانتظار والأولوية).

// TODO: Step 1.3, Create a LocationRequest.
locationRequest = LocationRequest().apply {
   // Sets the desired interval for active location updates. This interval is inexact. You
   // may not receive updates at all if no location sources are available, or you may
   // receive them less frequently than requested. You may also receive updates more
   // frequently than requested if other applications are requesting location at a more
   // frequent interval.
   //
   // IMPORTANT NOTE: Apps running on Android 8.0 and higher devices (regardless of
   // targetSdkVersion) may receive updates less frequently than this interval when the app
   // is no longer in the foreground.
   interval = TimeUnit.SECONDS.toMillis(60)

   // Sets the fastest rate for active location updates. This interval is exact, and your
   // application will never receive updates more frequently than this value.
   fastestInterval = TimeUnit.SECONDS.toMillis(30)

   // Sets the maximum time when batched location updates are delivered. Updates may be
   // delivered sooner than this interval.
   maxWaitTime = TimeUnit.MINUTES.toMillis(2)

   priority = LocationRequest.PRIORITY_HIGH_ACCURACY
}

3. اطّلِع على التعليقات لفهم آلية عمل كلٍّ منها.

إعداد استدعاء الموقع الجغرافي

1. في الوحدة base، ابحث عن TODO: Step 1.4, Initialize the LocationCallback في الملف ForegroundOnlyLocationService.kt.
2. يمكنك إضافة الرمز التالي بعد التعليق.

// TODO: Step 1.4, Initialize the LocationCallback.
locationCallback = object : LocationCallback() {
   override fun onLocationResult(locationResult: LocationResult?) {
       super.onLocationResult(locationResult)

       if (locationResult?.lastLocation != null) {

           // Normally, you want to save a new location to a database. We are simplifying
           // things a bit and just saving it as a local variable, as we only need it again
           // if a Notification is created (when user navigates away from app).
           currentLocation = locationResult.lastLocation

           // Notify our Activity that a new location was added. Again, if this was a
           // production app, the Activity would be listening for changes to a database
           // with new locations, but we are simplifying things a bit to focus on just
           // learning the location side of things.
           val intent = Intent(ACTION_FOREGROUND_ONLY_LOCATION_BROADCAST)
           intent.putExtra(EXTRA_LOCATION, currentLocation)
           LocalBroadcastManager.getInstance(applicationContext).sendBroadcast(intent)

           // Updates notification content if this service is running as a foreground
           // service.
           if (serviceRunningInForeground) {
               notificationManager.notify(
                   NOTIFICATION_ID,
                   generateNotification(currentLocation))
           }
       } else {
           Log.d(TAG, "Location information isn't available.")
       }
   }
}

LocationCallback التي تنشئها هنا هي معاودة الاتصال التي سيتصل بها FusedLocationProviderClient عند توفُّر تحديث جديد للموقع الجغرافي.

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

3. اطّلِع على التعليقات لفهم وظيفة كل جزء.

الاشتراك في تغييرات الموقع الجغرافي

الآن وبعد إعداد كل شيء، يجب إبلاغ FusedLocationProviderClient بأنك تريد تلقي التحديثات.

1. في الوحدة base، ابحث عن Step 1.5, Subscribe to location changes في الملف ForegroundOnlyLocationService.kt.
2. يمكنك إضافة الرمز التالي بعد التعليق.

// TODO: Step 1.5, Subscribe to location changes.
fusedLocationProviderClient.requestLocationUpdates(locationRequest, locationCallback, Looper.myLooper())

تسمح المكالمة requestLocationUpdates() لـ FusedLocationProviderClient بمعرفة أنك تريد تلقي تحديثات الموقع الجغرافي.

من المحتمل أنك تعرف LocationRequest وLocationCallback اللذين حددتهما سابقًا. يتيح ذلك لـ FusedLocationProviderClient معرفة معلَمات جودة الخدمة لطلبك وما يُفترض أن تطلبه عند إجراء تعديل. وأخيرًا، يحدّد الكائن Looper سلسلة محادثات معاودة الاتصال.

قد تلاحظ أيضًا أن هذا الرمز ضمن عبارة try/catch. وتتطلّب هذه الطريقة حظراً لمنع الوصول إلى SecurityException لأنّ تطبيقك لا يملك إذن الوصول إلى معلومات الموقع الجغرافي.

إلغاء الاشتراك في تغييرات الموقع الجغرافي

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

1. في الوحدة base، ابحث عن TODO: Step 1.6, Unsubscribe to location changes في الملف ForegroundOnlyLocationService.kt.
2. يمكنك إضافة الرمز التالي بعد التعليق.

// TODO: Step 1.6, Unsubscribe to location changes.
val removeTask = fusedLocationProviderClient.removeLocationUpdates(locationCallback)
removeTask.addOnCompleteListener { task ->
   if (task.isSuccessful) {
       Log.d(TAG, "Location Callback removed.")
       stopSelf()
   } else {
       Log.d(TAG, "Failed to remove Location Callback.")
   }
}

تُعِد طريقة removeLocationUpdates() مهمة للسماح لـ FusedLocationProviderClient بمعرفة أنك لم تعد تريد تلقي تحديثات الموقع الجغرافي على LocationCallback. يرسل addOnCompleteListener() معاودة الاتصال للإكمال وينفّذ Task.

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

قد تتساءل عن موعد استدعاء الطرق التي تحتوي على رمز الاشتراك/إلغاء الاشتراك. ويتم تشغيلها في الصف الرئيسي عندما ينقر المستخدم على الزر. وإذا كنت تريد الاطّلاع عليها، يمكنك إلقاء نظرة على الصف MainActivity.kt.

تشغيل التطبيق

شغِّل تطبيقك من "استوديو Android" وجرِّب زر الموقع الجغرافي.

من المفترض أن تظهر معلومات الموقع الجغرافي في شاشة الإخراج. هذا تطبيق كامل الوظائف لنظام التشغيل Android 9.

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

في هذا القسم، يمكنك إضافة دعم لنظام التشغيل Android 10.

يشترك تطبيقك بالفعل في تغييرات الموقع الجغرافي، لذا ليس هناك الكثير من العمل الذي عليك تنفيذه.

وفي الواقع، كل ما عليك فعله هو تحديد أن خدمة المقدّمة تُستخدَم لأغراض الموقع الجغرافي.

حزمة تطوير البرامج (SDK) المستهدفة 29

1. في الوحدة base، ابحث عن TODO: Step 2.1, Target SDK 10 في الملف build.gradle.
2. أدخِل التغييرات التالية:

1. ضبط compileSdkVersion على 29
2. ضبط buildToolsVersion على "29.0.3"
3. ضبط targetSdkVersion على 29

ويجب أن يظهر الرمز كما يلي:

android {
   // TODO: Step 2.1, Target Android 10.
   compileSdkVersion 29
   buildToolsVersion "29.0.3"
   defaultConfig {
       applicationId "com.example.android.whileinuselocation"
       minSdkVersion 26
       targetSdkVersion 29
       versionCode 1
       versionName "1.0"
   }
...
}

بعد إجراء ذلك، سيُطلب منك مزامنة المشروع. انقر على المزامنة الآن.

بعد ذلك، يصبح تطبيقك جاهزًا تقريبًا لنظام التشغيل Android 10.

إضافة نوع الخدمة التي تعمل في المقدّمة

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

في الوحدة base، ابحث عن TODO: 2.2, Add foreground service type في AndroidManifest.xml وأضِف الرمز التالي إلى العنصر <service>:

android:foregroundServiceType="location"

ويجب أن يظهر الرمز كما يلي:

<application>
   ...

   <!-- Foreground services in Android 10+ require type. -->
   <!-- TODO: 2.2, Add foreground service type. -->
   <service
       android:name="com.example.android.whileinuselocation.ForegroundOnlyLocationService"
       android:enabled="true"
       android:exported="false"
       android:foregroundServiceType="location" />
</application>

أكملت هذه الخطوة. يتوافق تطبيقك مع الموقع الجغرافي الذي يعمل بنظام التشغيل Android 10 في مجال "التعلّم أثناء الاستخدام" من خلال اتّباع أفضل الممارسات المتعلّقة بالموقع الجغرافي في Android.

تشغيل التطبيق

شغِّل تطبيقك من "استوديو Android" وجرِّب زر الموقع الجغرافي.

من المفترض أن يعمل كل شيء على النحو المعتاد سابقًا، ولكنه يعمل الآن على نظام التشغيل Android 10. إذا لم تقبل أذونات المواقع الجغرافية في السابق، من المفترض أن تظهر لك شاشة الأذونات.

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

في هذا القسم، يمكنك استهداف الإصدار 11 من نظام التشغيل Android.

خبر سارّ: لن تحتاج إلى إجراء تغييرات على أي ملف باستثناء ملف build.gradle.

SDK R المستهدف

1. في وحدة base، ابحث عن TODO: Step 2.1, Target SDK في الملف build.gradle.
2. أدخِل التغييرات التالية:

1. من compileSdkVersion إلى "android-R"
2. من targetSdkVersion إلى "R"

ويجب أن يظهر الرمز كما يلي:

android {
   // TODO: Step 2.1, Target Android 10.
   compileSdkVersion "android-R"
   buildToolsVersion "29.0.2"
   defaultConfig {
       applicationId "com.example.android.whileinuselocation"
       minSdkVersion 26
       targetSdkVersion "R"
       versionCode 1
       versionName "1.0"
   }
...
}

بعد إجراء ذلك، سيُطلب منك مزامنة المشروع. انقر على المزامنة الآن.

بعد ذلك، أصبح تطبيقك جاهزًا لنظام التشغيل Android 11.

تشغيل التطبيق

شغِّل تطبيقك من "استوديو Android" وحاوِل النقر على الزر.

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

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

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

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

طلب الأذونات التي تحتاج إليها فقط

اطلب الأذونات فقط عند الحاجة. مثلاً:

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

توفير إجراءات خفض التوافق إذا لم يتم منح الإذن

للحفاظ على انطباع جيد للمستخدم، صمِّم تطبيقك بحيث يمكنه التعامل مع المواقف التالية بطريقة سلسة:

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

لقد تعلّمت كيفية تلقّي تحديثات الموقع الجغرافي على نظام التشغيل Android، مع مراعاة أفضل الممارسات.

مزيد من المعلومات

• مثال كامل لاستخدام الموقع في الخلفية إذا كانت لديك حالة استخدام صالحة
• طلب تعديل الموقع الجغرافي