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

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

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

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

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

ملاحظة: إذا كانت بيئة التطوير تستخدم إصدارًا مختلفًا من Android Studio أو Gradle، قد تحتاج إلى تعديل الخطوات استنادًا إلى هذين الإصدارَين. لمزيد من المعلومات، معلومات حول إصدارَي "استوديو Android" و"أداة Gradle"، يُرجى الاطّلاع على المكوّن الإضافي لنظام Gradle المتوافق مع Android والتوافق مع "استوديو Android"

الخطوة 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 لـ حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط 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 على القيمتين التاليتين:
   ملاحظة: تأكَّد من أنّ السمة compileSdk هي تم ضبطها على 34 أو أعلى وminSdk على 21 أو أعلى.

   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 على GitHub لمعرفة أحدث متطلبات النظام وتعليمات التثبيت.

لتثبيت مكوّن 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 من التحقق من عنصر تحكّم الإصدار .
   ملاحظة: إذا لم يكن ملف secrets.properties موجودًا، أنشِئه في المجلد نفسه الذي يتضمّن ملف local.properties.

   MAPS_API_KEY=YOUR_API_KEY

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

7. أنشئ الملف local.defaults.properties في دليل المستوى الأعلى، بالطريقة نفسها كملف secrets.properties، ثم أضف الرمز التالي.

   ملاحظة: أدخِل الرمز كما هو موضّح. لا تستبدِل DEFAULT_API_KEY بمفتاح واجهة برمجة التطبيقات.

   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 الأساسي، بما في ذلك حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android للتوافق مع الأنظمة القديمة، توفر واجهة برمجة التطبيقات أيضًا يتوافق مع الاسم com.google.android.maps.v2.API_KEY. هذا المحتوى القديم اسمها بالمصادقة على الإصدار الثاني من واجهة برمجة تطبيقات خرائط Android فقط. يمكن لتطبيق ما تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات يطرح استثناء.

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 في البدء السريع.

لطلب إذن 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

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

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

  

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

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

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

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