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

توضّح هذه الصفحة كيفية إعداد مشروع في "استوديو Android" لاستخدام الـ Maps SDK for Android بدون استخدام نموذج "خرائط Google" الموضّح بالتفصيل في دليل الـQuickstart.

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

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

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

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

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

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

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

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

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

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

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