توضّح هذه الصفحة كيفية إعداد مشروع على "استوديو Android" لاستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android بدون استخدام نموذج "خرائط Google" كما هو موضح بالتفصيل في مقالة Quickstart.
يهيئ نموذج خرائط Google خريطة أساسية ويضيفها تلقائيًا إلى مشروع استوديو Android. مع ذلك، يمكنك أيضًا إضافة خريطة إلى مشروع على Android. يستخدم نموذجًا مختلفًا من "استوديو Android" للقيام بذلك، فإنك بحاجة إلى تهيئة مشروعك ثم إضافة الخريطة.
الخطوة 1: إعداد "استوديو Android"
تصف هذه الوثيقة بيئة تطوير تستخدم Android Studio Hedgehog المكوّن الإضافي لنظام Gradle المتوافق مع Android الإصدار 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 لـ حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات AndroidGroovy
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
إلى القيم التالية:Groovy
android { compileSdk 34 defaultConfig { minSdk 21 // ... } }
Kotlin
android { compileSdk = 34 defaultConfig { minSdk = 21 // ... } }
- في القسم
buildFeatures
من ملفbuild.gradle
على مستوى الوحدة، أضف الفئةBuildConfig
، التي يمكنك استخدامها للوصول إلى قيم البيانات الوصفية المحددة لاحقًا في هذا الإجراء:Groovy
android { // ... buildFeatures { buildConfig true // ... } }
Kotlin
android { // ... buildFeatures { buildConfig = true // ... } }
الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع
يصف هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات كي يمكن الرجوع إليه بشكل آمن من خلال
تطبيقك. يجب عدم التحقق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذا ننصحك
تخزينه في ملف secrets.properties
، الموجود في الدليل الجذري
مشروعك. لمزيد من المعلومات عن ملف secrets.properties
، يمكنك الاطّلاع على
ملفات خصائص Gradle:
لتبسيط هذه المهمة، نوصيك باستخدام المكوّن الإضافي السري لنظام Gradle المتوافق مع Android
لتثبيت مكوّن Secrets Gradle الإضافي لنظام التشغيل Android في مشروعك على "خرائط Google"، اتّبِع الخطوات التالية:
-
في "استوديو Android"، افتح
build.gradle
أوbuild.gradle.kts
المستوى الأعلى. وإضافة التعليمة البرمجية التالية إلى العنصرdependencies
ضمنbuildscript
Groovy
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
Groovy
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 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-08-13 (حسب التوقيت العالمي المتفَّق عليه)
[{ "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":"غير ذلك" }]