توضّح هذه الصفحة كيفية إعداد مشروع على "استوديو Android" لاستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android بدون استخدام نموذج "خرائط Google" المفصّل في دليل البدء السريع.
يتم إعداد خريطة أساسية في "خرائط Google" تلقائيًا وإضافتها إلى مشروع جديد على "استوديو Android". مع ذلك، يمكنك أيضًا إضافة خريطة إلى مشروع Android يستخدم نموذج "استوديو Android" مختلفًا. ولإجراء ذلك، عليك ضبط مشروعك يدويًا ثم إضافة الخريطة.
الخطوة 1: إعداد "استوديو Android"
يوضّح هذا المستند بيئة تطوير باستخدام Android Studio Hedgehog ومكوّن Android Gradle الإضافي الإصدار 8.2.
الخطوة 2. إعداد حزمة تطوير البرامج (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:18.2.0' }
Kotlin
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:18.2.0") }
- في ملف
build.gradle
على مستوى الوحدة، اضبطcompileSdk
وminSdk
على القيم التالية:minSdk
رائع
android { compileSdk 34 defaultConfig { minSdk 19 // ... } }
Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 19 // ... } }
- في القسم
buildFeatures
من ملفbuild.gradle
على مستوى الوحدة، أضِف الفئةBuildConfig
التي يمكنك استخدامها للوصول إلى قيم البيانات الوصفية التي تم تحديدها لاحقًا في هذا الإجراء:رائع
android { // ... buildFeatures { buildConfig true // ... } }
Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع
يوضِّح هذا القسم طريقة تخزين مفتاح واجهة برمجة التطبيقات كي يتمكّن تطبيقك من الرجوع إليه بأمان. ويجب عدم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذا ننصح بتخزينه في ملف secrets.properties
المتوفّر في الدليل الجذري لمشروعك. لمزيد من المعلومات حول ملف secrets.properties
، يُرجى الاطّلاع على ملفات خصائص Gradle.
لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secret Gradle الإضافي لنظام Android.
لتثبيت المكوّن الإضافي Secret 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 يستند إلى الإصدار 4.0 من نظام التشغيل Android أو الإصدارات الأحدث ويتضمّن Google APIs.
- لاستخدام جهاز 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-03-14 (حسب التوقيت العالمي المتفَّق عليه)
[{ "type": "thumb-down", "id": "missingTheInformationINeed", "label":"لا يحتوي على المعلومات التي أحتاج إليها." },{ "type": "thumb-down", "id": "tooComplicatedTooManySteps", "label":"الخطوات معقدة للغاية / كثيرة جدًا." },{ "type": "thumb-down", "id": "outOfDate", "label":"المحتوى قديم." },{ "type": "thumb-down", "id": "translationIssue", "label":"ثمة مشكلة في الترجمة." },{ "type": "thumb-down", "id": "samplesCodeIssue", "label":"مشكلة في العيّنات / التعليمات البرمجية" },{ "type": "thumb-down", "id": "otherDown", "label":"غير ذلك" }] [{ "type": "thumb-up", "id": "easyToUnderstand", "label":"يسهُل فهم المحتوى." },{ "type": "thumb-up", "id": "solvedMyProblem", "label":"ساعَدني المحتوى في حلّ مشكلتي." },{ "type": "thumb-up", "id": "otherUp", "label":"غير ذلك" }]