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

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

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

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

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

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

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

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