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

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

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

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

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

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

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

  1. في ملف settings.gradle ذي المستوى الأعلى، ضمِّن بوابة مكوّنات Gradle الإضافية ومستودع Google Maven ومستودع Maven المركزي ضمن مجموعة pluginManagement. يجب أن تظهر كتلة pluginManagement قبل أي عبارات أخرى في النص البرمجي. 
    pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
  2. في ملف settings.gradle ذي المستوى الأعلى، يمكنك تضمين مستودع Maven من Google ومستودع 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 لأجهزة 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) لتطبيق "خرائط Google" لنظام التشغيل Android. للتوافق مع الأنظمة القديمة، تتيح واجهة برمجة التطبيقات أيضًا استخدام الاسم com.google.android.maps.v2.API_KEY. يسمح هذا الاسم القديم بالمصادقة على الإصدار الثاني من واجهة برمجة التطبيقات لخرائط 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 من واجهة برمجة التطبيقات (الإصدار 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 APIs.

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

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

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