تجربة العرض التوضيحي

من خلال دمج حزمة SDK للتنقل في نظام التشغيل Android، يستطيع تطبيقك تجاوز الارتباط بعرض خريطة خارجي. باستخدام التنقل في خرائط Google، يمكن أن يوفر تطبيقك استرجاعًا ديناميكيًا وتقارير أحادية النظر للبيانات حول رحلة السائق.

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

حزمة SDK للتنقل هي مكتبة ثابتة تمنحك إمكانية التحكم في الشكل والصوت للتنقل في تطبيقك. وللحصول على تفاصيل عن المكتبة، افتح مرجع حزمة SDK الخاصة بالتنقّل (Javadoc) في نافذة منفصلة.

الاستعداد

ملاحظة مهمة: بدءًا من الإصدار 3.0 من حزمة تطوير البرامج (SDK) الخاصة بالتنقل لنظام التشغيل Android، يمكنك الحصول على أحدث إصدار من حزمة SDK الخاصة بالتنقل لنظام التشغيل Android من مستودع Maven. وهذه هي الطريقة المفضّلة للحصول على حزمة SDK. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد مشروعك.

ملاحظة: يتم التحكّم في الوصول إلى حزمة SDK للتنقّل من خلال مجموعة مساحة عمل. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة الحصول على إذن بالوصول.

لبدء استخدام حزمة SDK للتنقل، تأكد من توفر العناصر التالية.

• ممثّل "منصة خرائط Google" الذي يوفّر إمكانية الوصول إلى ما يلي:

  • مفتاح واجهة برمجة تطبيقات تم توفيره للاستخدام مع حزمة تطوير البرامج (SDK) للتنقّل. عليك تقديم رقم تعريف المشروع الذي يمكنك العثور عليه في لوحة البيانات الرئيسية في Google Cloud Console، ضمن اسم المشروع.
  • عنصر حزمة تطوير البرامج (SDK) تأكّد من ضبط مشروعك لاستخدام Maven في حزمة تطوير البرامج (SDK) الخاصة بالتنقل.
  • بالنسبة إلى المشاريع التي تستخدم الإصدار 4.99.0 والإصدارات الأقدم: إذا لم تتمكن من استخدام Maven، يمكنك تنزيل العنصر المضغوط من Google Drive المشترك. وملف المكتبة الثابت هو ملف .aar في دليل libs/ الذي يحتوي على حزمة تطوير البرامج (SDK) الخاصة بالتنقّل على شكل حزمة AAR.
  • تطبيق واحد أو أكثر من التطبيقات التجريبية

• استوديو Android، بيئة التطوير الموصى بها لإنشاء تطبيق باستخدام حزمة SDK للتنقل.

هذه المستندات مُصمّمة للأشخاص الذين لديهم دراية بمفاهيم تطوير Android والبرمجة الموجَّهة للعناصر. يجب أيضًا أن تكون على دراية بخرائط Google من وجهة نظر المستخدم.

الحصول على التطبيقات التجريبية

توفر Google تطبيقين لمساعدتك على فهم ما تقدمه حزمة SDK للتنقل في أعلى واجهات برمجة التطبيقات لخرائط Google، بناءً على مستوى خبرتك. يمكن للمطورين على دراية بواجهات برمجة تطبيقات خرائط Google تركيز انتباههم على العرض التوضيحي لـ Google Navigation. سيجد المطورون الجدد في كلا المشروعين أن كلا التطبيقين مفيدان.

بدءًا من حزمة SDK للتنقل لنظام التشغيل Android الإصدار 4.1، يتوفر التطبيقان التجريبيان التاليان في Google Drive المشترك للتنزيل.

• الإصدار التجريبي من Google Navigation: يعرض عملية دمج سلوكيات وطرق عرض واجهة برمجة التطبيقات لأنّها تتعلق بتجربة المستخدم أثناء التصفّح في جلسة التنقّل الموجّهة.

• عرض توضيحي لخريطة Google: يعرض السلوكيات الفردية لواجهة GoogleMap لتخصيص مظهر الخرائط وطريقة عرضها.

ملاحظة حول استخدام Maven

تم إعداد التطبيقات التجريبية لتنزيل أداة SDK من مستودع Maven البعيد، باستخدام المكوّن الإضافي Artifact Registry في Gradle. تأكَّد من اتّباع تعليمات ضبط المشروع للحصول على إذن بالوصول إلى حزمة SDK.

ملاحظة: بالنسبة إلى الإصدارات 4.99.0 والإصدارات الأقدم، إذا كنت لا تزال تريد استخدام حزمة AAR الأولية في مشروعك، يمكنك إضافتها إلى مشروعك ضمن دليل libs. بعد ذلك، عليك إزالة جميع المراجع الخاصة بالمكوّن الإضافي artifactregistry والمستودع البعيد ذي الصلة، والإشارة إلى تبعية AAR التالية في build.gradle على مستوى التطبيق: api(name: 'google_navigation', ext: 'aar')

الإصدار التجريبي من Google Navigation

يتوفر أحدث إصدار تجريبي من Googlenavigation في جذر Google Drive المشترك. توجد الإصدارات السابقة من التطبيق في "الأرشيف". وبالنسبة إلى الإصدارات التي تسبق الإصدار 4.1، يتم تجميع التطبيق مع الاقتراحات المطبّقة تلقائيًا في ملف ZIP نفسه.

مدّ

1. في استوديو Android، استورِد التطبيق التجريبي واسمَح بتشغيل Gradle.

   ملاحظة: يتعذّر على التطبيق تحميل الخريطة إلى أن يتم تحديث local.defaults.properties باستخدام مفتاح واجهة برمجة التطبيقات المتوفر.

2. افتح local.defaults.properties وعدِّل قيمة السمة MAPS_API_KEY:

     MAPS_API_KEY=YOUR_API_KEY
   

3. انقر على إنشاء وافحص تفاصيل تنفيذ حزمة تطوير البرامج (SDK).

   • في فئة Java، لاحظ رمز التنفيذ.

   • في تنسيق XML، لاحِظ تصميم التنسيق ونصه.

   • في ملف build.gradle، لاحظ حزمة SDK في التبعيات.

راجِع وثائق المكوّن الإضافي Secret Gradle للحصول على مزيد من المعلومات حول كيفية إضافة مفتاح واجهة برمجة التطبيقات إلى البيان.

الجري

1. وصِّل جهاز Android بجهاز الكمبيوتر أو استخدِم أحد المحاكيات.

   • جهاز Android: يمكنك الرجوع إلى instructions لتفعيل خيارات المطوّرين على جهاز Android وضبط نظامك لرصد الجهاز.
   • أداة المحاكاة: استخدِم مدير جهاز Android الافتراضي (AVD) لضبط جهاز افتراضي. عند اختيار المحاكي، تأكد من اختيار صورة تتضمن Google APIs.

2. في استوديو Android، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل)، ثم اختَر هدف نشر.

عند إنشاء التطبيق وإطلاقه، يقدم للمستخدم صفحة مقصودة تضم قائمة من الخيارات.

خيارات NavViewActivity وNavFragmentActivity

من المرجّح أن يستفيد المستخدمون الجُدد من NavSDK من هذين الخيارين.

الخيار الأول: تعرض السمة NavViewActivity السلوكيات باستخدام NavigationView بالإضافة إلى Navigator.

الخيار الثاني: يعرض الخيار الثاني، المسمى NavFragmentActivity، السلوكيات باستخدام SupportNavigationFragment إلى جانب Navigator.

عند النقر على أحد هذه الخيارات، سيظهر لك ما يلي:

• واجهة مستخدم التنقل
• زر "تعيين الوجهة" في قائمة التطبيق
• تراكب يمكنك التفاعل معه لاستدعاء الطرق ديناميكيًا على واجهة برمجة التطبيقات
• قائمة كاملة بها مزيد من الخيارات

للبدء، انقر على تحديد الوجهة واختَر عنوانًا. ثم يحاكي التطبيق رحلة من موقعك الحالي إلى ذلك العنوان. استخدم تراكب لوحات التحكم لمعرفة ما يحدث عند استدعاء واجهة برمجة تطبيقات. على سبيل المثال، يمكنك النقر على عرض الطرق لمحاولة فرض وضع SDK في الوضع الليلي لمعرفة ما يبدو عليه.

خيار SwapingmapAndNavActivity

ملاحظة: يساعدك هذا الخيار في الانتقال من الإصدار 1 إلى الإصدار 4. ننصح باستخدام NavigationView حصريًا حيثما أمكن، لكنّنا نقدّم هذا كمثال على كيفية استخدام كلتا الطريقتين يدويًا.

يعرض SwappingMapAndNavActivity الأنماط الشائعة التالية:

• يعرض MapView
• التبديل إلى NavigationView عندما يبدأ التنقل
• العودة إلى MapView عند انتهاء التنقّل

الإصدار التجريبي من "خرائط Google"

ملاحظة: لا يتوفّر هذا التطبيق لإصدارات حزمة تطوير البرامج (SDK) التي تسبق الإصدار 4.1.

يتوفر أحدث إصدار تجريبي من Googleالتنقل في جذر Google Drive المشترك. توجد الإصدارات السابقة من التطبيق في "الأرشيف".

مدّ

1. في استوديو Android، استورِد التطبيق التجريبي واسمَح بتشغيل Gradle.

   ملاحظة: لن يتمكّن التطبيق من تحميل الخريطة إلى أن يتم تعديل Local.defaults.properties باستخدام مفتاح واجهة برمجة التطبيقات المقدّم.

2. افتح local.defaults.properties وعدِّل قيمة السمة MAPS_API_KEY:

     MAPS_API_KEY=YOUR_API_KEY
   

3. انقر على إنشاء وافحص تفاصيل تنفيذ حزمة تطوير البرامج (SDK).

   • في فئة Java، لاحظ رمز التنفيذ.

   • في تنسيق XML، لاحِظ تصميم التنسيق ونصه.

   • في ملف build.gradle، لاحظ حزمة SDK في التبعيات.

لمعرفة مزيد من المعلومات حول كيفية إضافة مفتاح واجهة برمجة التطبيقات إلى ملف البيان، يمكنك الاطّلاع على المكوّن الإضافي secrets gradle.

الجري

1. وصِّل جهاز Android بجهاز الكمبيوتر أو استخدِم أحد المحاكيات.

   • جهاز Android يُرجى الرجوع إلى instructions لتفعيل خيارات المطوّرين على جهاز Android وإعداد نظامك لاكتشاف الجهاز.
   • المحاكي يمكنك استخدام مدير جهاز Android الافتراضي (AVD) لضبط جهاز افتراضي. عند اختيار المحاكي، تأكد من اختيار صورة تتضمن Google APIs.

2. في استوديو Android، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل)، ثم اختَر هدف نشر.

عند إنشاء التطبيق وإطلاقه، يقدم للمستخدم صفحة مقصودة من قائمة العروض التوضيحية.

يجب أن يكون نمط العرض التقديمي هذا والبنية المقابلة لرمز المصدر مألوفين لمستخدمي عروض SDK لخرائط Google. وهذا لأن الإصدار التجريبي لخريطة Google تم تصميمه ليكون شبيهًا بالتطبيق التجريبي لواجهة برمجة تطبيقات الخرائط. يتمثل الاختلاف الأساسي في أن الإصدار التجريبي من حزمة SDK للتنقل يتيح للمستخدم اختيار صف العرض الذي يريد إجراء اختبار تشغيل تجريبي عليه: NavigationView أو MapView، حيثما ينطبق ذلك.

تشجّع Google بشكل عام المستخدمين على استخدام NavigationView. يوفّر هذا العرض التوضيحي مرونة في تجربة هذه السلوكيات على كِلا الإصدارَين في تطبيقنا التجريبي واختيار تلك التي تناسبك. على سبيل المثال، قد يكون من الضروري استخدام علامة MapView في الحالات التي تستخدم فيها مكتبة تابعة لجهة خارجية تتوقّع التفاعل مع ذلك الصف.

ملاحظة مُهمة: تتطلّب الصفوف MapView MapFragment وSupportMapFragment تثبيت تطبيق "خدمات Google Play" على الأجهزة. في حال تدوير محاكي جديد أو إعادة ضبط جهاز قديم جدًا على الإعدادات الأصلية، قد يتم إرفاق "خدمات Google Play" القديمة جدًا في صورة Android. في هذه الحالات، عليك الانتظار حتى تحصل على إصدار أحدث تلقائيًا، أو تحديث "خدمات Play" يدويًا من خلال "متجر Google Play".