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

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

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

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

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

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

إعداد جهاز Android

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

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

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

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

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

الخطوة 1

وحدة التحكّم

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

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

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

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

SDK للسحاب

gcloud projects create "PROJECT"

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

• gcloud projects create

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

الخطوة 2

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

وحدة التحكّم

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

SDK للسحاب

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

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

• gcloud services enable
• gcloud services disable

الخطوة 3

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

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

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

وحدة التحكّم

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

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

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

SDK للسحاب

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

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

• gcloud alpha services api-keys create

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

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

لتبسيط هذه المهمة، نوصيك باستخدام المكوّن الإضافي السري لنظام 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")
       }
   }

   رائع

   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")
   }

   رائع

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

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}" />

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

10. في "استوديو Android"، افتح 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"
    
        // 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.*"
    }
            

    رائع

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

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.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 Studio في إنشاء Gradle لإنشاء تطبيقك، ثم ستعرض النتائج على جهازك أو المحاكي. قد يستغرق تشغيل التطبيق عدة دقائق.

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

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

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

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