الإعداد

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

المتطلبات الأساسية

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

• الحد الأدنى لمستوى واجهة برمجة التطبيقات: المستوى 24 من واجهة برمجة تطبيقات Android (الإصدار 7.0 من Android) أو إصدار أحدث يجب أن يستهدف تطبيقك الإصدار 24 من minSdk أو إصدارًا أحدث.
• خدمات Google Play: تعتمد حزمة تطوير البرامج (SDK) لخدمة "خرائط Google" الثلاثية الأبعاد لنظام التشغيل Android على خدمات Google Play. يجب أن تكون "خدمات Google Play" مثبّتة على أجهزة الاختبار (والمحاكيات التي تستخدم Google APIs).

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

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

الخطوة 1: إعداد مشروعك

gcloud projects create "PROJECT"

الخطوة 2: تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK)

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

يُرجى العِلم أنّ بعض عمليات الدمج تتطلّب تفعيل واجهات برمجة تطبيقات أو حِزم تطوير برامج متعدّدة. إذا لم تكن متأكدًا من واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي يجب تفعيلها، يمكنك استخدام مستكشف الإمكانات أو الاطّلاع على مستندات واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK) التي تريد استخدامها.

لتفعيل واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) واحدة أو أكثر، اتّبِع الخطوات التالية:

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"

الخطوة 3: الحصول على مفتاح واجهة برمجة التطبيقات

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

مفتاح واجهة برمجة التطبيقات هو معرّف فريد يصادق على الطلبات المرتبطة بمشروعك لأغراض الاستخدام والفوترة. يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات واحد على الأقل مرتبط بمشروعك. لإنشاء مفتاح جديد أو إضافة واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) إلى مفتاح حالي، اتّبِع التعليمات التالية.

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

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

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

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

1. أنشئ مشروعًا جديدًا في "استوديو Android" باستخدام نموذج نشاط طرق العرض الفارغة. في إعدادات المشروع، اضبط الحدّ الأدنى لحزمة تطوير البرامج (SDK) على المستوى 24 من واجهة برمجة التطبيقات أو مستوى أعلى.

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

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

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

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

   • في قسم [plugins]، أضِف المكوّن الإضافي 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 إلى حزمة plugins:

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

   • في مجموعة الرموز البرمجية dependencies، أضِف اعتمادية "خدمات Google Play" لحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android:

   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: - في الدليل الجذري لوحدة التطبيق، أنشئ ملفًا جديدًا باسم local.defaults.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 العنصر النائب ${MAPS3D_API_KEY} بالمفتاح من ملف secrets.properties.

إعداد العرض الآلي (اختياري)

إذا كنت تفضّل إعداد عرض الخريطة آليًا بدلاً من استخدام تنسيقات XML، استخدِم Map3DInitConfig.

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

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

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