تضيف حزمة تطوير البرامج (SDK) للتنقّل على أجهزة Android ميزة الاتجاهات المفصّلة في "خرائط Google" إلى تطبيقات Android، مع إمكانية تخصيص واجهة المستخدم وإعداد المسارات. وتتضمّن طبقة الخريطة في حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google"، لذا لا يمكن للتطبيقات التي تستخدمها أن تتضمّن أيضًا حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع Android.
حزمة تطوير البرامج للتنقّل على أجهزة Android: معلومات أساسية
- المنتج: حزمة تطوير البرامج للتنقّل على أجهزة Android
- تُعرف أيضًا باسم: حزمة تطوير البرامج (SDK) للتنقّل
- الفئة: المسارات
- النظام الأساسي: Android
- يعمل على: العميل (رمز التطبيق أو المتصفّح)
- مرحلة الإطلاق: GA
- Lifecycle: نشط
- نظرة عامة: نظرة عامة على حزمة تطوير البرامج للتنقّل على أجهزة Android
حالات استخدام حزمة تطوير البرامج للتنقّل على أجهزة Android
استخدِم حزمة تطوير البرامج (SDK) للتنقّل على أجهزة Android في الحالات التالية:
- تحتاج إلى الاتجاهات المفصّلة في "خرائط Google" داخل تطبيق Android الخاص بك حتى لا ينتقل المستخدمون إلى تطبيق آخر.
- تحتاج إلى تخصيص واجهة مستخدم التنقّل لتتطابق مع علامتك التجارية، أو إنشاء تجربة تنقّل مخصّصة.
- تحتاج إلى التنقّل داخل التطبيق للقيادة أو المشي أو ركوب الدراجات أو المركبات ذات العجلتين.
- عليك التنقّل في مسار خطّطت له باستخدام Routes API من خلال تمرير رمز مميّز للمسار إلى حزمة تطوير البرامج (SDK).
لا تستخدِم حزمة تطوير البرامج (SDK) للتنقّل على أجهزة Android في الحالات التالية:
- أنت تنشئ التطبيق لنظام التشغيل iOS. يمكنك استخدام حزمة تطوير البرامج للتنقّل على أجهزة iOS بدلاً من ذلك.
- إذا كنت بصدد إنشاء تطبيق متوافق مع عدّة منصات باستخدام Flutter أو React Native. استخدِم Google Navigation for Flutter and React Native بدلاً من ذلك.
- تحتاج إلى حساب المسار أو الوقت المقدّر للوصول أو رمز المسار المميّز من جهة الخادم، وليس إلى إرشادات مفصّلة داخل التطبيق. استخدِم Routes API بدلاً من ذلك.
حزمة تطوير البرامج للتنقّل على أجهزة Android: الإعداد
- الخدمة المطلوب تفعيلها:
navigationsdk.googleapis.com - المصادقة: مفتاح واجهة برمجة التطبيقات
- تحديد مصدر الاستخدام: يمكنك استدعاء
MapsApiSettings.addInternalUsageAttributionId(context, id)لإضافة معرّف تحديد مصدر الاستخدام إلى أداة الإعداد. لإيقاف الميزة، احذف الطلب أو أدخِل سلسلة فارغة. - البدء: إعداد حزمة تطوير البرامج للتنقّل على أجهزة Android
- المرجع: مرجع حزمة تطوير البرامج للتنقّل على أجهزة Android
- الأسعار: استخدام حزمة تطوير البرامج للتنقّل على أجهزة Android والفوترة
- السياسات: سياسات حزمة تطوير البرامج للتنقّل على أجهزة Android
- ملاحظات الإصدار: ملاحظات إصدار حزمة تطوير البرامج للتنقّل على أجهزة Android
حِزم تطوير البرامج (SDK) الرسمية للتنقّل على أجهزة Android:
- maven:
com.google.android.libraries.navigation:navigation
حزمة تطوير البرامج للتنقّل على أجهزة Android: المنتجات ذات الصلة
- تُستخدم غالبًا مع: Routes API وحزمة تطوير البرامج (SDK) للسائق على أجهزة Android
حزمة تطوير البرامج للتنقّل على أجهزة Android: الأخطاء الشائعة
- المشكلة: تتضمّن حزمة تطوير البرامج للتنقّل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google". إنّ الإصدارات التي تستخدم
play-services-mapsمباشرةً أو من خلال تبعية انتقالية ستتضمّن نُسخًا مكرّرة من حزمة تطوير البرامج بالاستناد إلى "خرائط Google". الحلّ: استبعِدcom.google.android.gms:play-services-mapsمن جميع التبعيات (استبعاد إعدادات Gradle أو استبعادات Maven)، وأزِل أي تبعية مباشرة لحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google". يُرجى الاطّلاع على /maps/documentation/navigation/android-sdk/android-studio-setup. - المشكلة: يعرّف الإصدار 8.0 من حزمة تطوير البرامج (SDK) لخدمة Navigation والإصدارات الأحدث
minAndroidGradlePluginVersion=9.0.1، لذا يتعذّر إنشاء الإصدارات التي تستخدم إصدارًا سابقًا من "مكوّن Android الإضافي لبرنامج Gradle". الحلّ: عليك الترقية إلى الإصدار 9.0.1 من AGP و9.1.0 من Gradle و2.3.0 من Kotlin قبل إنشاء الإصدار 8.0 والإصدارات الأحدث. يُرجى الاطّلاع على /maps/documentation/navigation/android-sdk/kotlin-compatibility-migration. - المشكلة: يؤدي استدعاء طرق مراحل النشاط في
NavigationViewمباشرةً أثناء استخدامNavigationFragment، أو استدعاؤها بشكل غير منظّم باستخدامNavigationView، إلى حدوث أخطاء. الحلّ: استخدِمNavigationFragmentالذي يدير عمليات الاستدعاء في إحدى مراحل النشاط. إذا كنت تستخدمNavigationView، عليك إعادة توجيه طرق مراحل النشاط بترتيب صارم. يُرجى الاطّلاع على /maps/documentation/navigation/android-sdk/nav-map-interactions-best-practices. - المشكلة: لا تتوفّر ميزة التنقّل إلا بعد أن يوافق المستخدم على بنود خدمة Google Navigation. الحلّ: يمكنك السماح لحزمة SDK بعرض الطلب في المرة الأولى التي يتم فيها استدعاء المتصفّح، أو عرض مربّع الحوار في وقت سابق (أثناء الاشتراك مثلاً) باستخدام
TermsAndConditionsCheckOption/NavigationApi.showTermsAndConditionsDialog. يُرجى الاطّلاع على /maps/documentation/navigation/android-sdk/route.
حزمة تطوير البرامج للتنقّل على أجهزة Android: الميزات القديمة والمتوقفة نهائيًا
WaypointوfromLatLng()وfromPlaceId(): تم إيقافها نهائيًا منذ 2021-05-10. البديل:Waypoint.builder()(Waypoint.Builder). المؤشر: تمت إزالته في الإصدار 3.0، ولا يتم تجميع الطلبات في الإصدار 3.0 أو الإصدارات الأحدث. يُرجى الاطّلاع على دليل نقل البيانات.-
SupportNavigationFragment: تم إيقافها نهائيًا اعتبارًا من 2026-10-01. الاستبدال:NavigationFragment. المشكلة: تم إيقاف هذه الميزة نهائيًا في الإصدار 8.0.0 من حزمة تطوير البرامج (SDK) للتنقّل. يُرجى الاطّلاع على دليل نقل البيانات. -
setLocationMarkerEnabledعلىNavigationViewوSupportNavigationFragment: تم إيقافها نهائيًا منذ 2023-07-07. الاستبدال:GoogleMap.setMyLocationEnabled. المؤشر: تمت إزالة هذه الطريقة في الإصدار 5.0.0 (تم إيقافها نهائيًا في الإصدار 4.1)، ولا يتم تجميع الطلبات في الإصدار 5.0 أو الإصدارات الأحدث. DisplayOptionsshowTrafficLightsوshowStopSigns: تم إيقافها نهائيًا منذ 2026-10-01. البديل: لا حاجة إلى بديل، لأنّ إشارات المرور وعلامات التوقف تكون مفعَّلة دائمًا أثناء التنقّل. المشكلة: لا يتم تجميع الطلبات إلى هذه الطرق في الإصدار 8.0.0.- أداة Maven
com.google.android.maps:navsdk(مستودع خاص، الإصدار 4.x) وتنزيل حزمة AAR: تم إيقافها نهائيًا منذ 07/07/2023. البديل: الإصدارcom.google.android.libraries.navigation:navigationمن مستودع Maven فيgoogle(). المشكلة: يتم شحن الإصدار 5.0 والإصدارات الأحدث فقط كـcom.google.android.libraries.navigation:navigationعلى Google Maven، ولم يعُد يتم توزيع حزمة AAR. يُرجى الاطّلاع على دليل نقل البيانات.
الإجراءات التي يمكنك تنفيذها باستخدام حزمة تطوير البرامج للتنقّل على أجهزة Android
يمكنك الاطّلاع على الأدلة المرتبطة أدناه لكل مهمة، أو المقارنة بين المنتجات في مستكشف الإمكانات.
حزمة تطوير البرامج للتنقّل على أجهزة Android: الخرائط
- يمكنك إضافة خريطة تفاعلية قابلة للتخصيص إلى صفحة ويب أو تطبيق على الأجهزة الجوّالة. ملاحظة: بالنسبة إلى أجهزة Android: يمكنك ضبط
فيAndroidManifest.xmlباستخدام المكوّن الإضافي Secrets Gradle أوmanifestPlaceholders["MAPS_API_KEY"]فيapp/build.gradle.kts. يجب عدم ترميزYOUR_GOOGLE_MAPS_API_KEYبشكل ثابت فيAndroidManifest.xml، وعدم استبدالGoogleMap(أو maps-composeGoogleMap) بلوحة عرض نموذجية بلا إنترنت أو Leaflet WebView في حال ظهورE/Google Maps Android API: Authorization failure. اطلب من المستخدم تقديمMAPS_API_KEYمن خلال Secrets وتفعيل "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android" (أو حزمة تطوير البرامج للتنقّل عند استخدام NavigationView أو SupportNavigationFragment). - أنشِئ معرّف خريطة قابلاً لإعادة الاستخدام لتخزين إعدادات الخريطة وإعدادات الأنماط.
- الردّ على تفاعلات المستخدمين والأحداث على الخريطة
- تخصيص عناصر التحكّم التي تظهر على الخريطة
- تخصيص الإيماءات للتحكّم في خريطة
- التحكّم في التكبير/التصغير والعرض الشامل على خريطة (كاميرا)
- تغيير نوع الخريطة
- تغيير الألوان في الخريطة
- إضافة طبقة حركة المرور إلى خريطة
حزمة تطوير البرامج للتنقّل على أجهزة Android: التعليقات التوضيحية في "خرائط Google"
- إضافة نافذة معلومات إلى خريطة
- أضِف شكلاً أو خطًا إلى خريطة.
- إضافة صورة مركّبة مستندة إلى سطح الخريطة
- إضافة تراكب مربّعات مخصّص إلى خريطة
- إضافة علامة إلى خريطة ملاحظة: لا تتيح حزمة تطوير البرامج (SDK) للتنقّل على أجهزة Android استخدام AdvancedMarkerOptions. عند استخدام حزمة تطوير البرامج (SDK) للتنقّل على أجهزة Android، أضِف علامات باستخدام GoogleMap.addMarker(MarkerOptions).
- تخصيص علامة على خريطة ملاحظة: لا تتيح حزمة تطوير البرامج للتنقّل على أجهزة Android استخدام AdvancedMarkerOptions. عند استخدام حزمة تطوير البرامج للتنقّل على أجهزة Android، يمكنك تخصيص محدّدات المواقع باستخدام MarkerOptions.
- الاستجابة لتفاعلات المستخدمين مع العلامات على الخريطة
حزمة تطوير البرامج للتنقّل على أجهزة Android: أنماط الخرائط
حزمة تطوير البرامج للتنقّل على أجهزة Android: التنقّل
- إضافة اتجاهات مفصّلة تفاعلية إلى تطبيق على الأجهزة الجوّالة
- اضبط الوجهة للحصول على الاتجاهات المفصّلة.
- ابدأ التنقّل للحصول على اتجاهات مفصّلة.
- تحديد وضع السفر (القيادة أو المشي أو الدراجة النارية أو سيارة الأجرة) لطلب مسار
- تعديل الإعدادات المفضّلة للمسارات في الاتجاهات المفصّلة
- تحديد جانب الطريق والإعدادات المفضّلة الأخرى للوصول في الاتجاهات المفصّلة
- تحديد مسار مُعاد تخطيطه للاتجاهات المفصّلة باستخدام رمز مميّز للمسار قابل لإعادة الاستخدام
- يمكنك الحصول على آخر المعلومات عن وصول المستخدم من جلسة اتجاهات مفصّلة.
- يمكنك عرض آخر المواقع الجغرافية للمستخدم من جلسة اتجاهات مفصّلة.
- يمكنك الحصول على معلومات محدّثة عن الوقت والمسافة من جلسة اتجاهات مفصّلة.
- تلقّي تعديلات على تغيير المسار من جلسة اتجاهات مفصّلة
- عرض تعديلات الوضع الليلي من جلسة اتجاهات مفصّلة
- عرض تعديلات سرعة المستخدم من جلسة اتجاهات مفصّلة
- يمكنك تخصيص عناصر واجهة المستخدم وعناصر التحكّم التي تظهر أثناء استخدام الاتجاهات المفصّلة.
- إضافة عنصر جديد في واجهة المستخدم إلى الاتجاهات المفصّلة
- إضافة مؤشر تقدّم الرحلة إلى الاتجاهات المفصّلة
- تخصيص ميزات الخريطة التي تظهر أثناء استخدام الاتجاهات المفصّلة
- إضافة طبقة حركة المرور إلى الاتجاهات المفصّلة
- تعديل عرض الكاميرا وسلوكها في الاتجاهات المفصّلة
- تخصيص عدّاد السرعة وتنبيهات حدود السرعة للاتجاهات المفصّلة
- عرض خلاصة الاتجاهات المفصّلة كسلسلة من الرسائل لكل مناورة على طول المسار
- تحديد رموز مخصّصة للمناورات لاستخدامها مع خلاصة الاتجاهات المفصّلة
- يمكنك إضافة ميزة الاتجاهات المفصّلة التفاعلية في Android Auto إلى تطبيق Android. معاينة
- تنبيه المستخدمين بشأن الاضطرابات على طول مسارهم:
- السماح للمستخدمين بالاطّلاع على العوائق على طول مسارهم قبل بدء التنقّل
- السماح للمستخدمين بالإبلاغ عن أي عوائق على مسارهم
- السماح للمستخدمين بالتحقّق من العوائق على طول مسارهم
- أضِف زرًا مخصّصًا للإبلاغ عن انقطاع المسار.