توضّح هذه الصفحة طريقة إعداد مشروع على "استوديو Android" لاستخدام حزمة تطوير البرامج (SDK) لـ "خرائط Google" لنظام التشغيل Android بدون استخدام نموذج "خرائط Google" المفصّل في Quickstart.
يتم تلقائيًا ضبط نموذج "خرائط Google" لإضافة خريطة أساسية إلى مشروع جديد على "استوديو Android". مع ذلك، يمكنك أيضًا إضافة خريطة إلى مشروع Android يستخدم نموذجًا مختلفًا من "استوديو Android". ولإجراء ذلك، عليك ضبط مشروعك يدويًا ثم إضافة الخريطة.
الخطوة 1: إعداد "استوديو Android"
يصف هذا المستند بيئة تطوير باستخدام Android Studio Hedgehog والإصدار 8.2 من المكوّن الإضافي Android Gradle.
الخطوة 2. إعداد حزمة تطوير البرامج (SDK)
تتوفّر مكتبة "حزمة تطوير البرامج (SDK) لـ "خرائط Google" لأجهزة Android من خلال مستودع Maven من Google. لإضافة حزمة SDK إلى تطبيقك، يُرجى اتّباع الخطوات التالية:
- في ملف
settings.gradle
ذي المستوى الأعلى، أدرِج بوابة مكوّنات Gradle الإضافية، ومستودع Google Maven، ومستودع Maven المركزي ضمن مجموعةpluginManagement
. يجب أن تظهر مجموعة أدواتpluginManagement
قبل أي عبارات أخرى في النص البرمجي.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- في ملف
settings.gradle
ذي المستوى الأعلى، أدرِج مستودع Maven من Google ومستودع Maven المركزي ضمن مجموعةdependencyResolutionManagement
:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- في ملف
build.gradle
على مستوى الوحدة، أضِف اعتمادية خدمات Google Play لحزمة تطوير البرامج (SDK) الخاصة بـ "خرائط Google" لنظام التشغيل Android.رائع
dependencies { // Maps SDK for Android implementation 'com.google.android.gms:play-services-maps:19.0.0' }
Kotlin
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:18.2.0") }
- في ملف
build.gradle
على مستوى الوحدة، اضبطcompileSdk
وminSdk
على القيمتين التاليتين:رائع
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
- في القسم
buildFeatures
من ملفbuild.gradle
على مستوى الوحدة، أضِف الفئةBuildConfig
التي يمكنك استخدامها للوصول إلى قيم البيانات الوصفية المحدّدة لاحقًا في هذا الإجراء:رائع
android { // ... buildFeatures { buildConfig true // ... } }
Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع
يوضّح هذا القسم طريقة تخزين مفتاح واجهة برمجة التطبيقات كي يتمكّن تطبيقك من الرجوع إليه بشكل آمن. ويجب عدم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذا ننصحك بتخزينه في ملف secrets.properties
ضمن الدليل الجذري لمشروعك. لمزيد من المعلومات حول ملف secrets.properties
، راجِع ملفات خصائص Gradle.
لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secret Gradle لأجهزة Android.
لتثبيت مكوّن Secrets Gradle الإضافي لنظام التشغيل Android في مشروعك على "خرائط Google"، اتّبِع الخطوات التالية:
-
في "استوديو Android"، افتح ملف
build.gradle
أوbuild.gradle.kts
ذي المستوى الأعلى وأضِف الرمز التالي إلى العنصرdependencies
ضمنbuildscript
.رائع
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
-
افتح ملف
build.gradle
على مستوى الوحدة وأضِف الرمز التالي إلى العنصرplugins
.رائع
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
Kotlin
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- في ملف
build.gradle
على مستوى الوحدة، تأكَّد من ضبطtargetSdk
وcompileSdk
على 34. - احفظ الملف وزامن مشروعك مع Gradle.
-
افتح ملف
secrets.properties
في دليل المستوى الأعلى، ثم أضِف الرمز التالي. استبدِلYOUR_API_KEY
بمفتاح واجهة برمجة التطبيقات الخاص بك. عليك تخزين مفتاحك في هذا الملف لأنّه تم استبعادsecrets.properties
من التحقق من الوصول إلى نظام التحكم في الإصدار.MAPS_API_KEY=YOUR_API_KEY
- احفظ الملف.
-
أنشِئ ملف
local.defaults.properties
في دليل المستوى الأعلى والمجلد نفسه الذي يتضمّن ملفsecrets.properties
، ثم أضِف الرمز التالي.MAPS_API_KEY=DEFAULT_API_KEY
والغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات في حال عدم العثور على ملف
secrets.properties
كي لا يتعذّر تنفيذ عمليات الإنشاء. وقد يحدث ذلك إذا استنسخت التطبيق من نظام التحكم في الإصدار الذي يحذفsecrets.properties
ولم تنشئ بعد ملفsecrets.properties
محليًا لتقديم مفتاح واجهة برمجة التطبيقات الخاص بك. - احفظ الملف.
-
في ملف
AndroidManifest.xml
، انتقِل إلىcom.google.android.geo.API_KEY
وعدِّلandroid:value attribute
. في حال عدم توفّر العلامة<meta-data>
، أنشِئها كعلامة فرعية للعلامة<application>
.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Note:
com.google.android.geo.API_KEY
is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the namecom.google.android.maps.v2.API_KEY
. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception. -
In Android Studio, open your module-level
build.gradle
orbuild.gradle.kts
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.defaults.properties
, and set any other properties.Groovy
secrets { // Optionally specify a different file name 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" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
Kotlin
secrets { // Optionally specify a different file name 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" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
الخطوة 4: تعديل بيان التطبيق
يصف هذا القسم الإعدادات المطلوب إضافتها إلى ملف
AndroidManifest.xml
.رقم إصدار "خدمات Google Play"
أضِف التعريف التالي ضمن العنصر
application
. يؤدي ذلك إلى تضمين إصدار خدمات Google Play الذي تم تجميع التطبيق باستخدامه.<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />
إذن تحديد الموقع الجغرافي
إذا كان تطبيقك يحتاج إلى الوصول إلى الموقع الجغرافي للمستخدم، عليك طلب إذن تحديد الموقع الجغرافي في ملف
AndroidManifest.xml
. والخياران هماACCESS_FINE_LOCATION
الذي يتيح تحديد الموقع الجغرافي الدقيق للجهاز، وACCESS_COARSE_LOCATION
الأقل دقة. لمزيد من التفاصيل، يُرجى الاطّلاع على دليل بيانات الموقع الجغرافي.لطلب إذن
ACCESS_FINE_LOCATION
، أضِف هذا الرمز إلى العنصرmanifest
:<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
إذن الوصول إلى وحدة التخزين الخارجية
إذا كنت تستهدف الإصدار 8.3 أو إصدارًا أحدث من حزمة SDK لخدمات Google Play، لن تحتاج إلى إذن
WRITE_EXTERNAL_STORAGE
. إذا كنت تستهدف إصدارات سابقة من حزمة SDK الخاصة بخدمات Google Play، عليك طلب إذن WRITE_EXTERNAL_STORAGE في العنصرmanifest
.<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
مكتبة Apache HTTP القديمة
إذا كنت تستخدم الإصدار
com.google.android.gms:play-services-maps:16.0.0
أو الإصدارات الأقدم وكان تطبيقك يستهدف المستوى 28 من واجهة برمجة التطبيقات (الإصدار 9.0 من نظام التشغيل Android) أو الإصدارات الأحدث، يجب تضمين البيان التالي في العنصر<application>
ضمنAndroidManifest.xml
. وبخلاف ذلك، يمكنك تخطّي هذا البيان.<uses-library android:name="org.apache.http.legacy" android:required="false" />
الخطوة 5: إعداد جهاز Android
لتشغيل تطبيق يستخدم "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لنظام التشغيل Android، يجب نشره على جهاز Android أو محاكي Android يعمل على الإصدار 5.0 أو إصدار أحدث من نظام التشغيل Android ويتضمّن واجهات برمجة التطبيقات من Google.
- لاستخدام جهاز Android، اتّبِع التعليمات الواردة في مقالة تشغيل التطبيقات على جهاز.
- لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام مدير جهاز Android الافتراضي (AVD) الذي يتضمّن "استوديو Android".
الخطوة 6: التحقُّق من توفُّر دعم "خدمة Play" بشكل اختياري
تتطلب حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android توفُّر خدمات Google Play في الجهاز الذي تنشر تطبيقك عليه. توفر Google طريقة يمكنك الاتصال بها من تطبيقك للتحقق منها. للحصول على مزيد من المعلومات، يمكنك الاطلاع على التحقق مما إذا تم تثبيت خدمات Google Play أم لا.
الخطوات التالية
بعد إعداد مشروعك، يمكنك إضافة خريطة.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2024-07-13 (حسب التوقيت العالمي المتفَّق عليه)
[] []