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

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

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

الخطوة 1: إعداد Android Studio

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

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

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

  1. في ملف settings.gradle ذي المستوى الأعلى، يمكنك تضمينبوابة مكوّن Graddle ومستودع 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 للخرائط" لنظام التشغيل 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) لتطبيق "خرائط 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".

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

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