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

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

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

حول بيئة التطوير

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

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

إعداد جهاز Android

لتشغيل تطبيق يستخدم "حزمة تطوير البرامج (SDK) للخرائط" لنظام التشغيل 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 لخرائط Android. لمزيد من المعلومات حول Kotlin، يمكنك الاطّلاع على تطوير تطبيقات Android باستخدام Kotlin.

   • اضبط الحدّ الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة SDK متوافق مع جهاز الاختبار. يجب اختيار إصدار أعلى من الحد الأدنى للإصدار المطلوب في الإصدار 18.2.x من حزمة "SDK للخرائط" لنظام التشغيل Android، وهو المستوى 19 من واجهة برمجة تطبيقات Android ("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 وإعداد مفتاح واجهة برمجة تطبيقات.

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

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

الخطوة 1

وحدة التحكّم

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

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

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

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

Cloud SDK

gcloud projects create "PROJECT"

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

• gcloud projects create

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

الخطوة 2

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

وحدة التحكّم

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

Cloud 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. انقر على إغلاق.
   يتم عرض مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
   (يُرجى الحرص على تقييد مفتاح واجهة برمجة التطبيقات قبل استخدامه في قناة الإصدار العلني).

Cloud SDK

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

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

• gcloud alpha services api-keys create

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

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

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

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

لتثبيت مكوّن Secrets 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.

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

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

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

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

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

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

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

ملف Gradle للوحدة

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

dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.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"، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل) لتشغيل التطبيق.
2. عندما يُطلب منك اختيار جهاز، حدِّد أحد الخيارات التالية:
   • اختَر جهاز Android المتصل بجهاز الكمبيوتر.
   • ويمكنك بدلاً من ذلك النقر على زر الاختيار إطلاق المحاكي واختيار الجهاز الافتراضي الذي أعددته.
3. انقر على موافق. سيبدأ "استوديو Android" Gradle في إنشاء تطبيقك، ثم يعرض النتائج على جهازك أو المحاكي. قد يستغرق إطلاق التطبيق عدة دقائق.

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

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

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

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