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

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

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

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

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

الخطوة 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 ذي المستوى الأعلى، أدرِج مستودع Google Maven ومستودع 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")
   }

   Groovy

   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
           // ...
       }
   }

   Groovy

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

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

   Kotlin

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

   Groovy

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

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

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

لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي 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")
       }
   }

   Groovy

   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")
   }

   Groovy

   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. أنشئ ملف local.defaults.properties في الدليل على المستوى الأعلى، أي المجلد نفسه الذي يحتوي على ملف secrets.properties، ثم أضِف الرمز التالي.

   MAPS_API_KEY=DEFAULT_API_KEY

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

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

8. في 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"
   }
           

   Groovy

   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"
   }
           

الخطوة 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) لنظام التشغيل Android في "خرائط Google"، يجب نشره على جهاز Android أو محاكي Android يستند إلى الإصدار 5.0 من نظام التشغيل Android أو إصدار أحدث ويتضمّن واجهات Google API.

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

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

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

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

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