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

پروژه Android Studio خود را راه اندازی کنید

این صفحه نحوه ادغام Navigation SDK را در پروژه توسعه خود توضیح می دهد.

Navigation SDK را به پروژه خود اضافه کنید

Navigation SDK از طریق Google Maven Repository در دسترس است. می‌توانید با استفاده از پیکربندی Gradle build.gradle یا Maven pom.xml SDK را به پروژه خود اضافه کنید.

وابستگی زیر را به پیکربندی Gradle یا Maven خود اضافه کنید و جای جای VERSION_NUMBER را جایگزین نسخه دلخواه Navigation SDK برای Android کنید.
گریدل
موارد زیر را به build.gradle در سطح ماژول خود اضافه کنید:
```
dependencies {
        ...
        implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
}
```
ماون
موارد زیر را به pom.xml خود اضافه کنید:
```
<dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.navigation</groupId>
    <artifactId>navigation</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>
```
توجه: اگر مشتری Mobility Services هستید که از مخزن خصوصی اصلی Maven ارتقا می‌دهید، توجه داشته باشید که نام گروه و مصنوع تغییر کرده است و com.google.cloud.artifactregistry.gradle-plugin دیگر لازم نیست.

اگر وابستگی‌هایی دارید که از Maps SDK استفاده می‌کنند، باید وابستگی را در هر وابستگی اعلام‌شده که به Maps SDK متکی است حذف کنید.

گریدل

موارد زیر را به build.gradle سطح بالای خود اضافه کنید:

allprojects {
        ...
        // Required: you must exclude the Google Play service Maps SDK from
        // your transitive dependencies. This is to ensure 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>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 Scripts ، فایل local.properties را باز کنید و android.useDeprecatedNdk=true را اضافه کنید.

ویژگی های gradle را به روز کنید

در پوشه Gradle Scripts ، فایل gradle.properties را باز کنید و اگر قبلاً موجود نیست، موارد زیر را اضافه کنید:
1. android.useAndroidX=true
2. android.enableJetifier=true

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

فایل build.gradle (Module:app) را باز کنید و از دستورالعمل‌های زیر برای به‌روزرسانی تنظیمات برای برآورده کردن الزامات Navigation SDK استفاده کنید و گزینه‌های بهینه‌سازی را نیز در نظر بگیرید.
تنظیمات لازم برای Navigation SDK
1. minSdkVersion روی 23 یا بالاتر تنظیم کنید.
2. targetSdkVersion روی 34 یا بالاتر تنظیم کنید.
3. یک تنظیم dexOptions اضافه کنید که javaMaxHeapSize را افزایش می دهد.
4. مکان را برای کتابخانه های اضافی تنظیم کنید.
5. repositories و dependencies را برای Navigation SDK اضافه کنید.
6. شماره نسخه های موجود در وابستگی ها را با آخرین نسخه های موجود جایگزین کنید.
تنظیمات اختیاری برای کاهش زمان ساخت
- برای حذف کد و منابع استفاده نشده از وابستگی ها ، کوچک کردن کد و کوچک شدن منابع را با استفاده از R8/ProGuard فعال کنید. اگر مرحله R8/ProGuard برای اجرا زمان زیادی می برد، فعال کردن Multidex برای کار توسعه را در نظر بگیرید.
- کاهش تعداد ترجمه‌های زبان موجود در ساخت: resConfigs برای یک زبان در طول توسعه تنظیم کنید. برای ساخت نهایی، resConfigs برای زبان هایی که واقعا استفاده می کنید تنظیم کنید. به‌طور پیش‌فرض، Gradle شامل رشته‌های منبع برای همه زبان‌هایی است که توسط Navigation SDK پشتیبانی می‌شوند.
برای پشتیبانی از Java8، desugaring را اضافه کنید
- اگر برنامه خود را با استفاده از پلاگین Android Gradle نسخه 4.0.0 یا بالاتر می‌سازید، این افزونه از تعدادی API زبان جاوا 8 پشتیبانی می‌کند. برای اطلاعات بیشتر به پشتیبانی از قند زدایی جاوا 8 مراجعه کنید. برای نحوه کامپایل و گزینه‌های وابستگی، نمونه قطعه اسکریپت ساخت را در زیر ببینید.
- توصیه می کنیم از Gradle 8.4، افزونه Android Gradle نسخه 8.3.0 و کتابخانه Desugar com.android.tools:desugar_jdk_libs_nio:2.0.3 استفاده کنید. این تنظیمات با Navigation SDK برای اندروید نسخه 6.0.0 و بالاتر سازگار است.
- کتابخانه Desugar باید برای ماژول app و هر ماژولی که مستقیماً به 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.0.3'
}

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

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

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

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

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

کاتلین

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

شیار

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

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

کاتلین

plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

شیار

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

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

در Android Studio، فایل 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"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

شیار

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"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

اسناد مورد نیاز را در برنامه خود قرار دهید

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

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

NOTICE.txt
LICENSES.txt

اگر مشتری Mobility یا Fleet Engine Deliveries هستید

اگر مشتری Mobility یا Fleet Engine Deliveries هستید، در مورد صورتحساب در مستندات Mobility اطلاعات کسب کنید. برای اطلاعات بیشتر درباره ثبت تراکنش‌ها، به تنظیم صورت‌حساب ، ثبت تراکنش‌های قابل پرداخت ، گزارش‌دهی ، و ثبت تراکنش‌های قابل پرداخت (Android) مراجعه کنید.