توضّح هذه الصفحة كيفية ضبط مشروع في "استوديو Android" لاستخدام حزمة تطوير البرامج "خرائط Google" المتوفّرة لنظام التشغيل Android بدون استخدام نموذج "خرائط Google" الموضّح في البدء السريع.
يضبط نموذج "خرائط Google" تلقائيًا الخريطة الأساسية ويضيفها إلى مشروع جديد في Android Studio. ومع ذلك، يمكنك أيضًا إضافة خريطة إلى مشروع على Android يستخدم نموذجًا مختلفًا من "استوديو Android". ولإجراء ذلك، عليك ضبط مشروعك يدويًا ثم إضافة الخريطة.
الخطوة 1: إعداد Android Studio
- يجب إدخال الإصدار Android Studio Fox أو أحدث. تنزيل وتثبيته إذا لم يسبق لك تنزيله
- تأكَّد من استخدام الإصدار 7.0 من مكوّن Gradle الإضافي من Android أو إصدار أحدث في "استوديو Android".
الخطوة الثانية: إعداد حزمة تطوير البرامج (SDK)
تتوفّر حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لأجهزة Android من خلال مستودع Google Maven. لإضافة حزمة تطوير البرامج (SDK) إلى تطبيقك، عليك تنفيذ ما يلي:
- في ملف
settings.gradle
ذي المستوى الأعلى، يمكنك تضمينبوابة مكوّن Graddle ومستودع Google Maven ومستودع Maven المركزي ضمن كتلةpluginManagement
. ويجب أن تظهر كتلةpluginManagement
قبل أي عبارات أخرى في النص البرمجي.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- في ملف
settings.gradle
ذي المستوى الأعلى، أدرِج مستودع Google Maven ومستودع Maven المركزي ضمن كتلةdependencyResolutionManagement
:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- في ملف
build.gradle
على مستوى الوحدة، أضِف اعتمادية خدمات Google Play لحزمة تطوير البرامج "SDK للخرائط" لنظام التشغيل Android.dependencies { implementation 'com.google.android.gms:play-services-maps:18.1.0' // ... }
- في ملف
build.gradle
على مستوى الوحدة، اضبطcompileSdk
وminSdk
على القيم التالية:android { compileSdk 31 defaultConfig { minSdk 19 // ... }
الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع
يوضّح هذا القسم طريقة تخزين مفتاح واجهة برمجة التطبيقات بحيث يمكن الرجوع إليه بأمان من خلال تطبيقك. عليك عدم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكّم بالإصدار، لذلك ننصحك
بتخزينه في ملف local.properties
، والذي يتوفّر في الدليل الجذري لمشروعك. للحصول على مزيد من المعلومات عن ملف local.properties
، يُرجى الاطّلاع على ملفات خصائص Gradle.
لتبسيط هذه المهمة، نقترح عليك استخدام Secrets Gradle Plugin for Android. لتثبيت المكوِّن الإضافي وتخزين مفتاح واجهة برمجة التطبيقات:
- في "استوديو Android"، افتح ملف
build.gradle
على مستوى المشروع وأضِف الرمز التالي إلى العنصرdependencies
ضمنbuildscript
.plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false }
- بعد ذلك، افتح ملف
build.gradle
على مستوى الوحدة وأضِف الرمز التالي إلى العنصرplugins
.id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
- احفظ الملف وزامن مشروعك مع Gradle.
- افتح
local.properties
في الدليل على مستوى مشروعك، ثم أضِف الرمز التالي. استبدِلYOUR_API_KEY
بمفتاح واجهة برمجة التطبيقات.MAPS_API_KEY=YOUR_API_KEY
- احفظ الملف.
- في ملف
AndroidManifest.xml
، انتقِل إلىcom.google.android.geo.API_KEY
وعدِّلandroid:value attribute
على النحو التالي:<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
ملاحظة: كما هو موضّح أعلاه، com.google.android.geo.API_KEY
هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على عدة واجهات برمجة تطبيقات مستندة إلى "خرائط Google" على نظام Android الأساسي، بما في ذلك حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل Android. للتوافق مع الأنظمة القديمة، تتوافق واجهة برمجة التطبيقات أيضًا مع الاسم com.google.android.maps.v2.API_KEY
. يسمح هذا الاسم القديم بالمصادقة في الإصدار 2 من واجهة برمجة تطبيقات "خرائط Google" فقط. يمكن للتطبيق
تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. وإذا تم تحديد كلا النوعَين، ستعرض واجهة برمجة التطبيقات استثناءً.
الخطوة 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
لتشغيل تطبيق يستخدم حزمة تطوير البرامج (SDK) في "خرائط Google" لأجهزة Android، يجب نشره على جهاز Android أو محاكي Android يستند إلى الإصدار 4.0 من نظام التشغيل Android أو إصدار أحدث، ويتضمن ذلك واجهات برمجة تطبيقات Google.
- لاستخدام جهاز Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز معيّن.
- لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام مدير الأجهزة الافتراضية (AVD) من Android الذي يحتوي على "استوديو Android".
الخطوات التالية
بعد إعداد مشروعك، يمكنك إضافة خريطة.