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

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

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

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

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

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

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

  1. في ملف settings.gradle ذي المستوى الأعلى، ضمِّن بوابة المكوّنات الإضافية في Gradle ومستودع Google Maven ومستودع Maven المركزي ضمن الجزء pluginManagement. يجب أن تظهر مجموعة pluginManagement قبل أي عبارات أخرى في النص البرمجي.
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. في ملف settings.gradle ذي المستوى الأعلى، ضمِّن مستودع Maven من Google ومستودع Maven المركزي ضمن المجموعة dependencyResolutionManagement:
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
        }
    } 
  3. في ملف build.gradle على مستوى الوحدة، أضِف الاعتمادية لخدمات Google Play لحزمة تطوير البرامج (SDK) الخاصة بـ "خرائط Google" لنظام التشغيل Android.

    رائع

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

    Kotlin

    dependencies {
    
        // Maps SDK for Android
        implementation("com.google.android.gms:play-services-maps:18.2.0")
    }
  4. في ملف build.gradle على مستوى الوحدة، اضبط compileSdk وminSdk على القيم التالية: minSdk

    رائع

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

    Kotlin

    android {
        compileSdk = 34
    
        defaultConfig {
            minSdk = 19
            // ...
        }
    }
  5. في القسم buildFeatures من ملف build.gradle على مستوى الوحدة، أضِف الفئة BuildConfig التي يمكنك استخدامها للوصول إلى قيم البيانات الوصفية التي تم تحديدها لاحقًا في هذا الإجراء:

    رائع

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

    Kotlin

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

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

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

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

لتثبيت المكوّن الإضافي Secret Gradle الإضافي لنظام التشغيل Android في مشروع "خرائط Google"، اتَّبِع الخطوات التالية:

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

    رائع

    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.

    رائع

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

    Kotlin

    plugins {
        id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    }
  3. في ملف build.gradle على مستوى الوحدة، تأكَّد من ضبط targetSdk وcompileSdk على 34.
  4. احفظ الملف وزامِن مشروعك مع Gradle.
  5. افتح ملف secrets.properties في دليل المستوى الأعلى، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات. يمكنك تخزين مفتاحك في هذا الملف لأنّه تم استبعاد secrets.properties من التسجيل في نظام التحكّم في الإصدار.
    MAPS_API_KEY=YOUR_API_KEY
  6. احفظ الملف.
  7. أنشِئ ملف local.defaults.properties في دليل المستوى الأعلى، أي الملف نفسه الذي يتضمّن ملف secrets.properties، ثم أضِف الرمز التالي.

    MAPS_API_KEY=DEFAULT_API_KEY

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

  8. احفظ الملف.
  9. في ملف 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}" />

    Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

  10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

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

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

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

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

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

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