إعداد مشروعك، الإصدار 4.99 والإصدارات الأقدم

تتضمّن هذه الدليل متطلبات إعدادات التصميم لاستخدام Navigation SDK لنظام التشغيل Android. تفترض التعليمات أنّ لديك بيئة تطوير متكاملة (IDE) لنظام التشغيل Android مثبَّتة وأنّك على دراية بتطوير تطبيقات Android.

الحدّ الأدنى من المتطلبات لاستخدام Navigation SDK

تنطبق هذه المتطلبات على الإصدار 4.99 والإصدارات الأقدم من "حزمة تطوير البرامج للتنقّل على أجهزة Android".

وحدة تحكّم Google Cloud

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

إعداد مشاريعك: مشروع Cloud Console ومشروع Android

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

لإعداد هذه الميزة، اتّبِع الخطوات التالية:

في متصفّح الويب المفضّل لديك، سجِّل الدخول إلى وحدة تحكّم Cloud وأنشِئ مشروع وحدة تحكّم Cloud.
في بيئة التطوير المتكاملة، مثل "استوديو Android"، أنشئ مشروعًا لتطوير تطبيقات Android واحتفظ باسم الحزمة.
يُرجى التواصل مع ممثل "منصة خرائط Google" لمنحك إذن الوصول إلى حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation في مشروعك على Cloud Console.
أثناء تواجدك في لوحة بيانات Cloud Console في متصفّح الويب، أنشئ بيانات اعتماد لإنشاء مفتاح واجهة برمجة تطبيقات مع قيود.
في صفحة مفتاح واجهة برمجة التطبيقات، انقر على تطبيقات Android في منطقة قيود التطبيق.
انقر على إضافة اسم الحزمة والملف المرجعي، ثم أدخِل اسم حزمة مشروع التطوير والملف المرجعي لشهادة SHA-1 لهذا المفتاح.
انقر على حفظ.

إضافة حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation إلى مشروعك

تتوفّر حزمة تطوير البرامج للتنقّل باستخدام Maven أو حزمة AAR. بعد إنشاء مشروع التطوير، يمكنك دمج حزمة تطوير البرامج (SDK) فيه باستخدام إحدى الطرق التالية.

استخدام Maven للإصدار 4.5 والإصدارات الأحدث من حزمة Navigation SDK (إجراء يُنصح به)

يستخدم المثال التالي مستودع google() Maven، وهو أبسط طريقة وأكثرها يُنصح بها لإضافة حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation إلى مشروعك.

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

Gradle

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

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

في حال الترقية من مستودع Maven الأصلي، يُرجى العِلم بأنّ اسمَي المجموعة والعنصر قد تغيّرا، ولم يعُد المكوّن الإضافي com.google.cloud.artifactregistry.gradle-plugin ضروريًا.

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

allprojects {
...
// Required: you must exclude the Google Play service Maps SDK from
// your transitive dependencies to make nsure 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>com.google.android.libraries.navigation</groupId>
     <artifactId>navigation</artifactId>
     <version>VERSION_NUMBER</version>
</dependency>
</dependencies>

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

<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>

استخدام Maven مع حزمة Navigation SDK قبل الإصدار 4.5 أو مع حزمة Driver SDK

ستظل حزمة تطوير البرامج للتنقّل متاحة باستخدام مستودع Maven الأصلي خلال بقية إصدارات السلسلة 4. وهي المكتبة نفسها التي تتضمّن جميع التحديثات نفسها المتوفّرة في الإصدار أعلاه، وتوفّر توافقًا مع Driver SDK والمكتبات الأخرى أثناء عملية الانتقال. يتطلّب استخدام هذه التبعية تسجيل الدخول إلى مشروعك على السحابة الإلكترونية باستخدام gcloud عند التجميع.

اضبط بيئتك للوصول إلى مستودع Maven الخاص بـ Google كما هو موضّح في قسم المتطلبات الأساسية من مستندات Consumer SDK. يتم التحكّم في إمكانية الوصول إلى Navigation SDK من خلال مجموعة مساحة عمل.

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

Gradle

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

dependencies {
...
implementation 'com.google.android.maps:navsdk:VERSION_NUMBER'
}

وأضِف ما يلي إلى 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>com.google.android.maps</groupId>
     <artifactId>navsdk</artifactId>
     <version>VERSION_NUMBER</version>
</dependency>
</dependencies>

<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>

استخدام حِزمة AAR تم تنزيلها (لا يُنصح بذلك)

تتوفّر حزمة Navigation SDK أيضًا كحزمة AAR. بعد إنشاء مشروع التطوير، يمكنك دمج حزمة SDK. تفترض هذه التعليمات استخدام "استوديو Android" كبيئة تطوير متكاملة.

نزِّل أحدث إصدار من حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation من Google Drive المشترَك واستخرِجه. إذا لم يكن لديك إذن الوصول، يُرجى التواصل مع ممثّلك.
في استوديو Android، افتح مشروعًا وأضِف حزمة خدمات Google Play باستخدام SDK Manager.
من دليل ملف ZIP، انسخ libs/google_navigation_navmap.aar إلى دليل app/libs في مشروعك.

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

implementation(name: 'google_navigation_navmap', ext: 'aar')

وأضِف ما يلي إلى 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'
       }
   }
}

ضبط الإصدار

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

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

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

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

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

الإعدادات المطلوبة لحزمة تطوير البرامج للتنقّل
1. اضبط minSdkVersion على 23 أو أعلى.
2. اضبط قيمة targetSdkVersion على 30 أو أكثر.
3. أضِف إعداد dexOptions يزيد من javaMaxHeapSize.
4. اضبط الموقع الجغرافي للمكتبات الإضافية.
5. أضِف repositories وdependencies إلى حزمة تطوير البرامج للتنقّل.
6. استبدِل أرقام الإصدارات في العناصر التابعة بأحدث الإصدارات المتاحة.
إعدادات اختيارية لتقليل مدّة التصميم
- فعِّل تقليص حجم الرموز وتقليص الموارد باستخدام R8/ProGuard لإزالة الرموز والموارد غير المستخدَمة من التبعيات. إذا استغرقت خطوة R8/ProGuard وقتًا طويلاً جدًا، ننصحك بتفعيل Multidex لأغراض التطوير.
- قلِّل عدد ترجمات اللغات المضمّنة في الإصدار: اضبط resConfigs على لغة واحدة أثناء التطوير. بالنسبة إلى الإصدار النهائي، اضبط resConfigs على اللغات التي تستخدمها فعليًا. يتضمّن Gradle تلقائيًا سلاسل موارد لجميع اللغات التي تتوافق مع Navigation SDK.

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

apply plugin: 'com.android.application'
apply plugin: 'com.google.cloud.artifactregistry.gradle-plugin'

ext {
    androidxVersion = "1.0.0"
    lifecycle_version = "1.1.1"
}

android {
    compileSdkVersion 30
    buildToolsVersion '28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 30
        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 {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

// This tells Gradle where to look to find additional libraries - in this case, the
// google_navigation_navmap.aar file.
repositories {
    flatDir {
        dirs 'libs'
    }
    google()

    // Required for accessing the Navigation SDK on Google's Maven repository.
    maven {
        url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
    }
}

dependencies {
    // Include the Google Navigation SDK
    implementation 'com.google.android.maps:navsdk:4.4.0'

    // The included AAR file under libs can be used instead of the Maven repository.
    // Uncomment the line below and comment out the previous dependency to use
    // the AAR file instead. Make sure that you add the AAR file to the libs directory.
    // implementation(name: 'google_navigation_navmap', ext: 'aar')

    // These dependencies are required for the Navigation SDK to function
    // properly at runtime.
    implementation 'org.chromium.net:cronet-fallback:69.3497.100'
    // Optional for Cronet users:
    // implementation 'org.chromium.net:cronet-api:69.3497.100'
    implementation 'androidx.appcompat:appcompat:${androidxVersion}'
    implementation 'androidx.cardview:cardview:${androidxVersion}'
    implementation 'com.google.android.material:material:${androidxVersion}'
    implementation 'androidx.mediarouter:mediarouter:${androidxVersion}'
    implementation 'androidx.preference:preference:${androidxVersion}'
    implementation 'androidx.recyclerview:recyclerview:${androidxVersion}'
    implementation 'androidx.legacy:legacy-support-v4:${androidxVersion}'
    implementation 'com.github.bumptech.glide:glide:4.9.0'
    implementation 'com.github.bumptech.glide:okhttp-integration:4.9.0'
    implementation 'android.arch.lifecycle:common-java8:$lifecycle_version'
    implementation 'com.android.support:multidex:1.0.3'
    implementation 'com.google.android.datatransport:transport-api:2.2.0'
    implementation 'com.google.android.datatransport:transport-backend-cct:2.2.0'
    implementation 'com.google.android.datatransport:transport-runtime:2.2.0'
    implementation 'joda-time:joda-time:2.9.9'
    annotationProcessor 'androidx.annotation:annotation:1.1.0'
    annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'
}

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

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

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

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

في "استوديو 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")
    }
}

افتح ملف 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")
}

إذا كنت تستخدم "استوديو Android"، زامِن مشروعك مع Gradle.
افتح ملف local.properties في دليل مستوى مشروعك، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات.
```
MAPS_API_KEY=YOUR_API_KEY
```
يمكنك إما إضافة مفتاح واجهة برمجة التطبيقات إلى ملف 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 Plugin المفتاح في الفئة 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() قبل إعداد أي مكوّنات أخرى من حزمة Navigation SDK، مثل Navigator.
  - يحلّ المفتاح الذي تقدّمه باستخدام هذه الطريقة محلّ أي مفتاح لواجهة برمجة التطبيقات في AndroidManifest.xml.
  - استخدِم الإصدار 7.6 أو إصدارًا أحدث من حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation.

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

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

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

NOTICE.txt
LICENSES.txt

إعداد مشروعك، الإصدار 4.99 والإصدارات الأقدم تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الحدّ الأدنى من المتطلبات لاستخدام Navigation SDK

إعداد مشاريعك: مشروع Cloud Console ومشروع Android

إضافة حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation إلى مشروعك

استخدام Maven للإصدار 4.5 والإصدارات الأحدث من حزمة Navigation SDK (إجراء يُنصح به)

Gradle

Maven

استخدام Maven مع حزمة Navigation SDK قبل الإصدار 4.5 أو مع حزمة Driver SDK

Gradle

Maven

استخدام حِزمة AAR تم تنزيلها (لا يُنصح بذلك)

ضبط الإصدار

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

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

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

Groovy

Kotlin

Groovy

Kotlin

Kotlin

جافا

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

إعداد مشروعك، الإصدار 4.99 والإصدارات الأقدم