الإعداد

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

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

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

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

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

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

الخطوة 1

وحدة التحكّم

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

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

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

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

SDK للسحاب

gcloud projects create "PROJECT"

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

• gcloud projects create

ملاحظة: إذا كنت لا تخطط للاحتفاظ بالموارد التي تنشئها في تمرين تعليمي، أنشئ مشروعًا بدلاً من اختيار مشروع حالي. بعد الانتهاء من التمرين، يمكنك حذف المشروع، ما يؤدي إلى إزالة جميع الموارد المرتبطة به.

الخطوة 2

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

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

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

وحدة التحكّم

1. يمكنك الاطّلاع على واجهات برمجة التطبيقات وحزم تطوير البرامج (SDK) في "منصة خرائط Google" التي يمكنك تفعيلها من خلال الانتقال إلى صفحة مكتبة Maps API في وحدة تحكّم Cloud:

   انتقِل إلى صفحة مكتبة Maps API

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

SDK للسحاب

يؤدي الأمر التالي إلى تفعيل جميع واجهات برمجة التطبيقات Maps API وRoutes API وPlaces API:

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"

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

• gcloud services enable
• gcloud services disable

استخدِم هذا الأمر لتفعيل واجهات برمجة التطبيقات الخاصة بالبيئة:

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

ملاحظة: يؤدي تفعيل Places API أيضًا إلى تفعيل مكتبة الأماكن وMaps JavaScript API وPlaces SDK for Android و Places SDK for iOS.

الخطوة 3

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

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

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

وحدة التحكّم

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

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

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

SDK للسحاب

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

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

• gcloud services api-keys create

لتفعيل حزمة تطوير البرامج (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
   

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

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