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

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

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

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

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

إعداد جهاز Android

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

• لاستخدام جهاز Android، يُرجى اتّباع التعليمات الواردة في تشغيل التطبيقات على جهاز
• لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي من خلال أداة إدارة الأجهزة الافتراضية التي تعمل بنظام التشغيل Android (AVD) المتوفّرة ضمن "استوديو Android"

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

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

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

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

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

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

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

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

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

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

5. أضف نشاط بانوراميات في خرائط Google:

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

   2. حدد جديد > Google > نشاط بانوراميات في خرائط Google.

      

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

   4. اختَر إنهاء.

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

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

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

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

gcloud projects create "PROJECT"

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

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

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

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

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

لتثبيت مكوّن 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 من التحقق من عنصر تحكّم الإصدار .

   MAPS_API_KEY=YOUR_API_KEY

6. احفظ الملف.

7. أنشئ الملف local.defaults.properties في دليل المستوى الأعلى، بالطريقة نفسها كملف secrets.properties، ثم أضف الرمز التالي.

   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:19.0.0'
}

لمعرفة المزيد من المعلومات عن إدارة اعتمادية "خرائط 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 Studio بإنشاء Gradle لإنشاء تطبيقك، ثم ستعرض النتائج على جهازك أو المحاكي. قد يستغرق الأمر عدة دقائق قبل أن يتم تثبيت التطبيق عمليات الإطلاق.

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

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

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

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