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

إذا كان تطبيقك يحتاج إلى طلب تحديد الموقع الجغرافي أو تلقّي تحديثات الأذونات، يجب تفعيل إعدادات النظام المناسبة على الجهاز، مثل نظام تحديد المواقع العالمي (GPS) أو البحث عن شبكات Wi-Fi. فبدلاً من تفعيل الخدمات مثل نظام تحديد المواقع العالمي (GPS) على الجهاز بشكل مباشر، يحدّد تطبيقك المستوى المطلوب من الدقة/استهلاك الطاقة والفاصل الزمني للتحديث المطلوب، ويُجري الجهاز تلقائيًا التغييرات المناسبة على إعدادات النظام. يتم تحديد هذه الإعدادات من خلال كائن البيانات LocationRequest.

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

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

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

يجب على التطبيقات التي تستخدم ميزاتها خدمات الموقع الجغرافي طلب أذونات تحديد الموقع الجغرافي، بناءً على حالات استخدام هذه الميزات.

إعداد طلب موقع جغرافي

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

الفاصل الزمني للتعديل

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

الفاصل الزمني الأسرع للتحديث

setFastestInterval() - تحدّد هذه الطريقة المعدّل الأسرع بالمللي ثانية التي يمكن لتطبيقك خلالها معالجة تعديلات الموقع الجغرافي. لن تحتاج إلى طلب هذه الطريقة، ما لم يكن تطبيقك يستفيد من تلقّي التحديثات بسرعة أكبر من المعدّل المحدَّد في setInterval().

درجة الأهمية

setPriority() - تحدّد هذه الطريقة أولوية الطلب، ما يمنح "خدمات الموقع الجغرافي" في "خدمات Google Play" تلميحًا قويًا عن مصادر الموقع الجغرافي التي يجب استخدامها. في ما يلي القيم المسموح بها:

• PRIORITY_BALANCED_POWER_ACCURACY - يمكنك استخدام هذا الإعداد لطلب دقة الموقع الجغرافي داخل مبنى في المدينة، بدقة تبلغ 100 متر تقريبًا. وهذا يعتبر مستوى تقريبي من الدقة، ومن المرجّح أن يستهلك طاقة أقل. من خلال هذا الإعداد، من المرجَّح أن تستخدم خدمات الموقع الجغرافي شبكة Wi-Fi وتحديد موقع برج الاتصالات. مع ذلك، يعتمد اختيار موفّر الموقع الجغرافي على عدة عوامل أخرى، مثل المصادر المتاحة.
• PRIORITY_HIGH_ACCURACY - استخدِم هذا الإعداد لطلب الموقع الجغرافي بأعلى دقة ممكنة. من خلال هذا الإعداد، من المرجّح أن تستخدم خدمات الموقع الجغرافي نظام تحديد المواقع العالمي (GPS) لتحديد الموقع الجغرافي.
• PRIORITY_LOW_POWER - استخدِم هذا الإعداد لطلب الدقة على مستوى المدينة، أي دقة تبلغ 10 كيلومتر تقريبًا. وهذا يُعدّ مستوى تقريبيًا من الدقة، ومن المرجّح أن يستهلك طاقة أقل.
• PRIORITY_NO_POWER - استخدِم هذا الخيار إذا كنت بحاجة إلى تأثير ضئيل على استهلاك الطاقة، ولكنّك تريد تلقّي آخر المعلومات حول الموقع الجغرافي عند توفّرها. باستخدام هذا الإعداد، لن يبدأ تطبيقك أي تعديلات على الموقع الجغرافي، بل يتلقّى المواقع الجغرافية التي تم تشغيلها من خلال تطبيقات أخرى.

أنشِئ طلب الموقع الجغرافي واضبط المَعلمات كما هو موضّح في نموذج الرمز التالي:

Kotlin

fun createLocationRequest() {
  val locationRequest = LocationRequest.Builder()
      .setIntervalMillis(10000)
      .setFastestIntervalMillis(5000)
      .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY)
      .build()
}

Java

protected void createLocationRequest() {
  LocationRequest locationRequest = LocationRequest.Builder()
      .setIntervalMillis(10000)
      .setFastestIntervalMillis(5000)
      .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY)
      .build();
}

إنّ أولوية السمة PRIORITY_HIGH_ACCURACY، إلى جانب إعداد الإذن ACCESS_FINE_LOCATION الذي حدّدته في بيان التطبيق، والفاصل الزمني للتحديث السريع الذي تبلغ مدته 5,000 مللي ثانية (5 ثوانٍ)، تجعل موفّر الموقع الجغرافي المدمج يعرض بيانات الموقع الجغرافي الدقيقة في غضون بضعة أقدام. هذا الأسلوب مناسب لتصميم خرائط التطبيقات التي تعرض الموقع الجغرافي في الوقت الفعلي.

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

الحصول على إعدادات الموقع الجغرافي الحالية

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

Kotlin

val builder = LocationSettingsRequest.Builder()
        .addLocationRequest(locationRequest)

Java

LocationSettingsRequest.Builder builder = new LocationSettingsRequest.Builder()
     .addLocationRequest(locationRequest);

بعد ذلك، تحقق مما إذا كانت إعدادات الموقع الحالية متوافقة:

Kotlin

val builder = LocationSettingsRequest.Builder()

// ...

val client: SettingsClient = LocationServices.getSettingsClient(this)
val task: Task<LocationSettingsResponse> = client.checkLocationSettings(builder.build())

Java

LocationSettingsRequest.Builder builder = new LocationSettingsRequest.Builder();

// ...

SettingsClient client = LocationServices.getSettingsClient(this);
Task<LocationSettingsResponse> task = client.checkLocationSettings(builder.build());

عند اكتمال Task ، يمكن لتطبيقك التحقّق من إعدادات الموقع الجغرافي من خلال الاطّلاع على رمز الحالة في الكائن LocationSettingsResponse. للحصول على مزيد من التفاصيل حول الحالة الحالية لإعدادات الموقع الجغرافي ذات الصلة، يمكن لتطبيقك استدعاء طريقة getLocationSettingsStates() الخاصة بالكائن LocationSettingsResponse.

مطالبة المستخدم بتغيير إعدادات الموقع الجغرافي

لتحديد ما إذا كانت إعدادات الموقع الجغرافي مناسبة لطلب الموقع الجغرافي، أضِف OnFailureListener إلى عنصر Task الذي يتحقّق من إعدادات الموقع الجغرافي. بعد ذلك، تحقَّق مما إذا كان عنصر Exception الذي تم تمريره إلى الإجراء onFailure() هو نسخة افتراضية من فئة ResolvableApiException، ما يشير إلى ضرورة تغيير الإعدادات. بعد ذلك، اعرض مربّع حوار يطلب من المستخدم إذنًا لتعديل إعدادات الموقع الجغرافي من خلال طلب startResolutionForResult().

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

Kotlin

task.addOnSuccessListener { locationSettingsResponse ->
    // All location settings are satisfied. The client can initialize
    // location requests here.
    // ...
}

task.addOnFailureListener { exception ->
    if (exception is ResolvableApiException){
        // Location settings are not satisfied, but this can be fixed
        // by showing the user a dialog.
        try {
            // Show the dialog by calling startResolutionForResult(),
            // and check the result in onActivityResult().
            exception.startResolutionForResult(this@MainActivity,
                    REQUEST_CHECK_SETTINGS)
        } catch (sendEx: IntentSender.SendIntentException) {
            // Ignore the error.
        }
    }
}

Java

task.addOnSuccessListener(this, new OnSuccessListener<LocationSettingsResponse>() {
    @Override
    public void onSuccess(LocationSettingsResponse locationSettingsResponse) {
        // All location settings are satisfied. The client can initialize
        // location requests here.
        // ...
    }
});

task.addOnFailureListener(this, new OnFailureListener() {
    @Override
    public void onFailure(@NonNull Exception e) {
        if (e instanceof ResolvableApiException) {
            // Location settings are not satisfied, but this can be fixed
            // by showing the user a dialog.
            try {
                // Show the dialog by calling startResolutionForResult(),
                // and check the result in onActivityResult().
                ResolvableApiException resolvable = (ResolvableApiException) e;
                resolvable.startResolutionForResult(MainActivity.this,
                        REQUEST_CHECK_SETTINGS);
            } catch (IntentSender.SendIntentException sendEx) {
                // Ignore the error.
            }
        }
    }
});

يشرح لك الدرس التالي بعنوان تلقّي إشعارات بشأن الموقع الجغرافي كيفية تلقّي إشعارات دورية بشأن الموقع الجغرافي.