توضّح هذه الصفحة الخطوات التي يجب اتّخاذها لإعداد حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android. تتضمّن عملية الإعداد ضبط مشروع وواجهة برمجة تطبيقات على Google Cloud لاستخدامهما مع حزمة تطوير البرامج (SDK)، ثم إعداد مشروع على Android Studio. أكمِل هذه الخطوات قبل إضافة أول خريطة ثلاثية الأبعاد إلى تطبيقك.
إعداد مشروع على Google Cloud ومفتاح واجهة برمجة التطبيقات
قبل أن تتمكّن من البدء في إنشاء تطبيقات باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android، عليك إعداد مشروع على Google Cloud ومفتاح API لاستخدامهما مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android من خلال إكمال الخطوات التالية:
الخطوة 1
وحدة التحكّم
-
في صفحة اختيار المشروع ضمن Google Cloud Console، انقر على إنشاء مشروع لبدء إنشاء مشروع جديد على Cloud.
-
تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تأكَّد من تفعيل الفوترة لمشروعك.
تقدّم Google Cloud فترة تجريبية بدون أي رسوم. تنتهي الفترة التجريبية إما بعد 90 يومًا أو بعد أن تتراكم في الحساب رسوم بقيمة 300 دولار أمريكي، أيهما أقرب. يمكنك الإلغاء في أي وقت. لمزيد من المعلومات، يُرجى الاطّلاع على اعتمادات حساب الفوترة والفوترة.
SDK للسحاب
gcloud projects create "PROJECT"
يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت Cloud SDK والأوامر التالية:
الخطوة 2
لاستخدام Google Maps Platform، يجب تفعيل واجهات برمجة التطبيقات أو حِزم SDK التي تخطّط لاستخدامها مع مشروعك.
يُرجى العِلم أنّ بعض عمليات الدمج تتطلّب تفعيل واجهات برمجة تطبيقات أو حِزم SDK متعددة. إذا لم تكن متأكدًا من واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي يجب تفعيلها، جرِّب استخدام أداة اختيار واجهة برمجة التطبيقات أو راجِع المستندات الخاصة بواجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK) التي تريد استخدامها.
لتفعيل واجهة برمجة تطبيقات أو أكثر أو حزمة تطوير برامج أو أكثر، اتّبِع الخطوات التالية:
وحدة التحكّم
-
يمكنك الاطّلاع على واجهات برمجة التطبيقات وحِزم تطوير البرامج (SDK) في "منصة خرائط Google" التي يمكنك تفعيلها من خلال الانتقال إلى صفحة "مكتبة واجهة برمجة تطبيقات الخرائط" في Cloud Console:
انتقِل إلى صفحة مكتبة Maps API
- انقر على واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK) التي تريد تفعيلها.
- إذا كان الزر يعرض تفعيل، انقر عليه لتفعيل واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK).
- إذا كان الزر يعرض إدارة، يعني ذلك أنّ واجهة برمجة التطبيقات أو حزمة SDK مفعّلة، وليس عليك اتّخاذ أي إجراء آخر.
- سيؤدي النقر على أي من الزرّين إلى عرض لوحة بيانات واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK). (انقر على الزر إيقاف لإزالة واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK) من هذا المشروع).
SDK للسحاب
يؤدي الأمر التالي إلى تفعيل جميع واجهات برمجة التطبيقات Maps وRoutes وPlaces:
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 \ --project "PROJECT" \ "airquality.googleapis.com" \ "solar.googleapis.com" \ "pollen.googleapis.com" \ "weather.googleapis.com"
الخطوة 3
تتضمّن هذه الخطوة عملية إنشاء مفتاح واجهة برمجة التطبيقات فقط. إذا كنت تستخدم مفتاح واجهة برمجة التطبيقات في مرحلة الإنتاج، ننصحك بشدة بتقييد مفتاح واجهة برمجة التطبيقات. يمكنك العثور على مزيد من المعلومات في صفحة استخدام مفاتيح واجهة برمجة التطبيقات الخاصة بالمنتج.
مفتاح واجهة برمجة التطبيقات هو معرّف فريد يصادق على الطلبات المرتبطة بمشروعك لأغراض الاستخدام والفوترة. يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات واحد على الأقل مرتبط بمشروعك.
لإنشاء مفتاح واجهة برمجة تطبيقات، اتّبِع الخطوات التالية:
وحدة التحكّم
-
انتقِل إلى صفحة منصة خرائط Google > بيانات الاعتماد.
-
في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
يعرض مربّع الحوار تم إنشاء مفتاح واجهة برمجة التطبيقات مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه حديثًا. -
انقر على إغلاق.
يظهر مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
(يُرجى تذكُّر تقييد مفتاح واجهة برمجة التطبيقات قبل استخدامه في مرحلة الإنتاج.)
SDK للسحاب
gcloud services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت Cloud SDK والأوامر التالية:
لتفعيل حزمة SDK، يُرجى الاطّلاع على صفحة حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android في Google Cloud Console. لمزيد من المعلومات حول إكمال هذه الخطوات، يُرجى الاطّلاع على البدء في استخدام "منصة خرائط Google".
إعداد مشروع في "استوديو Android"
يوضّح هذا القسم كيفية إنشاء مشروع في "استوديو Android" وإعداده لاستخدامه مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android.
الجزء 1: إعداد مشروعك وإعدادات Gradle
أنشئ مشروعًا جديدًا في "استوديو Android" باستخدام نموذج نشاط عرض فارغ.
إذا كنت تستخدم Git للتحكّم في المصدر، عدِّل ملف المشروع
.gitignore
لمنع إرسال ملف الأسرار إلى نظام التحكّم في الإصدارات:- في الدليل الجذر لمشروعك، افتح الملف
.gitignore
. - أضِف السطر التالي:
secrets.properties
- في الدليل الجذر لمشروعك، افتح الملف
عدِّل ملف
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 }
- في الدليل الجذر لمشروعك، افتح الملف
عدِّل ملف
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" }
عدِّل ملف
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: إضافة مفتاح واجهة برمجة التطبيقات إلى مشروعك
إنشاء ملف
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.
- في الدليل الجذر لوحدة التطبيق (عادةً الدليل
أنشئ ملف
local.defaults.properties
: - في الدليل الجذري لوحدة التطبيق، أنشئ ملفًا جديدًا باسمsecrets.properties
. - أضِف مفتاحًا تلقائيًا أو عنصرًا نائبًا لمفتاح واجهة برمجة التطبيقات إلى الملف. يمكن إدراج هذا الملف في نظام التحكّم بالإصدارات:MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
الجزء 3: تعديل ملف AndroidManifest.xml
افتح ملف
app/src/main/AndroidManifest.xml
.داخل العلامة
<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، يمكنك إضافة خريطة ثلاثية الأبعاد إلى تطبيقك.