إعداد مشروع Android Studio

تصف هذه الصفحة كيفية تهيئة مشروع في استوديو Android لاستخدام حزمة تطوير البرامج لخرائط Google لنظام التشغيل Android بدون استخدام نموذج خرائط Google الموضح بالتفصيل في البدء السريع.

يعمل نموذج خرائط Google على تهيئة خريطة أساسية وإضافتها تلقائيًا إلى مشروع جديد في استوديو Android. ومع ذلك، يمكنك أيضًا إضافة خريطة إلى مشروع Android باستخدام نموذج Android Studio مختلف. ولإجراء ذلك، عليك تهيئة مشروعك يدويًا ثم إضافة الخريطة.

الخطوة 1: إعداد "استوديو Android"

  1. مطلوب Android Studio Arctic Fox أو إصدار أحدث. في حال عدم إجراء ذلك من قبل، يمكنك تنزيله وتثبيته.
  2. تأكّد من استخدام الإصدار 7.0 من مكوّن Gradle الإضافي لنظام التشغيل Android أو إصدار أحدث في "استوديو Android".

الخطوة الثانية: إعداد حزمة تطوير البرامج (SDK)

تتوفّر حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لأجهزة Android من خلال مستودع Google Maven. لإضافة حزمة تطوير البرامج (SDK) إلى تطبيقك، عليك تنفيذ ما يلي:

  1. في ملف settings.gradle بالمستوى الأعلى، يمكنك تضمين بوابة مكوّن Gradle الإضافية ومستودع Google Maven ومستودع Maven المركزي ضمن المجموعة pluginManagement. يجب أن تظهر العبارة pluginManagement قبل أي عبارات أخرى في النص البرمجي. 
    pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
  2. في ملف settings.gradle ذي المستوى الأعلى، عليك تضمين مستودع Google Maven ومستودع Maven المركزي ضمن حزمة dependencyResolutionManagement: 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
  3. في ملف build.gradle على مستوى الوحدة، أضِف التبعية على خدمات Google Play لحزمة تطوير البرامج (SDK) لخدمة "خرائط Google" لنظام التشغيل Android. 
    dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.0'
    // ...
}
  4. في ملف build.gradle على مستوى الوحدة، اضبط compileSdk وminSdk على القيم التالية: 
    android {
    compileSdk 31

    defaultConfig {
        minSdk 19
        // ...
    }

الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع

يصف هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات بحيث يمكن لتطبيقك الرجوع إليه بشكل آمن. ويجب عدم التحقق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذلك نوصي بتخزينه في ملف local.properties، الموجود في الدليل الجذري لمشروعك. لمزيد من المعلومات حول ملف local.properties، راجِع ملفات خصائص Gradle.

لتبسيط هذه المهمة، نقترح عليك استخدام Secrets Gradle Plugin for Android. لتثبيت المكون الإضافي وتخزين مفتاح واجهة برمجة التطبيقات:

  1. في "استوديو Android"، افتح ملف build.gradle على مستوى مشروعك وأضِف الرمز التالي إلى العنصر dependencies ضمن buildscript. 
    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
  2. بعد ذلك، افتح ملف build.gradle على مستوى الوحدة الخاصة بك وأضِف الرمز التالي إلى العنصر plugins. 
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
  3. احفظ الملف وزامن مشروعك مع Gradle.
  4. افتح local.properties في الدليل على مستوى مشروعك، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات. 
    MAPS_API_KEY=YOUR_API_KEY
  5. احفظ الملف.
  6. في ملف 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) للخرائط" لنظام التشغيل Android. للتوافق مع الأنظمة القديمة، تتوافق واجهة برمجة التطبيقات أيضًا مع الاسم com.google.android.maps.v2.API_KEY. يسمح هذا الاسم القديم بالمصادقة في الإصدار 2 من واجهة برمجة التطبيقات لخرائط Android فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. وإذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

الخطوة 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 من واجهة برمجة التطبيقات (الإصدار Android 9.0) أو إصدار أحدث، يجب تضمين البيان التالي ضمن العنصر <application> من AndroidManifest.xml. بخلاف ذلك، يمكنك تخطّي هذا البيان.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

الخطوة 5: إعداد جهاز Android

لتشغيل تطبيق يستخدم خرائط Google SDK لنظام التشغيل Android، يجب نشره على جهاز Android أو محاكي Android الذي يعتمد على Android 4.0 أو إصدار أحدث ويتضمن واجهات برمجة تطبيقات Google.

  • لاستخدام جهاز يعمل بنظام التشغيل Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز.
  • لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي من خلال استخدام مدير الأجهزة الافتراضية (AVD) من Android الذي يأتي مرفقًا مع Android Studio.

الخطوات التالية

بعد تهيئة مشروعك، يمكنك إضافة خريطة.