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

توضّح هذه الصفحة كيفية دمج حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation API في مشروع التطوير.

إضافة حزمة Navigation SDK إلى مشروعك

تتوفّر حزمة Navigation SDK من خلال مستودع Google Maven. يمكنك إضافة حزمة تطوير البرامج (SDK) إلى مشروعك باستخدام إعدادات build.gradle Gradle أو pom.xml Maven.

1. أضِف الاعتمادية التالية إلى إعدادات Gradle أو Maven، مع استبدال العنصر النائب VERSION_NUMBER بإصدار حزمة Navigation SDK لنظام التشغيل Android المطلوب.

   Gradle

   أضِف ما يلي إلى ملف build.gradle على مستوى الوحدة:

   dependencies {
           ...
           implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
   }
   

   Maven

   أضِف ما يلي إلى pom.xml:

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.libraries.navigation</groupId>
       <artifactId>navigation</artifactId>
       <version>VERSION_NUMBER</version>
     </dependency>
   </dependencies>
   

2. إذا كان لديك أي اعتماديات تستخدم حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google"، عليك استبعاد الاعتمادية في كل اعتمادية تم تعريفها وتعتمد على حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google".

   Gradle

   أضِف ما يلي إلى build.gradle ذي المستوى الأعلى:

   allprojects {
           ...
           // Required: you must exclude the Google Play service Maps SDK from
           // your transitive dependencies to make sure there won't be
           // multiple copies of Google Maps SDK in your binary, as the Navigation
           // SDK already bundles the Google Maps SDK.
           configurations {
               implementation {
                   exclude group: 'com.google.android.gms', module: 'play-services-maps'
               }
           }
   }
   

   Maven

   أضِف ما يلي إلى pom.xml:

   <dependencies>
     <dependency>
     <groupId>project.that.brings.in.maps</groupId>
     <artifactId>MapsConsumer</artifactId>
     <version>1.0</version>
       <exclusions>
         <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
         <exclusion>  <!-- declare the exclusion here -->
           <groupId>com.google.android.gms</groupId>
           <artifactId>play-services-maps</artifactId>
         </exclusion>
       </exclusions>
     </dependency>
   </dependencies>
   

ضبط الإصدار

بعد إنشاء المشروع، يمكنك ضبط الإعدادات لإنشاء حزمة ناجحة واستخدام حزمة Navigation SDK.

تعديل الخصائص المحلية

• في مجلد نصوص Gradle البرمجية، افتح الملف local.properties وأضِف android.useDeprecatedNdk=true.

تعديل نص Gradle البرمجي

• افتح الملف build.gradle (Module:app) واتّبِع الإرشادات التالية لتعديل الإعدادات بما يتوافق مع متطلبات Navigation SDK، واحرص على ضبط خيارات التحسين أيضًا.

  الإعدادات المطلوبة لحزمة تطوير البرامج للتنقّل

  1. اضبط قيمة minSdkVersion على 24 أو أعلى.
  2. اضبط targetSdkVersion على 36 أو أكثر.
  3. أضِف إعداد dexOptions يزيد من javaMaxHeapSize.
  4. اضبط الموقع الجغرافي للمكتبات الإضافية.
  5. أضِف repositories وdependencies إلى حزمة Navigation SDK.
  6. استبدِل أرقام الإصدارات في العناصر التابعة بأحدث الإصدارات المتاحة.

  إعدادات اختيارية لتقليل مدّة التصميم

  • فعِّل تقليص حجم الرموز وتقليص الموارد باستخدام R8 أو ProGuard لإزالة الرموز والموارد غير المستخدَمة من العناصر التابعة. إذا استغرقت خطوة R8/ProGuard وقتًا طويلاً جدًا، ننصحك بتفعيل Multidex لأغراض التطوير.
  • قلِّل عدد ترجمات اللغات المضمّنة في الإصدار: اضبط resConfigs للغة واحدة أثناء التطوير. بالنسبة إلى الإصدار النهائي، اضبط قيمة resConfigs على اللغات التي تستخدمها فعليًا. يتضمّن Gradle تلقائيًا سلاسل موارد لجميع اللغات التي تتوافق مع Navigation SDK.

  إضافة عملية إزالة التشويش لتوافق Java8

  • إذا كنت تنشئ تطبيقك باستخدام الإصدار 4.0.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android، يتيح لك المكوّن الإضافي استخدام عدد من واجهات برمجة التطبيقات للغة Java 8. لمزيد من المعلومات، راجِع توافق Java 8 مع إزالة التجميل اللغوي. اطّلِع على مثال مقتطف نص برمجي للإصدار أدناه لمعرفة كيفية استخدام خيارات التجميع والاعتماديات.
  • استخدِم إصدارات Gradle والمكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) ومكتبة Desugar التي تتوافق مع إصدار Navigation SDK. اطّلِع على الجدول التالي.
  • يجب تفعيل مكتبة Desugar للوحدة app وأي وحدة تعتمد بشكل مباشر على حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation.

يسرد الجدول التالي إصدارات Gradle وAGP ومكتبة Desugar المطلوبة لكل إصدار من Navigation SDK.

في ما يلي مثال على نص برمجة Gradle لإنشاء التطبيق. راجِع التطبيقات النموذجية للحصول على مجموعات محدَّثة من التبعيات، لأنّ إصدار حزمة Navigation SDK الذي تستخدمه قد يكون أحدث أو أقدم قليلاً من هذه المستندات.

apply plugin: 'com.android.application'

ext {
    navSdk = "__NAVSDK_VERSION__"
}

android {
    compileSdk 33
    buildToolsVersion='28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
        // Set this to the languages you actually use, otherwise you'll include resource strings
        // for all languages supported by the Navigation SDK.
        resConfigs "en"
        multiDexEnabled true
    }

    dexOptions {
        // This increases the amount of memory available to the dexer. This is required to build
        // apps using the Navigation SDK.
        javaMaxHeapSize "4g"
    }
    buildTypes {
        // Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
        // The configuration is included transitively by depending on the Navigation SDK.
        // If the ProGuard step takes too long, consider enabling multidex for development work
        // instead.
        all {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

repositories {
    // Navigation SDK for Android and other libraries are hosted on Google's Maven repository.
    google()
}

dependencies {
    // Include the Google Navigation SDK.
    // Note: remember to exclude Google Play service Maps SDK from your transitive
    // dependencies to avoid duplicate copies of the Google Maps SDK.
    api "com.google.android.libraries.navigation:navigation:${navSdk}"

    // Declare other dependencies for your app here.

    annotationProcessor "androidx.annotation:annotation:1.7.0"
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs_nio:2.1.5'
}

إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

يوضّح هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات كي يتمكّن تطبيقك من الرجوع إليه بشكل آمن. ننصحك بعدم إدخال مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدارات، بل بتخزينه في الملف 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 أو تقديم مفتاح واجهة برمجة التطبيقات آليًا.
   • أضِف مفتاح واجهة برمجة التطبيقات إلى AndroidManifest.xml:

     <meta-data
         android:name="com.google.android.geo.API_KEY"
         android:value="${MAPS_API_KEY}" />
             

     ملاحظة: ‫com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على عدة واجهات برمجة تطبيقات مستندة إلى "خرائط Google" على نظام Android الأساسي، بما في ذلك حزمة Navigation SDK لنظام التشغيل Android. لضمان التوافق مع الأنظمة القديمة، تتيح واجهة برمجة التطبيقات أيضًا استخدام الاسم com.google.android.maps.v2.API_KEY. يتيح هذا الاسم القديم المصادقة على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

   • قدِّم مفتاح واجهة برمجة التطبيقات آليًا:

     يوفّر المكوّن الإضافي Secrets Gradle المفتاح في الفئة BuildConfig. في عملية تهيئة تطبيقك (على سبيل المثال، في طريقة Application.onCreate())، استدعِ الطريقة على النحو التالي:

     Kotlin

     1. أضِف عبارات الاستيراد التالية:

        import com.google.android.libraries.navigation.NavigationApi

     2. أضِف ما يلي إلى طريقة Application.onCreate():

        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

     جافا

     1. أضِف عبارات الاستيراد التالية:

        import com.google.android.libraries.navigation.NavigationApi;

     2. أضِف ما يلي إلى طريقة Application.onCreate():

        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);

     ملاحظة: عند استخدام setApiKey()، يُرجى مراعاة ما يلي:

     • يجب تقديم مفتاح واجهة برمجة تطبيقات غير فارغ وغير قيمته فارغة.
     • يجب استدعاء setApiKey() مرة واحدة فقط خلال فترة استخدام تطبيقك. تُصدر الطريقة IllegalStateException إذا تم استدعاؤها أكثر من مرة.
     • اتّصِل بالدالة setApiKey() قبل تهيئة أي مكوّنات أخرى من حزمة تطوير البرامج للتنقّل، مثل Navigator.
     • يحلّ المفتاح الذي تقدّمه باستخدام هذه الطريقة محلّ أي مفتاح لواجهة برمجة التطبيقات في AndroidManifest.xml.
     • استخدِم الإصدار 7.6 أو إصدارًا أحدث من حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation.

تضمين الإشارات المطلوبة إلى المصدر في تطبيقك

إذا كنت تستخدم حزمة Navigation SDK لنظام التشغيل Android في تطبيقك، عليك تضمين نص تحديد المصدر وتراخيص المصادر المفتوحة كجزء من قسم الإشعارات القانونية في تطبيقك.

يمكنك العثور على نص تحديد المصدر وتراخيص البرامج المفتوحة المصدر المطلوبة في ملف zip الخاص بـ "حزمة تطوير البرامج للتنقّل على أجهزة Android" باتّباع الخطوات التالية:

• NOTICE.txt
• LICENSES.txt