الإعداد

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

إعداد مشروع على Google Cloud ومفتاح API

قبل أن تتمكّن من بدء الإنشاء باستخدام حزمة تطوير البرامج 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 plugin:

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

   • في قسم المكتبة، أضِف مكتبة حزمة SDK:

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

   • في قسم المكوّن الإضافي، أضِف المكوّن الإضافي Secrets Gradle:

   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، أضِف حزمة تطوير البرامج (SDK) باتّباع الخطوات التالية:

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