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

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

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

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

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

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

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

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

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

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

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

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

Kotlin

  fun createLocationRequest() {
    val locationRequest = LocationRequest.Builder(Priority.PRIORITY_HIGH_ACCURACY, 10000)
        .setMinUpdateIntervalMillis(5000)
        .build()
}

Java

  protected void createLocationRequest() {
    LocationRequest locationRequest = new LocationRequest.Builder(Priority.PRIORITY_HIGH_ACCURACY, 10000)
            .setMinUpdateIntervalMillis(5000)
            .build();
}

تؤدي أولوية PRIORITY_HIGH_ACCURACY، بالإضافة إلى إعدادات إذن ACCESS_FINE_LOCATION التي حدّدتها في بيان التطبيق، والفاصل الزمني السريع لتحديث الموقع الجغرافي الذي يبلغ 5000 ملي ثانية (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.
            }
        }
    }
});

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