النسخة التجريبية

من خلال دمج حزمة تطوير البرامج للتنقّل على أجهزة Android، يمكن لتطبيقك تجاوز مجرد الربط بعرض خارجي للخريطة. باستخدام ميزة التنقّل باتّجاهات مفصّلة في "خرائط Google"، يمكن لتطبيقك استرداد البيانات بشكل ديناميكي وتقديم تقارير بنظرة واحدة عن رحلة المستخدم. يوضّح هذا الدليل كيفية تشغيل التطبيقات التجريبية لحزمة تطوير البرامج للتنقّل، والتي تتوفّر على GitHub.

الاستعداد

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

• مفتاح واجهة برمجة تطبيقات تم توفيره لاستخدامه مع حزمة تطوير البرامج للتنقّل يمكنك الاطّلاع على مقالة استخدام مفاتيح واجهة برمجة التطبيقات لمزيد من المعلومات عن إنشاء المفاتيح وتقييدها.
• ملف حزمة تطوير البرامج (SDK) تأكَّد من ضبط مشروعك لاستخدام Maven لحزمة تطوير البرامج للتنقّل.
• تطبيق تجريبي واحد أو أكثر من تطبيقات العرض التوضيحي.
• استوديو Android، وهو بيئة التطوير المقترَحة لإنشاء تطبيق باستخدام حزمة تطوير البرامج للتنقّل.

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

ملاحظة: إذا كان تطبيقك يستخدم حاليًا حزمة تطوير البرامج لخرائط Google، ستحلّ حزمة تطوير البرامج للتنقّل محلّ حزمة تطوير البرامج لخرائط Google لكلّ من طبقة الخريطة وميزات التنقّل. لا يمكنك استخدام حزمة تطوير البرامج للتنقّل وحزمة تطوير البرامج لخرائط Google في التطبيق نفسه.

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

توفّر Google تطبيقَين لمساعدتك في فهم ما تقدّمه حزمة تطوير البرامج للتنقّل بالإضافة إلى واجهات برمجة التطبيقات لخرائط Google، وذلك حسب مستوى خبرتك. يمكن للمطوّرين الذين لديهم خبرة في واجهات برمجة التطبيقات لخرائط Google التركيز على التطبيق التجريبي GoogleNavigation. سيكون كلا التطبيقَين مفيدًا للمطوّرين الجدد في كلا المشروعَين.

اعتبارًا من الإصدار 4.1 من حزمة تطوير البرامج للتنقّل على أجهزة Android، يتوفّر كلا التطبيقَين التجريبيَين على GitHub لتنزيلهما.

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

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

التطبيق التجريبي GoogleNavigation

يتوفّر أحدث تطبيق تجريبي GoogleNavigation على GitHub.

إنشاء

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 plugin لمزيد من المعلومات عن كيفية إضافة مفتاح واجهة برمجة التطبيقات إلى ملف البيان.

الجري

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

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

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

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

خيارات NavViewActivity وNavFragmentActivity

من المرجّح أن يجد المستخدمون الجدد لحزمة تطوير البرامج للتنقّل هذَين الخيارَين الأكثر فائدة.

الخيار 1: NavViewActivity يعرض السلوكيات باستخدام NavigationView مع Navigator.

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

ملاحظة: في معظم الحالات، ننصح باستخدام SupportNavigationFragment، وهو برنامج تضمين لـ NavigationView، بدلاً من التفاعل مباشرةً مع NavigationView. لمزيد من المعلومات، يُرجى الاطّلاع على أفضل ممارسات التفاعل مع خريطة التنقّل .

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

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

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

الخيار SwappingMapAndNavActivity

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

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

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

التطبيق التجريبي GoogleMap

يتوفّر أحدث تطبيق تجريبي GoogleNavigation على GitHub.

ملاحظة: لمزيد من المعلومات عن التفاعل مع عنصر GoogleMap في تطبيقك، يُرجى الاطّلاع على أفضل ممارسات التفاعل مع GoogleMap.

إنشاء

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 plugin لمزيد من المعلومات عن كيفية إضافة مفتاح واجهة برمجة التطبيقات إلى ملف البيان.

الجري

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

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

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

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

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

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

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