إعداد مشروع في "استوديو Android"

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

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

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

يصف هذا المستند بيئة تطوير تستخدم الإصدار 8.2 من Android Studio Hedgehog ومكوّن Android Gradle الإضافي.

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

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

1. في ملف settings.gradle.kts على مستوى التطبيق، أدرِج بوابة المكوّنات الإضافية في Gradle، مستودع Google Maven، مستودع Maven المركزي ضمن مجموعة pluginManagement. يجب أن يظهر الرمز البرمجي pluginManagement قبل أي عبارات أخرى في النص البرمجي.

   pluginManagement {
       repositories {
           gradlePluginPortal()
           google()
           mavenCentral()
       }
   } 

2. في ملف settings.gradle.kts من المستوى الأعلى، أدرِج مستودع Maven من Google ومستودع Maven المركزي ضمن مجموعة dependencyResolutionManagement:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. في ملف build.gradle.kts أو build.gradle على مستوى الوحدة، أضِف تبعية خدمات Google Play لحزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل Android.

   Kotlin

   dependencies {
   
       // Maps SDK for Android
       implementation("com.google.android.gms:play-services-maps:19.0.0")
   }

   رائع

   dependencies {
   
       // Maps SDK for Android
       implementation "com.google.android.gms:play-services-maps:19.0.0"
   }

4. في ملف build.gradle.kts أو build.gradle على مستوى الوحدة، اضبط compileSdk وminSdk على القيم التالية:

   Kotlin

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 21
           // ...
       }
   }

   رائع

   android {
       compileSdk 34
   
       defaultConfig {
           minSdk 21
           // ...
       }
   }

5. في قسم buildFeatures من ملف build.gradle.kts أو build.gradle على مستوى الوحدة، أضِف فئة BuildConfig التي يمكنك استخدامها للوصول إلى قيم البيانات الوصفية المحدّدة لاحقًا في هذه العملية:

   Kotlin

   android {
     // ...
     buildFeatures {
       buildConfig = true
       // ...
     }
   }

   رائع

   android {
     // ...
     buildFeatures {
       buildConfig true
       // ...
     }
   }

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

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

لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secrets Gradle لأجهزة Android.

لتثبيت المكوّن الإضافي Secrets Gradle لأجهزة Android في مشروعك على "خرائط Google"، اتّبِع الخطوات التالية:

1. في Android Studio، افتح ملف build.gradle.kts أو build.gradle الأولي وأضِف الرمز البرمجي التالي إلى عنصر dependencies ضمن buildscript.

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   رائع

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

2. افتح ملف build.gradle.kts أو build.gradle على مستوى الوحدة وأضِف رمز الربط التالي إلى عنصر plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   رائع

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. في ملف build.gradle.kts أو build.gradle على مستوى الوحدة، تأكَّد من ضبط targetSdk وcompileSdk على 34.
4. احفظ الملف و امزِن مشروعك مع Gradle.
5. افتح ملف secrets.properties في الدليل من المستوى الأعلى، ثم أضِف الرمز التالي: استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات. عليك تخزين مفتاحك في هذا الملف لأنّه تم استبعاد secrets.properties من التحقّق من الملفات في نظام التحكّم في الإصدارات

   MAPS_API_KEY=YOUR_API_KEY

6. احفظ الملف.

7. أنشئ ملف local.defaults.properties في الدليل على المستوى الأعلى، وهو المجلد نفسه الذي يتضمّن ملف secrets.properties، ثم أضِف الرمز التالي.

   MAPS_API_KEY=DEFAULT_API_KEY

   الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات في حال عدم العثور على ملف secrets.properties حتى لا تفشل عمليات الإنشاء. يمكن أن يحدث ذلك في حال استنساخ التطبيق من نظام تحكّم في الإصدارات يتجاهل secrets.properties ولم تنشئ بعد ملف secrets.properties على الجهاز لتوفير مفتاح واجهة برمجة التطبيقات.

8. احفظ الملف.
9. في ملف 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}" />

   ملاحظة: com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة مع عدة واجهات برمجة تطبيقات مستندة إلى "خرائط Google" على نظام التشغيل Android، بما في ذلك حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل Android. للتوافق مع الإصدارات السابقة، تتيح واجهة برمجة التطبيقات أيضًا استخدام الاسم com.google.android.maps.v2.API_KEY. لا يسمح هذا الاسم القديم بالمصادقة إلا على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. في حال تحديد كليهما، يُعرِض واجهة برمجة التطبيقات استثناءً.

10. في Android Studio، افتح ملف build.gradle.kts أو build.gradle على مستوى الوحدة وحرِّر السمة secrets. إذا لم تكن السمة secrets متوفّرة، أضِفها.

    عدِّل سمات المكوّن الإضافي لضبط propertiesFileName على secrets.properties، وdefaultPropertiesFileName على local.defaults.properties، وأي سمات أخرى.

    Kotlin

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        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.*"
    }
            

    رائع

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        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 من واجهة برمجة التطبيقات (Android 9.0) أو إصدارًا أحدث، يجب تضمين البيان التالي ضمن عنصر <application> في AndroidManifest.xml. بخلاف ذلك، يمكنك تخطّي هذا البيان.

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

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

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

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

الخطوة 6: التحقّق من توفّر "خدمات Play" اختياريًا

تتطلّب حزمة تطوير البرامج (SDK) لخرائط Google لنظام التشغيل Android أن يكون جهازك الذي يتم نشر تطبيقك عليه مزوّدًا بـ "خدمات Google Play". تقدّم Google طريقة يمكنك الاستدعاء من تطبيقك للتحقّق من ذلك. لمزيد من المعلومات، يُرجى الاطّلاع على التحقّق مما إذا كانت "خدمات Google Play" مثبَّتة.

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

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