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

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

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

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

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

إعداد جهاز Android

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

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

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

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

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

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

    1. انقر بزر الماوس الأيمن على المجلد "app" في مشروعك.
    2. حدد جديد > Google > نشاط طرق العرض في خرائط Google.

      أضِف نشاطًا على "خرائط Google".

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

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

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

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

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

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

الخطوة 1

وحدة التحكّم

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

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

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

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

SDK للسحاب

gcloud projects create "PROJECT"

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

الخطوة 2

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

وحدة التحكّم

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

SDK للسحاب

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

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

الخطوة 3

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

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

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

وحدة التحكّم

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

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

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

SDK للسحاب

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

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

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

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

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

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

  1. في "استوديو Android"، افتح ملف 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 من التحقق من الوصول إلى نظام التحكم في الإصدار.
    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.kts or build.gradle 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.

    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.

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

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

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

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

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

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

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

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

يتضمن ملف build.gradle.kts للوحدة تبعية الخرائط التالية، وهي مطلوبة من خلال حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط 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، وهو نوع المقتطف المستخدَم فيملف نشاط "خرائط 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 Studio، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل) لتشغيل تطبيقك.
  2. عندما يُطلب منك اختيار جهاز، حدِّد أحد الخيارَين التاليَين:
    • اختَر جهاز Android المتصل بجهاز الكمبيوتر.
    • ويمكنك بدلاً من ذلك النقر على زر الاختيار إطلاق المحاكي واختيار الجهاز الافتراضي الذي أعددته.
  3. انقر على موافق. سيبدأ Android Studio Gradle لإنشاء تطبيقك، ثم سيعرض النتائج على جهازك أو المحاكي. قد يستغرق إطلاق التطبيق عدة دقائق.

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

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

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

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