يسرد هذا الدليل متطلبات إعدادات الإصدار لاستخدام Navigation SDK لنظام التشغيل Android. تفترض التعليمات أنّ لديك بيئة تطوير متكاملة (IDE) لنظام التشغيل Android مثبَّتة وأنّك على دراية بتطوير تطبيقات Android.
الحدّ الأدنى من متطلبات استخدام "حزمة تطوير البرامج للتنقّل"
تنطبق هذه المتطلبات على الإصدار 4.99 والإصدارات الأقدم من "حزمة تطوير البرامج للتنقّل على أجهزة Android".
-
مشروع تم تفعيل حزمة تطوير البرامج (SDK) للتنقّل فيه للحصول على معلومات حول التوفير، يُرجى التواصل مع ممثل Google Maps Platform.
يجب أن يستهدف تطبيقك المستوى 30 أو مستوى أحدث لواجهة برمجة التطبيقات.
لتشغيل تطبيق تم إنشاؤه باستخدام Navigation SDK، يجب أن يكون جهاز Android مثبّتًا عليه خدمات Google Play ومفعّلة.
يجب إضافة نص الإحالات إلى المصادر والتراخيص إلى التطبيق.
إعداد مشاريعك: مشروع Cloud Console ومشروع Android
قبل إنشاء تطبيق أو اختباره، عليك إنشاء مشروع في Cloud Console وإضافة بيانات اعتماد مفتاح واجهة برمجة التطبيقات. يجب أن يتضمّن المشروع إذنًا بالوصول إلى "حزمة تطوير البرامج للتنقّل". يتم منح جميع المفاتيح ضمن مشروع Cloud Console الإذن نفسه بالوصول إلى Navigation SDK. يمكن أن يرتبط المفتاح بأكثر من مشروع تطوير واحد. إذا كان لديك مشروع في وحدة التحكّم، يمكنك إضافة مفتاح إلى مشروعك الحالي.
لإعداد هذه الميزة، اتّبِع الخطوات التالية:
- في متصفّح الويب المفضّل لديك، سجِّل الدخول إلى وحدة تحكّم Cloud وأنشِئ مشروع وحدة تحكّم Cloud.
- في IDE، مثل "استوديو Android"، أنشئ مشروعًا لتطوير تطبيقات Android واحتفظ باسم الحزمة.
- يُرجى التواصل مع ممثل "منصة خرائط Google" لمنحك إذن الوصول إلى حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation في مشروعك على Cloud Console.
- أثناء تواجدك في لوحة بيانات Cloud Console في متصفّح الويب، أنشئ بيانات اعتماد لإنشاء مفتاح واجهة برمجة تطبيقات مع قيود.
- في صفحة مفتاح واجهة برمجة التطبيقات، انقر على "تطبيقات Android" في منطقة قيود التطبيقات.
- انقر على إضافة اسم الحزمة والملف المرجعي، ثم أدخِل اسم حزمة مشروع التطوير والملف المرجعي لشهادة SHA-1 لهذا المفتاح.
- انقر على حفظ.
إضافة حزمة Navigation SDK إلى مشروعك
تتوفّر حزمة تطوير البرامج للتنقّل باستخدام Maven أو حزمة AAR. بعد إنشاء مشروع التطوير، يمكنك دمج حزمة تطوير البرامج (SDK) فيه باتّباع إحدى الطرق التالية.
استخدام Maven للإصدار 4.5 والإصدارات الأحدث من حزمة تطوير البرامج للتنقّل (ننصح بذلك)
يستخدم المثال التالي مستودع google()
Maven، وهو أبسط طريقة وأكثرها
يُنصح بها لإضافة حزمة تطوير البرامج Navigation SDK إلى مشروعك.
أضِف الاعتمادية التالية إلى إعدادات Gradle أو Maven، مع استبدال العنصر النائب
VERSION_NUMBER
بإصدار حزمة تطوير البرامج للتنقّل على أجهزة 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>
إذا كانت لديك أي عناصر تابعة تستخدم حزمة تطوير البرامج (SDK) للخرائط، عليك استبعاد العنصر التابع في كل عنصر تابع تم الإعلان عنه ويعتمد على حزمة تطوير البرامج (SDK) للخرائط.
<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 مع حزمة تطوير البرامج للتنقّل قبل الإصدار 4.5 أو مع Driver SDK
ستظل حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation متاحة باستخدام مستودع 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>
إذا كانت لديك أي عناصر تابعة تستخدم حزمة تطوير البرامج (SDK) للخرائط، عليك استبعاد العنصر التابع في كل عنصر تابع تم الإعلان عنه ويعتمد على حزمة تطوير البرامج (SDK) للخرائط.
<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" كبيئة تطوير متكاملة.
نزِّل أحدث إصدار من Navigation SDK من Google Drive المشترَك واستخرِجه. إذا لم يكن لديك إذن الوصول، يُرجى التواصل مع ممثلك.
في Android Studio، افتح مشروعًا وأضِف حزمة خدمات Google Play باستخدام مدير SDK.
من دليل ملف 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، ويُفضّل أيضًا ضبط خيارات التحسين.الإعدادات المطلوبة لحزمة تطوير البرامج للتنقّل
- اضبط قيمة
minSdkVersion
على 23 أو أعلى. - اضبط قيمة
targetSdkVersion
على 30 أو أكثر. - أضِف إعداد
dexOptions
يزيد منjavaMaxHeapSize
. - اضبط الموقع الجغرافي للمكتبات الإضافية.
- أضِف
repositories
وdependencies
إلى حزمة تطوير البرامج للتنقّل. - استبدِل أرقام الإصدارات في التبعيات بأحدث الإصدارات المتاحة.
إعدادات اختيارية لتقليل وقت الإنشاء
- فعِّل تقليص الرموز وتقليص الموارد باستخدام R8/ProGuard لإزالة الرموز والموارد غير المستخدَمة من التبعيات. إذا استغرقت خطوة R8/ProGuard وقتًا طويلاً جدًا، ننصحك بتفعيل التطبيق المتعدد لأغراض التطوير.
- قلِّل عدد ترجمات اللغات المضمّنة في الإصدار: اضبط
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 properties.
لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secrets Gradle لأجهزة Android.
لتثبيت المكوّن الإضافي Secrets Gradle لأجهزة Android في مشروع "خرائط Google"، اتّبِع الخطوات التالية:
-
في Android Studio، افتح ملف
build.gradle.kts
أوbuild.gradle
ذي المستوى الأعلى وأضِف الرمز التالي إلى العنصرdependencies
ضمنbuildscript
.Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
Groovy
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
-
افتح ملف
build.gradle.kts
أوbuild.gradle
على مستوى الوحدة وأضِف الرمز التالي إلى العنصرplugins
.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- في ملف
build.gradle.kts
أوbuild.gradle
على مستوى الوحدة، تأكَّد من ضبط قيمتَيtargetSdk
وcompileSdk
على 34. - مزامنة مشروعك مع Gradle
-
افتح ملف
secrets.properties
في الدليل ذي المستوى الأعلى، ثم أضِف الرمز التالي. استبدِلYOUR_API_KEY
بمفتاح واجهة برمجة التطبيقات. خزِّن المفتاح في هذا الملف لأنّsecrets.properties
مستبعد من إمكانية التحقّق من نظام التحكّم في الإصدار.MAPS_API_KEY=YOUR_API_KEY
-
أنشئ ملف
local.defaults.properties
في الدليل على المستوى الأعلى، أي المجلد نفسه الذي يحتوي على ملفsecrets.properties
، ثم أضِف الرمز التالي.MAPS_API_KEY=DEFAULT_API_KEY
الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات في حال تعذّر العثور على الملف
secrets.properties
، وذلك لضمان عدم تعذّر إنشاء الإصدارات. يمكن أن يحدث ذلك إذا استنسخت التطبيق من نظام التحكّم في الإصدارات الذي يحذفsecrets.properties
ولم تنشئ بعد ملفsecrets.properties
محليًا لتوفير مفتاح واجهة برمجة التطبيقات. -
في ملف
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}" />
ملاحظة:
com.google.android.geo.API_KEY
هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على عدة واجهات برمجة تطبيقات مستندة إلى "خرائط Google" على نظام التشغيل Android، بما في ذلك حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation API لنظام التشغيل Android. للتوافق مع الإصدارات السابقة، تتيح واجهة برمجة التطبيقات أيضًا الاسمcom.google.android.maps.v2.API_KEY
. يتيح هذا الاسم القديم المصادقة على الإصدار 2 من واجهة برمجة التطبيقات "خرائط Google" لنظام التشغيل Android فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً. -
في Android Studio، افتح ملف
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 same folder as the 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 same folder as the 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" }
تضمين الإشارات المطلوبة إلى المصدر في تطبيقك
إذا كنت تستخدم حزمة تطوير البرامج (SDK) الخاصة بخدمة "التنقّل" لنظام التشغيل Android في تطبيقك، عليك تضمين نص تحديد المصدر وتراخيص المصادر المفتوحة كجزء من قسم الإشعارات القانونية في تطبيقك.
يمكنك العثور على نص تحديد المصدر المطلوب وتراخيص البرامج المفتوحة المصدر في ملف zip الخاص بـ "حزمة تطوير البرامج للتنقّل على أجهزة Android" باتّباع الخطوات التالية:
NOTICE.txt
LICENSES.txt