HTML5 Geolocation API

HTML5 Geolocation API يتم استخدام Geolocation لتحديد موقع العميل (زائر موقعك).

HTML5 Geolocation API

ما هو Geolocation؟

تتيح لك ميزة Geolocation بتنسيق HTML5 معرفة الإحداثيات الجغرافية (أرقام خطوط الطول والعرض) للموقع الحالي لزائر موقعك على الويب.

1. نظرًا لأن هذا يمكن أن يضر بالخصوصية ، فإن الوظيفة غير متاحة ما لم يوافق عليها المستخدم.
2. Geolocation أكثر دقة مع الأجهزة المزودة بنظام GPS، مثل الهواتف الذكية.

تحديد إحداثيات الزائر عن طريق Geolocation

يعد الحصول على معلومات موقع زائر الموقع باستخدام واجهة برمجة تطبيقات تحديد الموقع الجغرافي بتنسيق HTML5 أمرًا بسيطًا، حيث يمكنك تحديد إحداثيات الزائر بإستخدام الطرق الثلاث [ ()getCurrentPosition و ()watchPosition و ()clearWatch ] التي تم تجميعهم في كائن يسمى navigator.geolocation:

var geolocation = navigator.geolocation;

مثال للتوضيح (يقوم هذا المثال بتحديد الموقع الجغرافي الذي يعرض موقعك الحالي):

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Example To: Get Current Position</title>
  </head>
  <body>
    <div id="outputs">
        <!-- All Position information user will be inserted here -->
    </div>
    <button type="button" onclick="getMyPosition();">Get My Position</button>

    <script>
        function getMyPosition() {
            var geolocation = navigator.geolocation;
            if(geolocation) {
                geolocation.getCurrentPosition(function(position) {
                    var userPositionInfo = "Your current position is (" + "Latitude: " + position.coords.latitude + ", " + "Longitude: " + position.coords.longitude + ")";
                    document.getElementById("outputs").innerHTML = userPositionInfo;
                });
            } else {
                // This alert will be run when HTML5 geolocation not support in browser!
                alert("Sorry, your browser does not support HTML5 geolocation.");
            }
        }
    </script>
  
   </body>
</html>

1. فى المثال السابق، يجب علي الزائر أولاً الموافقة على السماح للمتصفح بإخبار خادم الويب عن موقعه، وإلا لن تشارك متصفحات الويب موقع الزائر.

2. خاصية الـ coords تحدد الموقع الجغرافي للجهاز، يتم التعبير عن الموقع كمجموعة من الإحداثيات الجغرافية مع معلومات حول العنوان والسرعة.

معالجة الأخطاء والرفض Handling Errors & Rejections

إذا فشلت في الحصول على موقع المستخدم (قد يكون هناك موقف لا يرغب فيه المستخدم في مشاركة بيانات موقعه معك)، للتعامل مع مثل هذه المواقف ، يمكنك استخدام الـ parameter الثانية للطريقة ()getCurrentPosition لمعالجة الأخطاء.

يمكنك معالجة الأخطاء عن طريق هذا الكود:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Handling the Geolocation Errors and Rejections</title>
  </head>
  <body>
    <div id="outputs">
        <!-- All Position information user will be inserted here -->
    </div>
    <button type="button" onclick="getMyPosition();">Get My Position</button>
   
    <script>
        
        var outputs; // Make global variable
        
        function getMyPosition() {

            // This variable for Store outputs
            outputs = document.getElementById("outputs");
            
            // If geolocation is available
            if(navigator.geolocation) {

                navigator.geolocation.getCurrentPosition(successCallback, errorCallback);
                outputs.innerHTML = "Getting User position information...";

            } else {

                // This alert will be run when HTML5 geolocation not support in browser!
                alert("Sorry, your browser does not support HTML5 geolocation.");
            }
        };
        
        // Define callback function for successful
        function successCallback(position) {
            outputs.innerHTML = "Your current position is (" + "Latitude: " + position.coords.latitude + ", " + "Longitude: " + position.coords.longitude + ")";
        }
        
        // Define callback function for failed
        function errorCallback(error) {

            if(error.code == 1) { // code 1 == PERMISSION_DENIED

            outputs.innerHTML = "User denied the request for Geolocation.";

            } else if(error.code == 2) { // code 2 == POSITION_UNAVAILABLE

                outputs.innerHTML = "Location information is unavailable.";

            } else if(error.code == 3) { // code 3 == TIMEOUT

                outputs.innerHTML = "The request to get user location timed out.";

            } else { // 'else' here == UNKNOWN_ERROR

                outputs.innerHTML = "Geolocation failed due to unknown error.";
                
            }

        }
    </script>
  
   </body>
</html>

أو عن طريق هذا الكود:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Handling the Geolocation Errors and Rejections</title>
  </head>

  <body>
    <div id="outputs">
        <!-- All Position information user will be inserted here -->
    </div>
    <button type="button" onclick="getMyPosition();">Get My Position</button>

    <script>
        var outputs; // Make global variable

        function getMyPosition() {

            // This variable for Store outputs
            outputs = document.getElementById("outputs");

            // If geolocation is available
            if (navigator.geolocation) {

                navigator.geolocation.getCurrentPosition(successCallback, errorCallback);
                outputs.innerHTML = "Getting User position information...";

            } else {

                // This alert will be run when HTML5 geolocation not support in browser!
                alert("Sorry, your browser does not support HTML5 geolocation.");
            }
        };

        // Define callback function for successful
        function successCallback(position) {
            outputs.innerHTML = "Your current position is (" + "Latitude: " + position.coords.latitude + ", " + "Longitude: " + position.coords.longitude + ")";
        }

        function errorCallback(error) {

            switch (error.code) {

                case error.PERMISSION_DENIED:
                    outputs.innerHTML = "User denied the request for Geolocation."
                    break;

                case error.POSITION_UNAVAILABLE:
                    outputs.innerHTML = "Location information is unavailable."
                    break;

                case error.TIMEOUT:
                    outputs.innerHTML = "The request to get user location timed out."
                    break;

                case error.UNKNOWN_ERROR:
                    outputs.innerHTML = "Geolocation failed due to unknown error"
                    break;
            }
        }
    </script>

  </body>
</html>

كلًا من الطريقتين السابقين سيعطوا نفس النتيجة أو المخرجات بدون إختلاف:

توضيح بعض الخصائص الموجوده فى الأمثلة السابقة:

الخاصية (Property)	الوصف
code	تحتوي هذه الخاصية على ارقام رموز الأخطاء. ارقام رموز الأخطاء المحتملة التي يتم إرجاعها في كائن PositionError: “0” = UNKNOWN_ERROR (أى فشل الطريقة في جلب موقع الجهاز بسبب خطأ غير معروف). “1” = PERMISSION_DENIED (أى فشل الطريقة في جلب موقع الجهاز لأن ليس لديه إذن لاستخدام خدمة الموقع). “2” = POSITION_UNAVAILABLE (أى لا يمكن تحديد موقع الجهاز). “3” = TIMEOUT (أى لم تتمكن الطريقة من جلب معلومات الموقع خلال الحد الأقصى لفترة المهلة المحددة).
message	يحتوي على وصف للخطأ يمكن قراءته.

الخاصية
(Property)

الوصف

code

تحتوي هذه الخاصية على ارقام رموز الأخطاء.

ارقام رموز الأخطاء المحتملة التي يتم إرجاعها في كائن PositionError:

“0” = UNKNOWN_ERROR (أى فشل الطريقة في جلب موقع الجهاز بسبب خطأ غير معروف).
“1” = PERMISSION_DENIED (أى فشل الطريقة في جلب موقع الجهاز لأن ليس لديه إذن لاستخدام خدمة الموقع).
“2” = POSITION_UNAVAILABLE (أى لا يمكن تحديد موقع الجهاز).
“3” = TIMEOUT (أى لم تتمكن الطريقة من جلب معلومات الموقع خلال الحد الأقصى لفترة المهلة المحددة).

message

يحتوي على وصف للخطأ يمكن قراءته.

عرض الموقع على خريطة جوجل Google map

لعرض النتيجة في خريطة ، تحتاج إلى الوصول إلى خدمة الخرائط (Maps service)، مثل خرائط Google.

مثال للتوضيح (سيُظهر المثال التالي موقعك الحالي على خريطة Google استنادًا إلى بيانات خطوط الطول والعرض المستردة من خلال ميزة Geolocation [باستخدام صورة ثابتة]):

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Show Position In Google Map</title>
  </head>
  <body>

    <div id="googleMap">
        <!--Google map will be appear here-->
    </div>
    <button type="button" onclick="getMyPosition();">Get My Position In Map</button>

    <script>
        function getMyPosition() {
            navigator.geolocation.getCurrentPosition(showInMap);
        }

        function showInMap(position) {
            // Get location data
            var latlong = position.coords.latitude + "," + position.coords.longitude;

            // Set Google map source url
            var img_map_url = "https://maps.googleapis.com/maps/api/staticmap?center="+latlon+"&zoom=14&size=400x300&sensor=false&key=YOUR_KEY";

            // Create Img and insert Google map
            document.getElementById("googleMap").innerHTML = "<img alt='Map Info' src='" + img_map_url + "'>";
        }
    </script>

  </body>
</html>

كيفية مراقبة حركة الزائر؟

يحتوي كائن geolocation على طريقة تسمى ()watchPosition تسمح لك بتتبع حركة الزائر من خلال إعادة الموقع المحدث مع تغير الموقع، كالتالى:

var outputs = document.getElementById("outputs");

function getLocation() {
    if (navigator.geolocation) {
        navigator.geolocation.watchPosition(showPosition);
    } else {
        alert("Sorry, your browser does not support HTML5 geolocation.");
    }
}

function showPosition(position) {
    outputs.innerHTML = "Latitude: " + position.coords.latitude +
        "<br>Longitude: " + position.coords.longitude;
}

Geolocation Methods

يوفر كائن Geolocation الطرق التالية:

الطريقة (method)	الوصف
()getCurrentPosition	تقوم هذه الطريقة بجلب الموقع الجغرافي الحالي للمستخدم.
()watchPosition	تقوم هذه الطريقة بعرض الموقع الحالي للمستخدم ويستمر في إرجاع الموقع المحدث أثناء تحرك المستخدم.
()clearWatch	تقوم هذه الطريقة بتوقف طريقة ()watchPosition.

1. ()watchPosition لها نفس parameters الإدخال مثل ()getCurrentPosition.
2. method الـ ()watchPosition مثل الـ GPS الموجود في الهواتف والسيارات.

getCurrentPosition() Properties

تقوم طريقة ()getCurrentPosition بإرجاع كائن عند النجاح، حيث يحتوى هذا الكائن على بعض الخصائص، وهم كالتالى:

الخاصية (Property)	الوصف
coords.latitude	يحدد خط العرض بالدرجات العشرية. نطاق القيمة [-90.00 ، +90.00].
coords.longitude	يحدد خط الطول بالدرجات العشرية. نطاق القيمة هو [-180.00 ، +180.00].
coords.altitude	يحدد الارتفاع بالأمتار فوق متوسط مستوى سطح البحر (يُعاد إذا كان متاحًا).
coords.accuracy	يحدد دقة تقديرات خطوط الطول والعرض بالأمتار.
coords.altitudeAccuracy	يحدد دقة تقدير الارتفاع بالأمتار.
coords.heading	يحدد الاتجاه الحالي للجهاز للحركة بالدرجات التي يتم احتسابها في اتجاه عقارب الساعة من الشمال (يُعاد إذا كان متاحًا).
coords.speed	يحدد السرعة الأرضية الحالية للجهاز بالأمتار في الثانية (يُعاد إذا كان متاحًا).
timestamp	يحدد الوقت الذي تم فيه استرداد معلومات الموقع (يُعاد إذا كان متاحًا).