این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

پروژه خود را راه اندازی کنید -- نسخه 4.99 و قبل از آن

این راهنما، الزامات پیکربندی ساخت برای استفاده از SDK ناوبری برای اندروید را فهرست می‌کند. این دستورالعمل‌ها فرض می‌کنند که شما یک IDE اندروید نصب کرده‌اید و با توسعه اندروید آشنا هستید.

حداقل الزامات برای استفاده از Navigation SDK

این الزامات برای Navigation SDK برای اندروید نسخه ۴.۹۹ و قبل از آن اعمال می‌شود.

یک کنسول ابری گوگل
پروژه‌ای که Navigation SDK در آن فعال است. برای تهیه‌ی اطلاعات، از نماینده‌ی پلتفرم نقشه‌های گوگل خود سوال کنید.
برنامه شما باید سطح API 30 یا بالاتر را هدف قرار دهد.
برای اجرای برنامه‌ای که با استفاده از Navigation SDK ساخته شده است، دستگاه اندروید باید سرویس‌های Google Play را نصب و فعال کرده باشد.
متن مربوط به مجوزها و اسناد باید به برنامه اضافه شود.

پروژه‌های خود را تنظیم کنید: پروژه کنسول ابری و پروژه اندروید

قبل از اینکه بتوانید یک برنامه بسازید یا آزمایش کنید، باید یک پروژه کنسول ابری ایجاد کنید و اعتبارنامه‌های کلید API را اضافه کنید. این پروژه باید برای دسترسی به SDK ناوبری، مجوز داشته باشد. به همه کلیدهای درون پروژه کنسول ابری، دسترسی یکسانی به SDK ناوبری اعطا می‌شود. یک کلید می‌تواند بیش از یک پروژه توسعه مرتبط با آن داشته باشد. اگر از قبل یک پروژه کنسول دارید، می‌توانید یک کلید به پروژه فعلی خود اضافه کنید.

برای تنظیم

در مرورگر وب مورد علاقه خود، وارد کنسول Cloud شوید و پروژه کنسول Cloud خود را ایجاد کنید.
در IDE خود، مانند اندروید استودیو، یک پروژه توسعه اپلیکیشن اندروید ایجاد کنید و نام بسته را یادداشت کنید.
برای دسترسی به Navigation SDK برای پروژه کنسول ابری خود، با نماینده پلتفرم نقشه‌های گوگل خود تماس بگیرید.
در حالی که در داشبورد کنسول ابری در مرورگر وب خود هستید، اعتبارنامه‌هایی را برای ایجاد یک کلید API با محدودیت‌ها ایجاد کنید.
در صفحه کلید API ، در قسمت محدودیت‌های برنامه ، روی برنامه‌های اندروید کلیک کنید.
روی «افزودن نام بسته و اثر انگشت» کلیک کنید و سپس نام بسته پروژه توسعه خود و اثر انگشت SHA-1 را برای آن کلید وارد کنید.
روی ذخیره کلیک کنید.

کیت توسعه نرم‌افزار ناوبری (Navigation SDK) را به پروژه خود اضافه کنید.

کیت توسعه نرم‌افزار ناوبری (Navigation SDK) با استفاده از Maven یا به عنوان یک بسته AAR در دسترس است. پس از ایجاد پروژه توسعه خود، می‌توانید SDK را با استفاده از یکی از رویکردهای زیر در آن ادغام کنید.

استفاده از Maven برای Navigation SDK نسخه ۴.۵ و بالاتر (توصیه می‌شود)

کد زیر از مخزن google() Maven استفاده می‌کند که ساده‌ترین و توصیه‌شده‌ترین روش برای افزودن Navigation SDK به پروژه شماست.

وابستگی زیر را به پیکربندی Gradle یا Maven خود اضافه کنید و به جای نسخه Navigation SDK برای اندروید، عبارت VERSION_NUMBER قرار دهید.

گرادل

موارد زیر را به 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'
       }
}
}

ماون

موارد زیر را به 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 SDK) همچنان با استفاده از مخزن اصلی Maven در بقیه نسخه‌های v4 در دسترس است. این همان کتابخانه با تمام به‌روزرسانی‌های مشابه نسخه بالا است و در طول انتقال با کیت توسعه نرم‌افزار درایور (Driver SDK) و سایر کتابخانه‌ها سازگاری دارد. استفاده از این وابستگی مستلزم ورود به پروژه ابری شما با استفاده از gcloud هنگام کامپایل است.

محیط خود را برای دسترسی به مخزن Maven گوگل، همانطور که در بخش پیش‌نیازها در مستندات Consumer SDK توضیح داده شده است، تنظیم کنید. دسترسی به Navigation SDK از طریق یک گروه فضای کاری کنترل می‌شود.

وابستگی زیر را به پیکربندی Gradle یا Maven خود اضافه کنید و به جای نسخه Navigation SDK، عبارت VERSION_NUMBER قرار دهید.

گرادل

موارد زیر را به 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'
        }
}
}

ماون

موارد زیر را به 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 را ادغام کنید. این دستورالعمل‌ها فرض را بر استفاده از اندروید استودیو برای IDE شما قرار می‌دهند.

آخرین نسخه Navigation SDK را از گوگل درایو مشترک دانلود و استخراج کنید. اگر دسترسی ندارید، با نماینده خود تماس بگیرید.
در اندروید استودیو ، یک پروژه باز کنید و بسته سرویس‌های گوگل پلی را با استفاده از SDK Manager اضافه کنید.
از دایرکتوری فایل زیپ، 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 استفاده کنید و تنظیم گزینه‌های بهینه‌سازی را نیز در نظر بگیرید.
تنظیمات مورد نیاز برای Navigation SDK
1. minSdkVersion روی ۲۳ یا بالاتر تنظیم کنید.
2. targetSdkVersion روی 30 یا بالاتر تنظیم کنید.
3. یک تنظیم dexOptions اضافه کنید که javaMaxHeapSize را افزایش دهد.
4. مکان کتابخانه‌های اضافی را تنظیم کنید.
5. repositories و dependencies مربوط به SDK ناوبری را اضافه کنید.
6. شماره نسخه‌ها را در وابستگی‌ها با آخرین نسخه‌های موجود جایگزین کنید.
تنظیمات اختیاری برای کاهش زمان ساخت
- فعال کردن کاهش کد و کاهش منابع با استفاده از R8/ProGuard برای حذف کد و منابع استفاده نشده از وابستگی‌ها. اگر مرحله R8/ProGuard زمان زیادی برای اجرا می‌برد، فعال کردن multidexing را برای کار توسعه در نظر بگیرید.
- تعداد ترجمه‌های زبان موجود در ساخت را کاهش دهید: در طول توسعه، resConfigs برای یک زبان تنظیم کنید. برای ساخت نهایی، resConfigs برای زبان‌هایی که واقعاً استفاده می‌کنید تنظیم کنید. به طور پیش‌فرض، Gradle شامل رشته‌های منبع برای همه زبان‌های پشتیبانی شده توسط SDK Navigation است.

در زیر نمونه‌ای از اسکریپت ساخت 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'
}

کلید API را به برنامه خود اضافه کنید

این بخش نحوه ذخیره کلید API شما را توضیح می‌دهد تا برنامه شما بتواند به طور ایمن به آن مراجعه کند. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید، بنابراین توصیه می‌کنیم آن را در فایل secrets.properties که در دایرکتوری ریشه پروژه شما قرار دارد، ذخیره کنید. برای اطلاعات بیشتر در مورد فایل secrets.properties ، به Gradle properties files مراجعه کنید.

برای ساده‌سازی این کار، توصیه می‌کنیم از افزونه Secrets Gradle برای اندروید استفاده کنید.

برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps خود:

در اندروید استودیو، فایل سطح بالای build.gradle.kts یا build.gradle خود را باز کنید و کد زیر را به عنصر dependencies در زیر buildscript اضافه کنید.

کاتلین

plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.jetbrains.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.secrets.gradle.plugin) apply false
}

گرووی

buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}

فایل build.gradle.kts یا build.gradle سطح ماژول خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

کاتلین

plugins {
    // ...
    alias(libs.plugins.secrets.gradle.plugin)
}

گرووی

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

در فایل build.gradle.kts یا build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی ۳۴ تنظیم شده‌اند.
پروژه خود را با Gradle همگام‌سازی کنید .
فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. YOUR_API_KEY با کلید API خود جایگزین کنید. کلید خود را در این فایل ذخیره کنید زیرا secrets.properties از بررسی در سیستم کنترل نسخه مستثنی است.
نکته: اگر فایل secrets.properties وجود ندارد، آن را در همان پوشه‌ای که فایل local.properties قرار دارد، ایجاد کنید.
```
MAPS_API_KEY=YOUR_API_KEY
```
فایل local.defaults.properties را در دایرکتوری سطح بالای خود، همان پوشه‌ای که فایل secrets.properties در آن قرار دارد، ایجاد کنید و سپس کد زیر را اضافه کنید.
توجه: کد را همانطور که نشان داده شده است وارد کنید. DEFAULT_API_KEY با کلید API خود جایگزین نکنید.
```
MAPS_API_KEY=DEFAULT_API_KEY
```
هدف از این فایل، فراهم کردن یک مکان پشتیبان برای کلید API در صورت عدم یافتن فایل secrets.properties است تا ساخت‌ها با شکست مواجه نشوند. این اتفاق زمانی می‌افتد که شما برنامه را از یک سیستم کنترل نسخه که secrets.properties حذف کرده است، کلون کنید و هنوز فایل secrets.properties را به صورت محلی برای ارائه کلید API خود ایجاد نکرده باشید.
در فایل 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 نام فراداده پیشنهادی برای کلید API است. کلیدی با این نام می‌تواند برای احراز هویت در چندین API مبتنی بر نقشه‌های گوگل در پلتفرم اندروید، از جمله Navigation SDK برای اندروید، استفاده شود. برای سازگاری با نسخه‌های قبلی، API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی، احراز هویت را فقط برای Android Maps API v2 امکان‌پذیر می‌کند. یک برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شوند، API یک استثنا ایجاد می‌کند.

در اندروید استودیو، فایل build.gradle.kts یا build.gradle در سطح ماژول خود را باز کنید و ویژگی secrets را ویرایش کنید. اگر ویژگی secrets وجود ندارد، آن را اضافه کنید.

ویژگی‌های افزونه را ویرایش کنید تا propertiesFileName روی secrets.properties ، defaultPropertiesFileName روی local.defaults.properties و سایر ویژگی‌ها تنظیم کنید.

کاتلین

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

گرووی

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

ویژگی‌های مورد نیاز را در برنامه خود بگنجانید

اگر از کیت توسعه نرم‌افزار ناوبری اندروید (Navigation SDK) در برنامه خود استفاده می‌کنید، باید متن ارجاع و مجوزهای متن‌باز را به عنوان بخشی از بخش اطلاعیه‌های قانونی برنامه خود درج کنید.

می‌توانید متن ارجاع مورد نیاز و مجوزهای متن‌باز را در فایل زیپ Navigation SDK for Android پیدا کنید:

NOTICE.txt
LICENSES.txt

پروژه خود را راه اندازی کنید -- نسخه 4.99 و قبل از آن با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

حداقل الزامات برای استفاده از Navigation SDK

پروژه‌های خود را تنظیم کنید: پروژه کنسول ابری و پروژه اندروید

کیت توسعه نرم‌افزار ناوبری (Navigation SDK) را به پروژه خود اضافه کنید.

استفاده از Maven برای Navigation SDK نسخه ۴.۵ و بالاتر (توصیه می‌شود)

گرادل

ماون

از Maven برای Navigation SDK نسخه‌های قبل از نسخه ۴.۵ یا با Driver SDK استفاده کنید.

گرادل

ماون

از یک بسته AAR دانلود شده استفاده کنید (توصیه نمی‌شود)

پیکربندی ساخت

به‌روزرسانی ویژگی‌های محلی

اسکریپت ساخت Gradle را به‌روزرسانی کنید

کلید API را به برنامه خود اضافه کنید

کاتلین

گرووی

کاتلین

گرووی

کاتلین

گرووی

ویژگی‌های مورد نیاز را در برنامه خود بگنجانید

پروژه خود را راه اندازی کنید -- نسخه 4.99 و قبل از آن