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

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

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

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

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

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

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

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

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

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

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

بعد ذلك، تحقّق مما إذا كانت إعدادات الموقع الجغرافي الحالية تستوفي المتطلبات التالية:

val builder = LocationSettingsRequest.Builder()

// ...

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

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، بالإضافة إلى كيفية طلب إذن من المستخدم لتغيير إعدادات الموقع الجغرافي إذا لزم الأمر:

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.
        }
    }
}

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.
            }
        }
    }
});

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