حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات السريعة على Android

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

هذا الدليل السريع مخصّص للمطوّرين الذين لديهم خبرة في أساسيات تطوير تطبيقات Android باستخدام Kotlin أو Java.

لمحة عن بيئة التطوير

تم تطوير هذا الدليل السريع باستخدام الإصدار Hedgehog من "استوديو Android" والإصدار 8.2 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.

ملاحظة: إذا كانت بيئة التطوير تستخدم إصدارًا مختلفًا من Android Studio أو Gradle، قد تحتاج إلى تعديل الخطوات حسب بيئتك. لمزيد من المعلومات حول إصدارات "استوديو Android" وGradle، يُرجى الاطّلاع على مقالة التوافق بين المكوّن الإضافي لنظام Gradle المتوافق مع Android و"استوديو Android".

إعداد جهاز Android

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

• لاستخدام جهاز Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز.
• لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام مدير أجهزة Android الافتراضية (AVD) المضمّن في "استوديو Android".
  ملاحظة: إذا اخترت استخدام محاكي Android، تأكَّد من اختيار جهاز يظهر عليه رمز Play، ، ضمن عمود متجر Play. يشير هذا الرمز إلى أنّ هذه الملفات الشخصية متوافقة تمامًا مع CTS ويمكنها استخدام صور النظام التي تتضمّن تطبيق "متجر Play":

  

إنشاء مشروع "خرائط Google" في "استوديو Android"

تم تغيير إجراء إنشاء مشروع "خرائط Google" في "استوديو Android" في الإصدار Flamingo والإصدارات الأحدث من "استوديو Android".

1. افتح "استوديو Android"، ثم انقر على مشروع جديد في نافذة مرحبًا بك في "استوديو Android".

2. في نافذة مشروع جديد، ضمن فئة الهاتف والكمبيوتر اللوحي، اختَر بدون نشاط، ثم انقر على التالي.

3. أكمِل نموذج مشروع جديد:

   • اضبط اللغة على Java أو Kotlin. وتتوافق كلتا اللغتين تمامًا مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android. لمزيد من المعلومات حول Kotlin، يُرجى الاطّلاع على تطوير تطبيقات Android باستخدام Kotlin.

   • اضبط الحد الأدنى لإصدار SDK على إصدار SDK متوافق مع جهاز الاختبار. يجب اختيار إصدار أكبر من الحد الأدنى للإصدار المطلوب من حزمة تطوير البرامج (SDK) الخاصة بـ "خرائط Google لنظام التشغيل Android" الإصدار 19.0.x، وهو المستوى 21 من واجهة برمجة التطبيقات Android ("Lollipop"، الإصدار 5.0 من نظام التشغيل Android) أو إصدار أحدث. يمكنك الاطّلاع على ملاحظات الإصدار للحصول على أحدث المعلومات حول متطلبات إصدار حزمة تطوير البرامج (SDK).

     ملاحظة: إذا لم تكن متأكدًا من إصدار حزمة SDK الذي يجب اختياره، انقر على الرابط ساعدني في الاختيار لعرض معلومات التوزيع الخاصة بحِزم Android SDK المتوافقة. على سبيل المثال، إذا اخترت المستوى 21 من واجهة برمجة التطبيقات لنظام التشغيل Android‏ ("Lollipop"، الإصدار 5.0 من نظام التشغيل Android)، من المفترض أن يعمل تطبيقك على أكثر من% 99 من أجهزة Android.

   • اضبط لغة إعدادات الإصدار على Kotlin DSL أو Groovy DSL. يتم عرض مقتطفات لكلتا لغتَي إعدادات الإصدار في الإجراءات التالية.

4. انقر على إنهاء.

   يبدأ "استوديو Android" في تشغيل Gradle وإنشاء المشروع. وقد تستغرق هذه العملية بعض الوقت.

5. أضِف نشاط "مشاهدات خرائط Google":

   1. انقر بزر الماوس الأيمن على المجلد app في مشروعك.

   2. اختَر جديد > Google > نشاط المشاهدات على "خرائط Google".

      

   3. في مربّع الحوار نشاط Android جديد، ضَع علامة في مربّع الاختيار نشاط المشغّل.

   4. انقر على إنهاء.

      لمزيد من المعلومات، يُرجى الاطّلاع على إضافة رمز من نموذج.

6. عند انتهاء عملية الإنشاء، يفتح "استوديو Android" الملفَين AndroidManifest.xml وMapsActivity. قد يكون لنشاطك اسم مختلف، ولكنّه الاسم الذي أعددته أثناء عملية الإعداد.

   تنبيه: يحتوي الملف AndroidManifest.xml على تعليمات حول كيفية الحصول على مفتاح لواجهة Google Maps API ثم إضافته إلى الملف local.properties. لا تُضِف مفتاح واجهة برمجة التطبيقات إلى الملف local.properties. ويؤدي ذلك إلى تخزين مفتاح واجهة برمجة التطبيقات بطريقة أقل أمانًا. بدلاً من ذلك، اتّبِع التعليمات الواردة في إعداد مشروعك على Google Cloud لإنشاء مشروع على Cloud وإعداد مفتاح API.

إعداد مشروعك على Google Cloud

أكمِل خطوات الإعداد المطلوبة في Cloud Console من خلال النقر على علامات التبويب التالية:

الخطوة 1

وحدة التحكّم

1. في صفحة اختيار المشروع ضمن Google Cloud Console، انقر على إنشاء مشروع لبدء إنشاء مشروع جديد على Cloud.

   الانتقال إلى صفحة اختيار المشروع

2. تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تأكَّد من تفعيل الفوترة لمشروعك.

   تقدّم Google Cloud فترة تجريبية بدون أي رسوم. تنتهي الفترة التجريبية إما بعد 90 يومًا أو بعد أن تتراكم في الحساب رسوم بقيمة 300 دولار أمريكي، أيهما أقرب. يمكنك الإلغاء في أي وقت. لمزيد من المعلومات، يُرجى الاطّلاع على اعتمادات حساب الفوترة والفوترة.

SDK للسحاب

gcloud projects create "PROJECT"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت Cloud SDK والأوامر التالية:

• gcloud projects create

ملاحظة: إذا كنت لا تخطّط للاحتفاظ بالمراجع التي تنشئها في تمرين تعليمي، أنشئ مشروعًا بدلاً من اختيار مشروع حالي. بعد الانتهاء من التمرين، يمكنك حذف المشروع، ما يؤدي إلى إزالة جميع الموارد المرتبطة به.

الخطوة 2

لاستخدام Google Maps Platform، يجب تفعيل واجهات برمجة التطبيقات أو حِزم SDK التي تخطّط لاستخدامها مع مشروعك.

وحدة التحكّم

تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android

SDK للسحاب

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت Cloud SDK والأوامر التالية:

• gcloud services enable
• gcloud services disable

الخطوة 3

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

مفتاح واجهة برمجة التطبيقات هو معرّف فريد يصادق على الطلبات المرتبطة بمشروعك لأغراض الاستخدام والفوترة. يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات واحد على الأقل مرتبط بمشروعك.

لإنشاء مفتاح واجهة برمجة تطبيقات، اتّبِع الخطوات التالية:

وحدة التحكّم

1. انتقِل إلى صفحة منصة خرائط Google > بيانات الاعتماد.

   الانتقال إلى صفحة "بيانات الاعتماد"

2. في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
   يعرض مربّع الحوار تم إنشاء مفتاح واجهة برمجة التطبيقات مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه حديثًا.
3. انقر على إغلاق.
   يظهر مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
   (يُرجى تذكُّر تقييد مفتاح واجهة برمجة التطبيقات قبل استخدامه في مرحلة الإنتاج.)

SDK للسحاب

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت Cloud SDK والأوامر التالية:

• gcloud services api-keys create

إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

يوضّح هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات كي يتمكّن تطبيقك من الرجوع إليه بشكل آمن. ويجب عدم إدخال مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدار، لذا ننصح بتخزينه في الملف secrets.properties، الذي يقع في الدليل الجذر لمشروعك. لمزيد من المعلومات عن ملف secrets.properties، يُرجى الاطّلاع على ملفات Gradle properties.

لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secrets Gradle لأجهزة Android.

ملاحظة: للاطّلاع على أحدث متطلبات النظام وتعليمات التثبيت، يُرجى الرجوع إلى مستندات المكوّن الإضافي Secrets Gradle لأجهزة Android على GitHub.

لتثبيت المكوّن الإضافي Secrets Gradle لأجهزة Android في مشروع "خرائط Google"، اتّبِع الخطوات التالية:

1. في Android Studio، افتح ملف build.gradle.kts أو build.gradle ذي المستوى الأعلى وأضِف الرمز التالي إلى العنصر dependencies ضمن buildscript.

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Groovy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

2. افتح ملف build.gradle.kts أو build.gradle على مستوى الوحدة وأضِف الرمز التالي إلى العنصر plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. في ملف build.gradle.kts أو build.gradle على مستوى الوحدة، تأكَّد من ضبط قيمتَي targetSdk وcompileSdk على 34.
4. مزامنة مشروعك مع Gradle
5. افتح ملف secrets.properties في الدليل ذي المستوى الأعلى، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات. خزِّن المفتاح في هذا الملف لأنّ secrets.properties مستبعد من إمكانية التحقّق من نظام التحكّم في الإصدار.
   ملاحظة: إذا لم يكن ملف secrets.properties متوفّرًا، أنشئه في المجلد نفسه الذي يتضمّن ملف local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. أنشئ ملف local.defaults.properties في الدليل على المستوى الأعلى، أي المجلد نفسه الذي يحتوي على ملف secrets.properties، ثم أضِف الرمز التالي.

   ملاحظة: أدخِل الرمز كما هو معروض. لا تستبدِل DEFAULT_API_KEY بمفتاح واجهة برمجة التطبيقات.

   MAPS_API_KEY=DEFAULT_API_KEY

   الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات في حال تعذّر العثور على الملف secrets.properties، وذلك لضمان عدم تعذّر إنشاء الإصدارات. يمكن أن يحدث ذلك إذا نسخت التطبيق من نظام التحكّم في الإصدارات الذي يحذف secrets.properties ولم تنشئ بعد ملف secrets.properties محليًا لتوفير مفتاح واجهة برمجة التطبيقات.

7. في ملف AndroidManifest.xml، انتقِل إلى com.google.android.geo.API_KEY وعدِّل android:value attribute. إذا لم تكن العلامة <meta-data> متوفّرة، أنشئها كعنصر تابع للعلامة <application>.

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

   ملاحظة: ‫com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على عدة واجهات برمجة تطبيقات مستندة إلى "خرائط Google" على نظام التشغيل Android، بما في ذلك حزمة تطوير البرامج (SDK) الخاصة بـ "خرائط Google" لنظام التشغيل Android. للتوافق مع الإصدارات السابقة، تتيح واجهة برمجة التطبيقات أيضًا الاسم com.google.android.maps.v2.API_KEY. يتيح هذا الاسم القديم إجراء المصادقة على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

8. في Android Studio، افتح ملف build.gradle.kts أو build.gradle على مستوى الوحدة وعدِّل السمة secrets. إذا لم تكن السمة secrets متوفّرة، أضِفها.

   عدِّل خصائص المكوّن الإضافي لضبط propertiesFileName على secrets.properties، وضبط defaultPropertiesFileName على local.defaults.properties، وضبط أي خصائص أخرى.

   Kotlin

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
           

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }
           

الاطّلاع على الرمز

افحص الرمز الذي يوفّره النموذج. على وجه الخصوص، اطّلِع على الملفات التالية في مشروعك على "استوديو Android".

ملف نشاط "خرائط Google"

ملف نشاط الخرائط هو النشاط الرئيسي للتطبيق، ويتضمّن الرمز البرمجي لإدارة الخريطة وعرضها. يكون اسم الملف الذي يحدّد النشاط هو MapsActivity.java تلقائيًا، أو MapsActivity.kt إذا ضبطت Kotlin كلغة لتطبيقك.

العناصر الرئيسية لنشاط "خرائط Google":

• يدير عنصر SupportMapFragment دورة حياة الخريطة وهو العنصر الرئيسي لواجهة مستخدم التطبيق.

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

• تعمل الدالة moveCamera على توسيط الخريطة عند إحداثيات LatLng لمدينة سيدني في أستراليا. عادةً ما تكون الإعدادات الأولى التي يجب ضبطها عند إضافة خريطة هي موقع الخريطة وإعدادات الكاميرا، مثل زاوية العرض واتجاه الخريطة ومستوى التكبير/التصغير. راجِع دليل الكاميرا والعرض للاطّلاع على التفاصيل.

• تضيف الدالة addMarker علامة إلى الإحداثيات الخاصة بمدينة سيدني. راجِع دليل العلامات للاطّلاع على التفاصيل.

ملف Gradle الخاص بالوحدة

يتضمّن ملف الوحدة build.gradle.kts تبعية الخرائط التالية، وهي مطلوبة من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android.

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

ملاحظة: يمكن أن يتغير الإصدار الدقيق استنادًا إلى الإصدار الحالي من حزمة تطوير البرامج (SDK) لخدمة "خرائط Google" لنظام التشغيل Android.

لمزيد من المعلومات حول إدارة تبعية "خرائط Google"، راجِع التحكّم في الإصدار.

ملف تنسيق XML

ملف activity_maps.xml هو ملف تصميم XML الذي يحدّد بنية واجهة مستخدم التطبيق. يقع الملف في الدليل res/layout. يحدّد ملف activity_maps.xml جزءًا يتضمّن العناصر التالية:

• يضبط tools:context النشاط التلقائي للجزء على MapsActivity، ويتم تحديد ذلك في ملف نشاط الخرائط.
• يضبط android:name اسم فئة الجزء على SupportMapFragment، وهو نوع الجزء المستخدَم في ملف نشاط الخرائط.

يحتوي ملف تنسيق XML على الرمز التالي:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

نشر التطبيق وتشغيله

عند تشغيل التطبيق بنجاح، ستظهر خريطة في وسطها مدينة سيدني في أستراليا مع علامة على المدينة كما هو موضّح في لقطة الشاشة التالية.

لنشر التطبيق وتشغيله، اتّبِع الخطوات التالية:

1. في Android Studio، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل) لتشغيل تطبيقك.
2. عندما يُطلب منك اختيار جهاز، حدِّد أحد الخيارات التالية:
   • اختَر جهاز Android المتصل بجهاز الكمبيوتر.
   • بدلاً من ذلك، انقر على زر الاختيار تشغيل المحاكي واختَر الجهاز الافتراضي الذي أعددته.
3. انقر على موافق. سيبدأ Android Studio في استخدام Gradle لإنشاء تطبيقك، ثم يعرض النتائج على جهازك أو المحاكي. قد يستغرق إطلاق التطبيق عدة دقائق.

الخطوات التالية

• إعداد خريطة: يوضّح هذا المستند كيفية إعداد الإعدادات الأولية وإعدادات وقت التشغيل للخريطة، مثل موضع الكاميرا ونوع الخريطة ومكوّنات واجهة المستخدم والإيماءات.

• إضافة خريطة إلى تطبيق Android (Kotlin): يرشدك هذا الدرس العملي إلى تطبيق يعرض بعض الميزات الإضافية لحزمة تطوير البرامج (SDK) الخاصة بـ "خرائط Google" لنظام التشغيل Android.

• استخدام مكتبة Maps Android KTX: تتيح لك مكتبة إضافات Kotlin (KTX) الاستفادة من العديد من ميزات لغة Kotlin أثناء استخدام حزمة تطوير البرامج (SDK) بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android.