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

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

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