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

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

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

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

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

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

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

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

   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.1.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.1.0"
   
   [libraries]
   play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }
       

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

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

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

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

1. في "استوديو Android"، افتح ملف build.gradle.kts أو build.gradle على المستوى الأعلى وأضِف الرمز البرمجي التالي إلى حزمة plugins.

   Kotlin

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

   Groovy

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

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

   Kotlin

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

   Groovy

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

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

   MAPS_API_KEY=YOUR_API_KEY

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

   MAPS_API_KEY=DEFAULT_API_KEY

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

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

7. في "استوديو Android"، افتح ملف 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 root directory (the same folder as the root 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 root directory (the same folder as the root 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 Legacy

إذا كنت تستخدم 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

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

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

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

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

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

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