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

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

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

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

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

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

إعداد جهاز Android

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

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

  

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

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

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

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

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

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

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

     ملاحظة: إذا لم تكن متأكدًا من إصدار حزمة SDK الذي يجب اختياره، يُرجى النقر على الرابط مساعدتي في الاختيار لعرض معلومات التوزيع لحِزم تطوير البرامج (SDK) المتوافقة مع Android. على سبيل المثال، إذا اخترت المستوى 19 من واجهة برمجة تطبيقات Android ("KitKat" أو Android 4.4)، يجب أن يعمل تطبيقك على أكثر من 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 ثم إضافته إلى ملف local.properties. لا تضِف مفتاح واجهة برمجة التطبيقات إلى ملف local.properties. يؤدي هذا الإجراء إلى تخزين مفتاح واجهة برمجة التطبيقات بشكل أقل أمانًا. بدلاً من ذلك، يُرجى اتّباع التعليمات الواردة في مقالة إعداد مشروعك على Google Cloud لإنشاء مشروع على السحابة الإلكترونية وضبط مفتاح واجهة برمجة تطبيقات.

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

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

الخطوة 1

وحدة التحكّم

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

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

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

   تقدّم خدمة Google Cloud فترة تجريبية مجانية تبلغ 0.00 دولار أمريكي. تنتهي الفترة التجريبية إما في نهاية 90 يومًا أو بعد تراكم مبلغ 300 دولار أمريكي (أو ما يعادله بالعملة المحلية) على الحساب، أيهما أقرب. ويمكنك إلغاء الاشتراك في أي وقت. تتميز "منصة خرائط Google" برصيد شهري متكرر بقيمة 200 دولار أمريكي. لمزيد من المعلومات، راجِع أرصدة حساب الفوترة والفوترة.

Cloud SDK

gcloud projects create "PROJECT"

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

• gcloud projects create

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

الخطوة 2

ولاستخدام "منصة خرائط Google"، يجب تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي تخطط لاستخدامها مع مشروعك.

وحدة التحكّم

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

Cloud SDK

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

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

• gcloud services enable
• gcloud services disable

الخطوة 3

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

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

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

وحدة التحكّم

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

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

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

Cloud SDK

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

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

• gcloud alpha services api-keys create

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

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

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

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

لتثبيت المكوّن الإضافي Secret Gradle الإضافي لنظام التشغيل Android في مشروع "خرائط Google"، اتَّبِع الخطوات التالية:

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

   رائع

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

   Kotlin

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

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

   رائع

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

   Kotlin

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

3. في ملف 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. احفظ الملف.

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

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

   MAPS_API_KEY=DEFAULT_API_KEY

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

8. احفظ الملف.
9. في ملف 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}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

انظر إلى الرمز

افحص الرمز الذي يوفّره النموذج. وعلى وجه التحديد، انظر إلى الملفات التالية في مشروع استوديو Android.

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

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

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

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

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

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

• تضيف الدالة addMarker علامة إلى إحداثيات سيدني. يمكنك الاطّلاع على دليل العلامات للحصول على التفاصيل.

ملف Gradle للوحدة

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

dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}

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

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

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

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

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