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

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

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

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

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

إعداد جهاز Android

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

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

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

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

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

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

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

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

   • اضبط الحد الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة تطوير برامج (SDK) متوافق مع جهاز الاختبار. يجب اختيار إصدار أعلى من الحد الأدنى للإصدار المطلوب من حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android، الإصدار 20.0.x، وهو المستوى 23 من واجهة برمجة التطبيقات Android ("Marshmallow"؛ الإصدار 6.0 من نظام التشغيل Android) أو إصدار أحدث. يُرجى الاطّلاع على ملاحظات الإصدار للحصول على أحدث المعلومات حول متطلبات إصدار حزمة تطوير البرامج (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 services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

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

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

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

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

   Groovy

   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.

   Groovy

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

   Kotlin

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

3. إذا كنت تستخدم "استوديو Android"، يمكنك مزامنة مشروعك مع Gradle.
4. افتح ملف local.properties في دليل مستوى مشروعك، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الخاص بك.

   MAPS_API_KEY=YOUR_API_KEY

5. في ملف AndroidManifest.xml، انتقِل إلى com.google.android.geo.API_KEY وعدِّل السمة android:value على النحو التالي:

   <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. يتيح هذا الاسم القديم المصادقة على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

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

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

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

ملف النشاط على "خرائط 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(libs.play.services.maps)
}

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

ملف تنسيق XML

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

• يضبط tools:context النشاط التلقائي للجزء على MapsActivity، والذي يتم تحديده في ملف النشاط على "خرائط Google".
• يضبط 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.

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