الإعداد

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

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

قبل أن تتمكّن من بدء الإنشاء باستخدام حزمة تطوير البرامج Maps 3D SDK لنظام التشغيل Android، عليك إعداد مشروع على Google Cloud ومفتاح لواجهة برمجة التطبيقات لاستخدامهما مع حزمة تطوير البرامج Maps 3D SDK لنظام التشغيل 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"

لتفعيل حزمة SDK، اطّلِع على صفحة حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط 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:

   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 ضمن الدليل الجذر للمشروع. - في قسم الإصدارات، أضِف إصدارات حزمة تطوير البرامج (SDK) والمكوّن الإضافي Secrets Gradle:

   maps3dSdk = "0.0.1" # Update this value to match the SDK version to include
   secretsGradlePlugin = "2.0.1"
   

   -   In the library section, add the SDK library:
   

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

   -   In the plugin section, add the 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
   }
   

   -   In the `dependencies` block, add the SDK:
   

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

   -   At the end of the file, outside of the `android` and `dependencies`
       blocks, add the secrets configuration:
   

   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
   ``` Note: Make sure you
       replace `YOUR_API_KEY_HERE` with the API key that you configured for use
   with the Maps 3D SDK for Android.
   

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، يمكنك إضافة خريطة ثلاثية الأبعاد إلى تطبيقك.