الإعداد

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

إعداد مشروع على Google Cloud ومفتاح واجهة برمجة تطبيقات

قبل البدء في إنشاء تطبيقات باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android، يجب إعداد مشروع على Google Cloud ومفتاح واجهة برمجة تطبيقات لاستخدامهما مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android من خلال إكمال الخطوات التالية:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

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

لتفعيل حزمة تطوير البرامج، يُرجى الاطّلاع على صفحة حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android في Google Cloud Console. لمزيد من المعلومات عن إكمال هذه الخطوات، يُرجى الاطّلاع على مقالة البدء في استخدام "منصة خرائط Google".

إعداد مشروع في "استوديو Android"

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

الجزء 1: إعداد مشروعك وإعداد Gradle

1. أنشِئ مشروعًا جديدًا في "استوديو Android" باستخدام نموذج نشاط "عرض فارغ".

2. إذا كنت تستخدم Git للتحكّم في المصدر، عدِّل ملف .gitignore الخاص بالمشروع لمنع إرسال ملف الأسرار إلى نظام التحكّم في الإصدارات:

   • في الدليل الجذري لمشروعك، افتح ملف .gitignore.
   • أضِف السطر التالي:

   secrets.properties
   

3. عدِّل ملف build.gradle.kts على مستوى المشروع:

   • في الدليل الجذري لمشروعك، افتح ملف build.gradle.kts.
   • في حزمة plugins، أضِف Secrets Gradle plugin:

   plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
   }
   

4. عدِّل ملف gradle/libs.versions.toml:

   • افتح ملف gradle/libs.versions.toml، الذي يكون عادةً في دليل gradle ضمن الدليل الجذري للمشروع.
   • في قسم [versions]، أضِف أرقام إصدارات حزمة تطوير البرامج وSecrets Gradle plugin:

   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "0.2.0"
   # See https://github.com/google/secrets-gradle-plugin/releases for available releases
   secretsGradlePlugin = "2.0.1"
   

   • في قسم [library]، أضِف مكتبة حزمة تطوير البرامج:

   play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
   

   • في قسم [plugins]، أضِف Secrets Gradle plugin:

   secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }
   

5. عدِّل ملف app/build.gradle.kts على مستوى الوحدة:

   • افتح ملف build.gradle.kts على مستوى الوحدة، الذي يكون عادةً ضمن دليل app.
   • في أعلى الملف، أضِف Secrets Gradle plugin إلى حزمة plugins:

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.secrets.gradle.plugin) // Add this line
   }
   

   • في حزمة dependencies، أضِف حزمة تطوير البرامج:

   dependencies {
       // ... other dependencies
       implementation(libs.play.services.maps3d) // Add this line
   }
   

   • في نهاية الملف، خارج حزمتَي android وdependencies، أضِف إعدادات الأسرار:

   secrets {
       // Optionally specify a different filename 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"
   }
   

الجزء 2: إضافة مفتاح واجهة برمجة التطبيقات إلى مشروعك

1. أنشِئ ملف secrets.properties:

   • في الدليل الجذري لوحدة التطبيق (عادةً دليل app)، أنشِئ ملفًا جديدًا باسم secrets.properties.
   • أضِف مفتاح واجهة برمجة التطبيقات إلى الملف:

   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   

2. أنشِئ ملف local.defaults.properties : - في الدليل الجذري لوحدة التطبيق، أنشِئ ملفًا جديدًا باسم secrets.properties. - أضِف مفتاح واجهة برمجة تطبيقات تلقائيًا أو عنصرًا نائبًا إلى الملف. يمكن إرسال هذا الملف إلى نظام التحكّم في الإصدارات:

   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   

الجزء 3: تعديل ملف AndroidManifest.xml

1. افتح ملف app/src/main/AndroidManifest.xml.

2. داخل العلامة <application>، قبل العلامة <activity>، أضِف العنصر التالي <meta-data> للإعلان عن مفتاح واجهة برمجة التطبيقات:

   <application
       ...>
   
       <meta-data
           android:name="com.google.android.geo.maps3d.API_KEY"
           android:value="${MAPS3D_API_KEY}" />
   
       <activity
           ...>
       </activity>
   </application>
   

   أثناء عملية التصميم، سيستبدل Secrets Gradle Plugin العنصر النائب ${MAPS3D_API_KEY} بالمفتاح من ملف secrets.properties.

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

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