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

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

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

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

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

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

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

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

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

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

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

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

   Kotlin

   dependencies {
   
       // Maps SDK for Android
       implementation(libs.play.services.maps)
   }

   Groovy

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

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

   Kotlin

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

   Groovy

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

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

   Kotlin

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

   Groovy

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

6. في ملف libs.versions.toml، أضِف ما يلي:

   [versions]
   play-services-maps = "20.0.0"
   
   [libraries]
   play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }
       

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

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

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

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

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

   Groovy

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

   Kotlin

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

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

   Groovy

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

   Kotlin

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

3. إذا كنت تستخدم "استوديو Android"، زامِن مشروعك مع Gradle.
4. افتح ملف local.properties في دليل مستوى المشروع، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الخاص بك.

   MAPS_API_KEY=YOUR_API_KEY

5. في ملف AndroidManifest.xml، انتقِل إلى com.google.android.geo.API_KEY وعدِّل السمة android:value على النحو التالي:

   <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. يسمح هذا الاسم القديم بالمصادقة على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API فقط. يمكن لأي تطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. في حال تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

الخطوة 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

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

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

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

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

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

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