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

إذا كان تطبيقك يحتاج إلى طلب الموقع الجغرافي أو تلقّي تحديثات الأذونات، على الجهاز تفعيل إعدادات النظام المناسبة، مثل البحث عن نظام تحديد المواقع العالمي (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. للحصول على مزيد من التفاصيل حول الحالة الحالية لإعدادات الموقع الجغرافي ذات الصلة، يمكن لتطبيقك استدعاء طريقة LocationSettingsResponse للعنصر getLocationSettingsStates().

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

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

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