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

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

يوضّح لك هذا الدرس كيفية طلب تلقّي تحديثات منتظمة بشأن الموقع الجغرافي لجهاز باستخدام طريقة requestLocationUpdates() في خدمة الموقع الجغرافي المدمَجة.

الحصول على آخر موقع جغرافي معروف

يوفّر آخر موقع جغرافي معروف للجهاز قاعدة مفيدة يمكن البدء منها، ما يضمن توفّر موقع جغرافي معروف للتطبيق قبل بدء عمليات تحديث الموقع الجغرافي الدورية. يوضّح لك الدرس حول الحصول على آخر موقع جغرافي معروف كيفية الحصول على آخر موقع جغرافي معروف من خلال استدعاء getLastLocation(). تفترض المقتطفات في الأقسام التالية أنّ تطبيقك قد استردّ بالفعل آخر موقع جغرافي معروف وتم تخزينه كعنصر Location في المتغير العام mCurrentLocation.

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

قبل طلب تعديلات على الموقع الجغرافي، يجب أن يتصل تطبيقك بخدمات الموقع الجغرافي وأن يقدّم طلبًا للحصول على الموقع الجغرافي. توضّح لك الدرس حول تغيير إعدادات الموقع الجغرافي كيفية إجراء ذلك. بعد إعداد طلب تحديد الموقع الجغرافي، يمكنك بدء تلقّي الإشعارات المنتظمة من خلال الاتصال بالرقم requestLocationUpdates().

استنادًا إلى شكل الطلب، يستدعي موفّر الموقع الجغرافي المدمج إما طريقة معاودة الاتصال LocationCallback.onLocationResult() ويُمرِّر إليها قائمة بعناصر Location، أو يُصدر PendingIntent يحتوي على الموقع الجغرافي في بياناته الموسّعة. تتأثر دقة التحديثات ومعدّل تكرارها بأذونات تحديد الموقع الجغرافي التي طلبتها والخيارات التي ضبطتها في عنصر طلب تحديد الموقع الجغرافي.

توضّح لك هذه الدرس كيفية الحصول على التحديث باستخدام طريقة LocationCallback لإجراء معاودة الاتصال. استدعِ الدالة requestLocationUpdates()، مع تمرير نسخة من الكائن LocationRequest وLocationCallback. حدِّد طريقة startLocationUpdates() كما هو موضّح في نموذج الرمز البرمجي التالي:

Kotlin

override fun onResume() {
    super.onResume()
    if (requestingLocationUpdates) startLocationUpdates()
}

private fun startLocationUpdates() {
    fusedLocationClient.requestLocationUpdates(locationRequest,
            locationCallback,
            Looper.getMainLooper())
}

Java

@Override
protected void onResume() {
    super.onResume();
    if (requestingLocationUpdates) {
        startLocationUpdates();
    }
}

private void startLocationUpdates() {
    fusedLocationClient.requestLocationUpdates(locationRequest,
            locationCallback,
            Looper.getMainLooper());
}

يُرجى العِلم أنّ مقتطف الرمز البرمجي أعلاه يشير إلى علامة منطقية، requestingLocationUpdates، تُستخدَم لتتبُّع ما إذا كان المستخدم قد فعّل أو أوقف إشعارات الموقع الجغرافي. وإذا أوقف المستخدمون إشعارات الموقع الجغرافي، يمكنك إبلاغهم بمتطلبات تطبيقك المتعلقة بالموقع الجغرافي. لمزيد من المعلومات حول الاحتفاظ بقيمة العلامة المنطقية على مستوى مثيلات النشاط، راجِع حفظ حالة النشاط.

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

يستدعي موفِّر الموقع المدمج طريقة رد الاتصال LocationCallback.onLocationResult(). يحتوي الوسيط الوارد على قائمة Location تتضمّن خطَّي الطول والعرض للموقع الجغرافي. يوضّح المقتطف التالي كيفية تنفيذ واجهة LocationCallback وتحديد الطريقة، ثم الحصول على الطابع الزمني لتعديل الموقع الجغرافي وعرض خطوط الطول والعرض والطابع الزمني على واجهة مستخدم تطبيقك:

Kotlin

private lateinit var locationCallback: LocationCallback

// ...

override fun onCreate(savedInstanceState: Bundle?) {
    // ...

    locationCallback = object : LocationCallback() {
        override fun onLocationResult(locationResult: LocationResult?) {
            locationResult ?: return
            for (location in locationResult.locations){
                // Update UI with location data
                // ...
            }
        }
    }
}

Java

private LocationCallback locationCallback;

// ...

@Override
protected void onCreate(Bundle savedInstanceState) {
    // ...

    locationCallback = new LocationCallback() {
        @Override
        public void onLocationResult(LocationResult locationResult) {
            if (locationResult == null) {
                return;
            }
            for (Location location : locationResult.getLocations()) {
                // Update UI with location data
                // ...
            }
        }
    };
}

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

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

لإيقاف تحديثات الموقع الجغرافي، استدعِ الدالة removeLocationUpdates()، مع تمرير LocationCallback، كما هو موضّح في نموذج الرمز التالي:

Kotlin

override fun onPause() {
    super.onPause()
    stopLocationUpdates()
}

private fun stopLocationUpdates() {
    fusedLocationClient.removeLocationUpdates(locationCallback)
}

Java

@Override
protected void onPause() {
    super.onPause();
    stopLocationUpdates();
}

private void stopLocationUpdates() {
    fusedLocationClient.removeLocationUpdates(locationCallback);
}

استخدِم قيمة منطقية، requestingLocationUpdates، لتتبُّع ما إذا كانت ميزة تعديل الموقع الجغرافي مفعّلة حاليًا. في طريقة onResume() الخاصة بالنشاط، تحقَّق مما إذا كانت عمليات تعديل الموقع الجغرافي مفعّلة حاليًا، وفعِّلها إذا لم تكن كذلك:

Kotlin

override fun onResume() {
    super.onResume()
    if (requestingLocationUpdates) startLocationUpdates()
}

Java

@Override
protected void onResume() {
    super.onResume();
    if (requestingLocationUpdates) {
        startLocationUpdates();
    }
}

حفظ حالة النشاط

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

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام معاودة الاتصال onSaveInstanceState() الخاصة بالنشاط لحفظ حالة المثيل:

Kotlin

override fun onSaveInstanceState(outState: Bundle?) {
    outState?.putBoolean(REQUESTING_LOCATION_UPDATES_KEY, requestingLocationUpdates)
    super.onSaveInstanceState(outState)
}

Java

@Override
protected void onSaveInstanceState(Bundle outState) {
    outState.putBoolean(REQUESTING_LOCATION_UPDATES_KEY,
            requestingLocationUpdates);
    // ...
    super.onSaveInstanceState(outState);
}

حدِّد طريقة updateValuesFromBundle() لاستعادة القيم المحفوظة من مثيل النشاط السابق، إذا كانت متاحة. استدعِ الطريقة من طريقة onCreate() للنشاط، كما هو موضّح في نموذج الرمز التالي:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    updateValuesFromBundle(savedInstanceState)
}

private fun updateValuesFromBundle(savedInstanceState: Bundle?) {
    savedInstanceState ?: return

    // Update the value of requestingLocationUpdates from the Bundle.
    if (savedInstanceState.keySet().contains(REQUESTING_LOCATION_UPDATES_KEY)) {
        requestingLocationUpdates = savedInstanceState.getBoolean(
                REQUESTING_LOCATION_UPDATES_KEY)
    }

    // ...

    // Update UI to match restored state
    updateUI()
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    // ...
    updateValuesFromBundle(savedInstanceState);
}

private void updateValuesFromBundle(Bundle savedInstanceState) {
    if (savedInstanceState == null) {
        return;
    }

    // Update the value of requestingLocationUpdates from the Bundle.
    if (savedInstanceState.keySet().contains(REQUESTING_LOCATION_UPDATES_KEY)) {
        requestingLocationUpdates = savedInstanceState.getBoolean(
                REQUESTING_LOCATION_UPDATES_KEY);
    }

    // ...

    // Update UI to match restored state
    updateUI();
}

لمزيد من المعلومات حول حفظ حالة المثيل، راجِع مرجع فئة نشاط Android.

ملاحظة: للحصول على مساحة تخزين أكثر ثباتًا، يمكنك تخزين الإعدادات المفضّلة للمستخدم في SharedPreferences بتطبيقك. اضبط الإعدادات المفضّلة المشترَكة في طريقة onPause() الخاصة بنشاطك، واسترجِع الإعدادات المفضّلة في onResume(). لمزيد من المعلومات حول حفظ الإعدادات المفضّلة، يمكنك الاطّلاع على حفظ مجموعات المفتاح والقيمة.

مراجع إضافية

لمزيد من المعلومات، يمكنك الاستفادة من المراجع التالية:

نماذج

• تطبيق نموذجي لتوضيح كيفية تلقّي آخر المعلومات حول الموقع الجغرافي في Android