این راهنما الزامات پیکربندی ساخت را برای استفاده از Navigation SDK for Android فهرست میکند. این دستورالعملها فرض میکنند که شما یک Android IDE نصب کردهاید و با توسعه Android آشنا هستید.
حداقل الزامات برای استفاده از کیت توسعه نرمافزار پیمایش
این پیشنیازها برای «کیت توسعه نرمافزار پیمایش برای Android» نسخه ۴.۹۹ و قدیمیتر اعمال میشود.
-
پروژه با Navigation SDK فعالشده. برای تدارک، از نماینده «پلاتفرم Google Maps» خود بپرسید.
برنامهتان باید سطح میانای برنامهسازی کاربردی ۳۰ یا بالاتر را هدفیابی کند.
برای اجرای برنامهای که با Navigation SDK ساخته شده است، دستگاه Android باید خدمات Google Play را نصب و فعال داشته باشد.
نوشتار ارجاع و صدور پروانه باید به برنامه اضافه شود.
راهاندازی پروژهها: پروژه کنسول Cloud و پروژه Android
قبلاز اینکه بتوانید برنامهای بسازید یا آزمایش کنید، باید پروژه کنسول Cloud ایجاد کنید و اطلاعات کاربری کلید API را اضافه کنید. پروژه باید برای دسترسی به کیت توسعه نرمافزار پیمایش، تدارک داشته باشد. به همه کلیدهای موجود در پروژه کنسول Cloud دسترسی یکسانی به Navigation SDK اعطا میشود. یک کلید میتواند بیش از یک پروژه توسعه مرتبط با آن داشته باشد. اگر ازقبل پروژه کنسول دارید، میتوانید کلیدی به پروژه فعلیتان اضافه کنید.
برای راهاندازی
- در مرورگر وب دلخواهتان، به سیستم کنسول Cloud وارد شوید و پروژه کنسول Cloud خود را ایجاد کنید.
- در IDE خود، مانند Android Studio، یک پروژه توسعه برنامه Android ایجاد کنید و نام بسته را یادداشت کنید.
- با نماینده Google Maps Platform خود تماس بگیرید تا دسترسی به Navigation SDK را برای پروژه کنسول Cloud شما فراهم کند.
- وقتی در داشبورد کنسول Cloud در مرورگر وب هستید، اعتبارنامههایی برای تولید کلید میانای API با محدودیت ایجاد کنید.
- در صفحه کلید API، روی برنامههای Android در بخش محدودیتهای برنامه کلیک کنید.
- روی افزودن نام بسته و اثر انگشت کلیک کنید، سپس نام بسته پروژه توسعه و اثر انگشت SHA-1 آن کلید را وارد کنید.
- روی ذخیره کلیک کنید.
افزودن Navigation SDK به پروژه
«کیت توسعه نرمافزار ناوبری» بااستفاده از Maven یا بهعنوان بسته AAR دردسترس است. پساز ایجاد پروژه توسعه، میتوانید بااستفاده از یکی از رویکردهای زیر، کیت توسعه نرمافزار را در آن ادغام کنید.
استفاده از Maven برای کیت توسعه نرمافزار پیمایش نسخه ۴.۵ و جدیدتر (توصیهشده)
در ادامه از مخزن 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>اگر وابستگیهایی دارید که از Maps SDK استفاده میکنند، باید وابستگی را در هر وابستگی اعلامشدهای که به Maps 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 برای Navigation SDK قبلاز نسخه ۴.۵، یا با Driver SDK
کیت توسعه نرمافزار Navigation همچنان بااستفاده از مخزن Maven اصلی در بقیه نسخههای v4 دردسترس است. این همان کتابخانه است
با همان بهروزرسانیهای نسخه بالا، و سازگاری با
«کیت توسعه نرمافزار راننده» و کتابخانههای دیگر را درطول انتقال فراهم میکند.
استفاده از این وابستگی مستلزم ورود به سیستم پروژه ابری بااستفاده از gcloud
هنگام کامپایل کردن است.
- محیط خود را برای دسترسی به مخزن Maven Google همانطور که در بخش پیشنیازها در مستندات Consumer SDK شرح داده شده است راهاندازی کنید. دسترسی به کیت توسعه نرمافزار Navigation ازطریق گروه فضای کاری کنترل میشود.
وابستگی زیر را به پیکربندی 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>اگر وابستگیهایی دارید که از Maps SDK استفاده میکنند، باید وابستگی را در هر وابستگی اعلامشدهای که به Maps 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 بارگیریشده (توصیه نمیشود)
«کیت توسعه نرمافزار پیمایش» بهصورت دسته AAR نیز دردسترس است. پساز ایجاد پروژه توسعه، میتوانید کیت توسعه نرمافزار را ادغام کنید. این دستورالعملها فرض میکنند که از Android Studio برای IDE خود استفاده میکنید.
جدیدترین نسخه «کیت توسعه نرمافزار پیمایش» را از Google Drive مشترک بارگیری و استخراج کنید. اگر دسترسی ندارید، با نمایندهتان تماس بگیرید.
در Android Studio، پروژهای را باز کنید و بااستفاده از مدیر SDK، بسته خدمات Google Play را اضافه کنید.
از فهرست راهنمای فایل 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 Scripts، فایل
local.propertiesرا باز کنید وandroid.useDeprecatedNdk=trueرا اضافه کنید.
بهروزرسانی اسکریپت ساخت Gradle
فایل
build.gradle (Module:app)را باز کنید و از دستورالعملهای زیر استفاده کنید تا تنظیمات را بهروز کنید تا الزامات Navigation SDK را برآورده کند و همچنین گزینههای بهینهسازی را نیز تنظیم کنید.تنظیمات لازم برای کیت توسعه نرمافزار ناوبری
-
minSdkVersionرا روی ۲۳ یا بالاتر تنظیم کنید. targetSdkVersionرا روی ۳۰ یا بیشتر تنظیم کنید.- تنظیم
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 در دایرکتوری ریشه پروژهتان ذخیره کنید و آن فایل را از کنترل نسخه مستثنی کنید. برای اطلاعات بیشتر درباره
فایلهای ویژگیهای Gradle، به
فایلهای ویژگیهای Gradle مراجعه کنید.
برای ساده کردن این کار، توصیه میکنیم از افزایه Secrets Gradle ویژه Android استفاده کنید.
برای نصب افزایه Secrets Gradle ویژه Android و ذخیره کلید میانای برنامهسازی کاربردی:
-
در Android Studio، فایل سطح بالای
build.gradle.ktsیاbuild.gradleرا باز کنید و کد زیر را به بلوکpluginsاضافه کنید.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false }
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false }
-
فایل
build.gradle.ktsیاbuild.gradleدر سطح ماژول را باز کنید و کد زیر را به عنصرpluginsاضافه کنید.Kotlin
plugins { id("com.android.application") // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Groovy
plugins { id 'com.android.application' // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- اگر از «استودیو Android» استفاده میکنید، پروژهتان را با Gradle همگامسازی کنید.
-
فایل
secrets.propertiesرا در دایرکتوری سطح بالا باز کنید، سپس کد زیر را اضافه کنید.YOUR_API_KEYرا با کلید میانای API خودتان جایگزین کنید. حتماًsecrets.propertiesرا به فایل.gitignoreخود اضافه کنید (یا بهنحوی آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید میانای برنامهسازی کاربردی خود را در کنترل نسخه بررسی نکنید.MAPS_API_KEY=YOUR_API_KEY
-
فایل
local.defaults.propertiesرا در دایرکتوری سطح بالا، همان پوشه فایلsecrets.properties، ایجاد کنید و سپس کد زیر را اضافه کنید.MAPS_API_KEY=DEFAULT_API_KEY
هدف این فایل ارائه مکان پشتیبانگیری برای کلید میانای برنامهسازی کاربردی است تا اگر فایل
secrets.propertiesپیدا نشد، ساختها ناموفق نباشند. این مشکل زمانی رخ میدهد که برنامه را از سیستم کنترل نسخهای شبیهسازی کنید کهsecrets.propertiesرا حذف میکند و هنوز فایلsecrets.propertiesرا بهصورت محلی برای ارائه کلید میانای برنامهسازی کاربردی خود ایجاد نکردهاید. -
میتوانید کلید میانای API را به فایل
AndroidManifest.xmlخود اضافه کنید یا کلید میانای API را بهصورت برنامهنویسیشده ارائه دهید.- کلید میانای برنامهسازی کاربردی خود را به
AndroidManifest.xmlاضافه کنید:<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />توجه:
com.google.android.geo.API_KEYنام فراداده توصیهشده برای کلید میانای API است. از کلیدی با این نام میتوان برای اصالتسنجی در چندین میانای برنامهسازی کاربردی مبتنی بر Google Maps در پلاتفرم Android، ازجمله Navigation SDK for Android، استفاده کرد. برای سازگاری با نسخههای قدیمی، این میانای برنامهسازی کاربردی از نامcom.google.android.maps.v2.API_KEYنیز پشتیبانی میکند. این نام قدیمی فقط امکان اصالتسنجی در Android Maps API v2 را فراهم میکند. برنامه فقط میتواند یکی از نامهای فراداده کلید میانای برنامهسازی کاربردی را مشخص کند. اگر هر دو مشخص شده باشند، API استثنایی را ایجاد میکند. - کلید میانای برنامهسازی کاربردی را بهطور برنامهریزیشده ارائه دهید:
افزونه Secrets Gradle کلید را در کلاس
BuildConfigدردسترس قرار میدهد. در مقداردهی اولیه برنامهتان (برای مثال، در روشApplication.onCreate())، روش را بهصورت زیر فراخوانی کنید:Kotlin
- عبارتهای وارد کردن زیر را اضافه کنید:
import com.google.android.libraries.navigation.NavigationApi
- موارد زیر را به روش
Application.onCreate()خود اضافه کنید:NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)
جاوا
- عبارتهای وارد کردن زیر را اضافه کنید:
import com.google.android.libraries.navigation.NavigationApi;
- موارد زیر را به روش
Application.onCreate()خود اضافه کنید:NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
توجه: هنگام استفاده ازsetApiKey()، موارد زیر را بهخاطر داشته باشید:- کلید میانای برنامهسازی کاربردی غیرتهی و غیرخالی ارائه دهید.
setApiKey()را فقط یکبار درطول عمر برنامهتان فراخوانی کنید. اگر این روش بیشاز یک بار فراخوانی شود،IllegalStateExceptionرا برمیگرداند.- پیشاز مقداردهی اولیه هر مؤلفه دیگر Navigation SDK، مانند
Navigator، باsetApiKey()تماس بگیرید. - کلیدی که با این روش ارائه میدهید، هر کلید میانای API را در
AndroidManifest.xmlشما لغو میکند. - از «کیت توسعه نرمافزار ناوبری» نسخه ۷.۶ یا بالاتر استفاده کنید.
- عبارتهای وارد کردن زیر را اضافه کنید:
- کلید میانای برنامهسازی کاربردی خود را به
-
در 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 root directory (the same folder as the root 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 root directory (the same folder as the root 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" }
ارجاعهای لازم را در برنامهتان بگنجانید
اگر از «کیت توسعه نرمافزار ناوبری» برای Android در برنامهتان استفاده میکنید، باید نوشتار انتساب و پروانههای متنباز را بهعنوان بخشی از بخش ابلاغیههای حقوقی برنامهتان اضافه کنید.
میتوانید نوشتار انتساب و پروانههای متنباز موردنیاز را در فایل zip «کیت توسعه نرمافزار پیمایش برای Android» پیدا کنید:
NOTICE.txtLICENSES.txt