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

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

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

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

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

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

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

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

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

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

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

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

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