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

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

ملاحظة: يستخدم دليل البدء السريع هذا نموذج نشاط طرق عرض "خرائط Google"، الذي ينشئ تنسيق XML باستخدام SupportMapFragment. إذا كنت بصدد إنشاء واجهة المستخدم باستخدام Jetpack Compose، يمكنك الاطّلاع على مكتبة Compose لحزمة تطوير برامج "خرائط Google" بدلاً من ذلك.

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

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

ننصحك باستخدام أحدث إصدار ثابت من استوديو Android والمكوّن الإضافي لنظام Gradle المتوافق مع Android.

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

إعداد جهاز Android

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

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

إنشاء مشروع "خرائط Google" في "استوديو 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).

     ملاحظة: إذا لم تكن متأكدًا من إصدار حزمة SDK الذي يجب اختياره، انقر على الرابط مساعدة في الاختيار لعرض معلومات التوزيع الخاصة بحِزم تطوير البرامج (SDK) المتوافقة مع Android. على سبيل المثال، إذا اخترت مستوى واجهة برمجة التطبيقات 23 من نظام التشغيل Android (الإصدار Marshmallow؛ الإصدار 6.0 من نظام التشغيل Android)، من المفترض أن يعمل تطبيقك على أكثر من% 99 من أجهزة Android.

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

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

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

5. أضِف نشاط مشاهدات "خرائط Google":

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

   2. اختَر جديد > Google > نشاط مشاهدات "خرائط Google".

      

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

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

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

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

   تنبيه: يحتوي الملف AndroidManifest.xml على تعليمات حول كيفية الحصول على مفتاح Google Maps API ثم إضافته إلى الملف local.properties. لا تُضِف مفتاح واجهة برمجة التطبيقات إلى الملف local.properties. بدلاً من ذلك، اتّبِع التعليمات الواردة في إعداد مشروعك على Google Cloud وإضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك لتخزين مفتاح واجهة برمجة التطبيقات في ملف secrets.properties منفصل باستخدام المكوّن الإضافي Secrets Gradle Plugin لنظام التشغيل Android.

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

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

الخطوة 1

وحدة التحكّم

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

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

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

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

SDK للسحاب

gcloud projects create "PROJECT"

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

• gcloud projects create

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

الخطوة 2

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

وحدة التحكّم

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

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

SDK للسحاب

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

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

• gcloud services api-keys create

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

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

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

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

1. في استوديو Android، افتح ملف build.gradle.kts أو build.gradle ذي المستوى الأعلى وأضِف الرمز التالي إلى مجموعة plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }

   Groovy

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

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

   Kotlin

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

   Groovy

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

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

   MAPS_API_KEY=YOUR_API_KEY

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

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

   MAPS_API_KEY=DEFAULT_API_KEY

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

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

7. في استوديو 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 root directory (the same folder as the root 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"
   }

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
   }

ملاحظة: إذا أبلغت أداة Logcat عن E/Google Maps Android API: Authorization failure، يُرجى التأكّد من تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android في مشروع على السحابة الإلكترونية على Google Cloud ومن صلاحية مفتاح واجهة برمجة التطبيقات في ملف AndroidManifest.xml المدمج.

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

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

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

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

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

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

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

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

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

Kotlin

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney")
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

جافا

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

ملف Gradle الخاص بالوحدة

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

Kotlin

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

Groovy

dependencies {

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

إذا كان مشروعك يستخدم قائمة إصدارات Gradle (gradle/libs.versions.toml)، حدِّد التبعية play-services-maps في libs.versions.toml:

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

ملاحظة: يمكن أن يتغير الإصدار الدقيق استنادًا إلى الإصدار الحالي من حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android.

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

ملف تنسيق XML

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

• يضبط tools:context النشاط التلقائي للجزء على MapsActivity، ويتم تحديد ذلك في ملف نشاط الخرائط.
• يضبط android:name اسم فئة الجزء على SupportMapFragment، وهو نوع الجزء المستخدَم في ملف النشاط على "خرائط Google".

يحتوي ملف تخطيط 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.