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

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

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

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

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