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

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

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

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

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

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

الخطوة 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.1.0"
   }

4. في ملف build.gradle.kts أو build.gradle على مستوى الوحدة، اضبط compileSdk وminSdk على القيم التالية:
   ملاحظة: تأكَّد من ضبط compileSdk على 34 أو أعلى وضبط minSdk على 23 أو أعلى.

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

   MAPS_API_KEY=YOUR_API_KEY

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

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

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

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" مفعَّلة.

لطلب إذن 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 يستند إلى الإصدار 6.0 من نظام التشغيل Android أو إصدار أحدث ويتضمّن واجهات برمجة تطبيقات Google.

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

  

  مربّع الحوار إضافة جهاز في "أداة إدارة الأجهزة" في "استوديو Android" يعرض الملفات الشخصية للأجهزة الافتراضية مع رمز Google Play في عمود Play.

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

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

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

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