من الميزات الفريدة للتطبيقات المتوافقة مع الأجهزة الجوّالة هي ميزة "معرفة الموقع الجغرافي". يأخذ مستخدمو الأجهزة الجوّالة أجهزتهم معهم أينما ذهبوا، وتوفر إضافة ميزة معرفة الموقع الجغرافي إلى تطبيقك تجربة أكثر سياقية للمستخدمين.
عيّنات تعليمات برمجية
يتضمّن مستودع ApiDemos على GitHub عيّنات توضّح استخدام الموقع الجغرافي على الخريطة:
Kotlin
- MyLocationDemoActivity: استخدام طبقة موقعي، بما في ذلك أذونات التشغيل
- LocationSourceDemoActivity: استخدام واجهة برمجة تطبيقات مخصَّصة
LocationSource
- CurrentPlaceDetailsOnMap: العثور على الموقع الجغرافي الحالي لجهاز Android وعرض تفاصيل المكان (نشاط تجاري أو نقطة اهتمام أخرى) في ذلك الموقع الجغرافي اطّلِع على الدليل التعليمي حول عرض تفاصيل المكان الحالي على الخريطة.
Java
- MyLocationDemoActivity: استخدام طبقة موقعي، بما في ذلك أذونات التشغيل
- LocationSourceDemoActivity: استخدام ملف شخصي مخصّص
LocationSource
- CurrentPlaceDetailsOnMap: العثور على الموقع الجغرافي الحالي لجهاز Android وعرض تفاصيل المكان (نشاط تجاري أو نقطة اهتمام أخرى) في ذلك الموقع الجغرافي اطّلِع على الدليل التعليمي حول عرض تفاصيل المكان الحالي على الخريطة.
استخدام بيانات الموقع
تتضمّن بيانات الموقع الجغرافي المتاحة لجهاز Android الموقع الجغرافي الحالي للجهاز، والذي يتم تحديده باستخدام مجموعة من التقنيات، واتجاه الحركة وطريقة التنقّل، وما إذا كان الجهاز قد تحرّك عبر حدود جغرافية محدّدة مسبقًا أو سياج جغرافي. استنادًا إلى احتياجات تطبيقك، يمكنك الاختيار من بين عدة طرق للعمل مع بيانات الموقع الجغرافي:
- توفّر طبقة موقعي الجغرافي طريقة بسيطة لعرض الموقع الجغرافي للجهاز على الخريطة. ولا يقدّم أي بيانات.
- يُنصح باستخدام واجهة برمجة التطبيقات للموقع الجغرافي في "خدمات Google Play" للجميع. الطلبات الآلية لبيانات الموقع.
- تتيح لك واجهة
LocationSource
تقديم مزوّد موقع جغرافي مخصّص.
أذونات تحديد الموقع
إذا كان تطبيقك يتطلّب الوصول إلى الموقع الجغرافي للمستخدم، عليك طلب الإذن عن طريق إضافة أذونات تحديد الموقع الجغرافي ذات الصلة في Android إلى تطبيقك
يوفّر Android إذنَي تحديد الموقع الجغرافي: ACCESS_COARSE_LOCATION
و
ACCESS_FINE_LOCATION
يحدِّد الإذن الذي تختاره دقة
الموقع الجغرافي الذي تعرضه واجهة برمجة التطبيقات.
android.permission.ACCESS_COARSE_LOCATION
– للسماح لواجهة برمجة التطبيقات بعرض الموقع التقريبي للجهاز. يقدّم الإذن تقديرًا لموقع الجهاز الجغرافي من خدمات الموقع الجغرافي، كما هو описан في المستندات حول دقة الموقع الجغرافي التقريبي.android.permission.ACCESS_FINE_LOCATION
– للسماح لواجهة برمجة التطبيقات بتحديد الموقع الدقيق قدر الإمكان من خلال مزوّدو المواقع الجغرافية المتاحون، بما في ذلك نظام تحديد المواقع العالمي (نظام تحديد المواقع العالمي "GPS") بالإضافة إلى شبكة Wi-Fi وبيانات شبكة الجوّال.
إضافة الأذونات إلى بيان التطبيق
إذا كان الموقع الجغرافي التقريبي مطلوبًا فقط لكي يعمل تطبيقك، أضِف إذن
ACCESS_COARSE_LOCATION
إلى ملف بيان تطبيقك:
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.myapp" > ... <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> ... </manifest>
مع ذلك، إذا أردتِ الحصول على الموقع الجغرافي الدقيق، عليك إضافة قيمتَي ACCESS_COARSE_LOCATION
.
بالإضافة إلى أذونات ACCESS_FINE_LOCATION
في ملف بيان تطبيقك:
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.myapp" > ... <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> ... </manifest>
طلب أذونات التشغيل
يقدّم Android 6.0 (Marshmallow) نموذجًا جديدًا للتعامل مع الأذونات، والذي يبسّط العملية للمستخدمين عند تثبيت التطبيقات وترقيتها. إذا كان تطبيقك يستهدف المستوى 23 من واجهة برمجة التطبيقات أو الإصدارات الأحدث، يمكنك استخدام نموذج الأذونات الجديد.
إذا كان تطبيقك متوافقًا مع نموذج الأذونات الجديد وكان الجهاز يعمل بالإصدار 6.0 (Marshmallow) من نظام التشغيل Android أو إصدار أحدث، لن يحتاج المستخدم إلى منح أي أذونات عند تثبيت التطبيق أو ترقيته. على التطبيق التحقّق مما إذا كان يملك الإذن اللازم أثناء التشغيل وطلب الإذن إذا لم يكن لديه. يعرض النظام مربّع حوار للمستخدم الذي يطلب الإذن.
للحصول على أفضل تجربة للمستخدم، من المهم طلب الإذن في السياق. إذا كان الموقع الجغرافي ضروريًا لعمل تطبيقك، يجب طلب إذن تحديد الموقع الجغرافي عند بدء تشغيل التطبيق. ومن الطرق الجيدة لإجراء ذلك استخدام شاشة مرحبًا دافئة أو معالج يوضّح للمستخدمين سبب طلب الإذن.
إذا كان التطبيق يتطلّب الإذن لاستخدام جزء من وظائفه فقط، يجب طلب إذن الموقع الجغرافي في الوقت الذي ينفّذ فيه التطبيق الإجراء الذي يتطلّب الإذن.
يجب أن يتعامل التطبيق بسلاسة مع الحالة التي لا يمنح فيها المستخدم إذن. على سبيل المثال، إذا كان الإذن مطلوبًا لميزة معينة، سيتم تطبيقك تعطيل هذه الميزة. إذا كان الإذن ضروريًا لكي يعمل التطبيق، يمكن للتطبيق إيقاف جميع وظائفه وإعلام المستخدم بأنّه يحتاج إلى منح الإذن.
يتحقّق نموذج الرمز البرمجي التالي من الإذن باستخدام مكتبة AndroidX
قبل تفعيل طبقة "موقعي الجغرافي". ثم تعالج نتيجة
طلب إذن من خلال تنفيذ
ActivityCompat.OnRequestPermissionsResultCallback
من مكتبة الدعم:
Kotlin
// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.example.kotlindemos import android.Manifest import android.annotation.SuppressLint import android.content.pm.PackageManager import android.location.Location import android.os.Bundle import android.widget.Toast import androidx.appcompat.app.AppCompatActivity import androidx.core.app.ActivityCompat import androidx.core.app.ActivityCompat.OnRequestPermissionsResultCallback import androidx.core.content.ContextCompat import com.example.kotlindemos.PermissionUtils.PermissionDeniedDialog.Companion.newInstance import com.example.kotlindemos.PermissionUtils.isPermissionGranted import com.google.android.gms.maps.GoogleMap import com.google.android.gms.maps.GoogleMap.OnMyLocationButtonClickListener import com.google.android.gms.maps.GoogleMap.OnMyLocationClickListener import com.google.android.gms.maps.OnMapReadyCallback import com.google.android.gms.maps.SupportMapFragment /** * This demo shows how GMS Location can be used to check for changes to the users location. The * "My Location" button uses GMS Location to set the blue dot representing the users location. * Permission for [Manifest.permission.ACCESS_FINE_LOCATION] and [Manifest.permission.ACCESS_COARSE_LOCATION] * are requested at run time. If either permission is not granted, the Activity is finished with an error message. */ class MyLocationDemoActivity : AppCompatActivity(), OnMyLocationButtonClickListener, OnMyLocationClickListener, OnMapReadyCallback, OnRequestPermissionsResultCallback { /** * Flag indicating whether a requested permission has been denied after returning in * [.onRequestPermissionsResult]. */ private var permissionDenied = false private lateinit var map: GoogleMap override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.my_location_demo) val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment? mapFragment?.getMapAsync(this) } override fun onMapReady(googleMap: GoogleMap) { map = googleMap googleMap.setOnMyLocationButtonClickListener(this) googleMap.setOnMyLocationClickListener(this) enableMyLocation() } /** * Enables the My Location layer if the fine location permission has been granted. */ @SuppressLint("MissingPermission") private fun enableMyLocation() { // 1. Check if permissions are granted, if so, enable the my location layer if (ContextCompat.checkSelfPermission( this, Manifest.permission.ACCESS_FINE_LOCATION ) == PackageManager.PERMISSION_GRANTED || ContextCompat.checkSelfPermission( this, Manifest.permission.ACCESS_COARSE_LOCATION ) == PackageManager.PERMISSION_GRANTED ) { map.isMyLocationEnabled = true return } // 2. If if a permission rationale dialog should be shown if (ActivityCompat.shouldShowRequestPermissionRationale( this, Manifest.permission.ACCESS_FINE_LOCATION ) || ActivityCompat.shouldShowRequestPermissionRationale( this, Manifest.permission.ACCESS_COARSE_LOCATION ) ) { PermissionUtils.RationaleDialog.newInstance( LOCATION_PERMISSION_REQUEST_CODE, true ).show(supportFragmentManager, "dialog") return } // 3. Otherwise, request permission ActivityCompat.requestPermissions( this, arrayOf( Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION ), LOCATION_PERMISSION_REQUEST_CODE ) } override fun onMyLocationButtonClick(): Boolean { Toast.makeText(this, "MyLocation button clicked", Toast.LENGTH_SHORT) .show() // Return false so that we don't consume the event and the default behavior still occurs // (the camera animates to the user's current position). return false } override fun onMyLocationClick(location: Location) { Toast.makeText(this, "Current location:\n$location", Toast.LENGTH_LONG) .show() } override fun onRequestPermissionsResult( requestCode: Int, permissions: Array<String>, grantResults: IntArray ) { if (requestCode != LOCATION_PERMISSION_REQUEST_CODE) { super.onRequestPermissionsResult( requestCode, permissions, grantResults ) return } if (isPermissionGranted( permissions, grantResults, Manifest.permission.ACCESS_FINE_LOCATION ) || isPermissionGranted( permissions, grantResults, Manifest.permission.ACCESS_COARSE_LOCATION ) ) { // Enable the my location layer if the permission has been granted. enableMyLocation() } else { // Permission was denied. Display an error message // Display the missing permission error dialog when the fragments resume. permissionDenied = true } } override fun onResumeFragments() { super.onResumeFragments() if (permissionDenied) { // Permission was not granted, display error dialog. showMissingPermissionError() permissionDenied = false } } /** * Displays a dialog with error message explaining that the location permission is missing. */ private fun showMissingPermissionError() { newInstance(true).show(supportFragmentManager, "dialog") } companion object { /** * Request code for location permission request. * * @see .onRequestPermissionsResult */ private const val LOCATION_PERMISSION_REQUEST_CODE = 1 } }
Java
// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.example.mapdemo; import android.Manifest.permission; import android.annotation.SuppressLint; import com.google.android.gms.maps.GoogleMap; import com.google.android.gms.maps.GoogleMap.OnMyLocationButtonClickListener; import com.google.android.gms.maps.GoogleMap.OnMyLocationClickListener; import com.google.android.gms.maps.OnMapReadyCallback; import com.google.android.gms.maps.SupportMapFragment; import android.Manifest; import android.content.pm.PackageManager; import android.location.Location; import android.os.Bundle; import androidx.annotation.NonNull; import androidx.appcompat.app.AppCompatActivity; import androidx.core.app.ActivityCompat; import androidx.core.content.ContextCompat; import android.widget.Toast; /** * This demo shows how GMS Location can be used to check for changes to the users location. The "My * Location" button uses GMS Location to set the blue dot representing the users location. * Permission for {@link android.Manifest.permission#ACCESS_FINE_LOCATION} and {@link * android.Manifest.permission#ACCESS_COARSE_LOCATION} are requested at run time. If either * permission is not granted, the Activity is finished with an error message. */ public class MyLocationDemoActivity extends AppCompatActivity implements OnMyLocationButtonClickListener, OnMyLocationClickListener, OnMapReadyCallback, ActivityCompat.OnRequestPermissionsResultCallback { /** * Request code for location permission request. * * @see #onRequestPermissionsResult(int, String[], int[]) */ private static final int LOCATION_PERMISSION_REQUEST_CODE = 1; /** * Flag indicating whether a requested permission has been denied after returning in {@link * #onRequestPermissionsResult(int, String[], int[])}. */ private boolean permissionDenied = false; private GoogleMap map; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.my_location_demo); SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map); mapFragment.getMapAsync(this); } @Override public void onMapReady(@NonNull GoogleMap googleMap) { map = googleMap; map.setOnMyLocationButtonClickListener(this); map.setOnMyLocationClickListener(this); enableMyLocation(); } /** * Enables the My Location layer if the fine location permission has been granted. */ @SuppressLint("MissingPermission") private void enableMyLocation() { // 1. Check if permissions are granted, if so, enable the my location layer if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED || ContextCompat.checkSelfPermission(this, permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED) { map.setMyLocationEnabled(true); return; } // 2. Otherwise, request location permissions from the user. PermissionUtils.requestLocationPermissions(this, LOCATION_PERMISSION_REQUEST_CODE, true); } @Override public boolean onMyLocationButtonClick() { Toast.makeText(this, "MyLocation button clicked", Toast.LENGTH_SHORT).show(); // Return false so that we don't consume the event and the default behavior still occurs // (the camera animates to the user's current position). return false; } @Override public void onMyLocationClick(@NonNull Location location) { Toast.makeText(this, "Current location:\n" + location, Toast.LENGTH_LONG).show(); } @Override public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) { if (requestCode != LOCATION_PERMISSION_REQUEST_CODE) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); return; } if (PermissionUtils.isPermissionGranted(permissions, grantResults, Manifest.permission.ACCESS_FINE_LOCATION) || PermissionUtils .isPermissionGranted(permissions, grantResults, Manifest.permission.ACCESS_COARSE_LOCATION)) { // Enable the my location layer if the permission has been granted. enableMyLocation(); } else { // Permission was denied. Display an error message // Display the missing permission error dialog when the fragments resume. permissionDenied = true; } } @Override protected void onResumeFragments() { super.onResumeFragments(); if (permissionDenied) { // Permission was not granted, display error dialog. showMissingPermissionError(); permissionDenied = false; } } /** * Displays a dialog with error message explaining that the location permission is missing. */ private void showMissingPermissionError() { PermissionUtils.PermissionDeniedDialog .newInstance(true).show(getSupportFragmentManager(), "dialog"); } }
طبقة "موقعي"
يمكنك استخدام طبقة "موقعي" وزر "موقعي" لعرض
موقعهم الحالي على الخريطة. الاتصال بـ "mMap.setMyLocationEnabled()
"
لتمكين طبقة "موقعي" على الخريطة.
يعرض النموذج التالي استخدامًا بسيطًا لطبقة "موقعي":
Kotlin
// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.maps.example.kotlin import android.annotation.SuppressLint import android.location.Location import android.os.Bundle import android.widget.Toast import androidx.appcompat.app.AppCompatActivity import com.google.android.gms.maps.GoogleMap import com.google.android.gms.maps.GoogleMap.OnMyLocationButtonClickListener import com.google.android.gms.maps.GoogleMap.OnMyLocationClickListener import com.google.android.gms.maps.OnMapReadyCallback import com.google.android.gms.maps.SupportMapFragment import com.google.maps.example.R internal class MyLocationLayerActivity : AppCompatActivity(), OnMyLocationButtonClickListener, OnMyLocationClickListener, OnMapReadyCallback { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_my_location) val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment mapFragment.getMapAsync(this) } @SuppressLint("MissingPermission") override fun onMapReady(map: GoogleMap) { // TODO: Before enabling the My Location layer, you must request // location permission from the user. This sample does not include // a request for location permission. map.isMyLocationEnabled = true map.setOnMyLocationButtonClickListener(this) map.setOnMyLocationClickListener(this) } override fun onMyLocationClick(location: Location) { Toast.makeText(this, "Current location:\n$location", Toast.LENGTH_LONG) .show() } override fun onMyLocationButtonClick(): Boolean { Toast.makeText(this, "MyLocation button clicked", Toast.LENGTH_SHORT) .show() // Return false so that we don't consume the event and the default behavior still occurs // (the camera animates to the user's current position). return false } }
Java
// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.maps.example; import android.annotation.SuppressLint; import android.location.Location; import android.os.Bundle; import android.widget.Toast; import androidx.annotation.NonNull; import androidx.appcompat.app.AppCompatActivity; import com.google.android.gms.maps.GoogleMap; import com.google.android.gms.maps.OnMapReadyCallback; import com.google.android.gms.maps.SupportMapFragment; class MyLocationLayerActivity extends AppCompatActivity implements GoogleMap.OnMyLocationButtonClickListener, GoogleMap.OnMyLocationClickListener, OnMapReadyCallback { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_my_location); SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map); mapFragment.getMapAsync(this); } @SuppressLint("MissingPermission") @Override public void onMapReady(GoogleMap map) { // TODO: Before enabling the My Location layer, you must request // location permission from the user. This sample does not include // a request for location permission. map.setMyLocationEnabled(true); map.setOnMyLocationButtonClickListener(this); map.setOnMyLocationClickListener(this); } @Override public void onMyLocationClick(@NonNull Location location) { Toast.makeText(this, "Current location:\n" + location, Toast.LENGTH_LONG) .show(); } @Override public boolean onMyLocationButtonClick() { Toast.makeText(this, "MyLocation button clicked", Toast.LENGTH_SHORT) .show(); // Return false so that we don't consume the event and the default behavior still occurs // (the camera animates to the user's current position). return false; } }
عند تفعيل طبقة "موقعي الجغرافي"، يظهر الزر "موقعي الجغرافي" في أعلى يسار الخريطة. عندما ينقر المستخدم على الزر، تمركز الكاميرا الخريطة على الموقع الحالي للجهاز، إذا كانت معروفة. الموقع الجغرافي على الخريطة بنقطة زرقاء صغيرة إذا كان الجهاز ثابتًا، أو على شكل شارة شيفر إذا كان الجهاز يتحرك.
تعرض لقطة الشاشة التالية الزر "موقعي" أعلى اليسار النقطة الزرقاء لموقعي في وسط الخريطة:
يمكنك منع ظهور زر "موقعي الجغرافي" من خلال الاتصال بالرقم التالي:
UiSettings.setMyLocationButtonEnabled(false)
.
يمكن لتطبيقك الاستجابة للأحداث التالية:
- إذا نقر المستخدم على زر "موقعي الجغرافي"، يتلقّى تطبيقك مكالمة
onMyLocationButtonClick()
من العميلGoogleMap.OnMyLocationButtonClickListener
. - إذا نقر المستخدم على النقطة الزرقاء لموقعي الجغرافي، فسيتلقّى تطبيقك
معاودة الاتصال "
onMyLocationClick()
" منGoogleMap.OnMyLocationClickListener
واجهة برمجة التطبيقات Location API في "خدمات Google Play"
Location API ضمن "خدمات Google Play" هي الطريقة المفضّلة لإضافة ميزة التعرّف على المواقع الجغرافية إلى تطبيق Android ويشمل وظائف تتيح لك إجراء ما يلي:
- حدِّد الموقع الجغرافي للجهاز.
- الاستماع إلى التغييرات في الموقع الجغرافي
- حدِّد وسيلة النقل، إذا كان الجهاز يتحرّك.
- إنشاء مناطق جغرافية محدّدة مسبقًا، والتي تُعرف باسم "حدود جغرافية"، ومراقبتها
تسهّل لك واجهات برمجة التطبيقات المتعلّقة بالموقع الجغرافي إنشاء تطبيقات تتحكّم في استهلاك الطاقة وتراعي الموقع الجغرافي. مثلما الحال مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android، لا شك في أنّ يتم توزيع واجهة برمجة التطبيقات كجزء من حزمة تطوير البرامج (SDK) لخدمات Google Play. لمزيد من المعلومات حول Location API، يُرجى الرجوع إلى فئة التدريب على Android إتاحة معلومات الموقع الجغرافي لتطبيقك أو مرجع Location API . يتم تضمين أمثلة الرموز كجزء من إرشادات حزمة تطوير البرامج (SDK) لخدمات Play