Navigation SDK در حال حاضر فقط برای مشتریان منتخب در دسترس است. برای کسب اطلاعات بیشتر با واحد فروش تماس بگیرید .

طراحی نقشه جدید به زودی به پلتفرم نقشه های گوگل ارائه می شود. این به‌روزرسانی برای استایل نقشه شامل یک پالت رنگ پیش‌فرض جدید و بهبودهایی در تجربیات نقشه و قابلیت استفاده است. همه سبک‌های نقشه به‌طور خودکار در مارس 2025 به‌روزرسانی می‌شوند. برای اطلاعات بیشتر در مورد در دسترس بودن و نحوه انتخاب زودتر، به سبک نقشه جدید برای پلتفرم Google Maps مراجعه کنید.

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

پروژه خود را تنظیم کنید

این راهنما الزامات پیکربندی ساخت را برای استفاده از Navigation SDK برای اندروید نسخه 5.0.0 و بالاتر فهرست می‌کند.

دستورالعمل ها فرض می کنند که شما یک Android IDE نصب کرده اید و با توسعه اندروید آشنا هستید.

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

این الزامات برای Navigation SDK برای نسخه‌های Android 5.0.0 و بالاتر اعمال می‌شود.

یک پروژه Google Cloud Console با فعال کردن Navigation SDK. برای تهیه، از نماینده پلتفرم Google Maps خود بپرسید.
برنامه شما باید نسخه های اندروید را به صورت زیر مشخص کند:
- نسخه هدف باید اندروید 13 (سطح API 33) یا بالاتر باشد.
- حداقل نسخه باید اندروید 6 (سطح API 23) یا بالاتر باشد.
برای اجرای یک برنامه ساخته شده با Navigation SDK، دستگاه Android باید شرایط زیر را داشته باشد:
- خدمات Google Play نصب و فعال شد.
- 2 گیگابایت رم یا بیشتر.
- پشتیبانی از OpenGL ES 2.0 مستندات سازگاری Android 6.0 منبع باز Android را برای شتاب گرافیک دو بعدی و سه بعدی ببینید
اسناد و متن مجوز باید به برنامه اضافه شود.

پروژه های خود را راه اندازی کنید: پروژه Cloud Console و پروژه Android

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

برای راه اندازی

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

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

Navigation SDK از طریق Maven در دسترس است. پس از ایجاد پروژه توسعه خود، می توانید SDK را با استفاده از یکی از روش های زیر در آن ادغام کنید.

استفاده از Maven برای Navigation SDK نسخه 4.5 و جدیدتر (توصیه می شود)

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

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

گریدل

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

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

پس از ایجاد پروژه، می توانید تنظیمات را برای ساخت و استفاده موفق از Navigation SDK پیکربندی کنید.

ویژگی های محلی را به روز کنید

در پوشه Gradle Scripts ، فایل local.properties را باز کنید و android.useDeprecatedNdk=true را اضافه کنید.

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

فایل build.gradle (Module:app) را باز کنید و از دستورالعمل‌های زیر برای به‌روزرسانی تنظیمات برای برآورده کردن الزامات Navigation SDK استفاده کنید و گزینه‌های بهینه‌سازی را نیز در نظر بگیرید.
تنظیمات لازم برای Navigation SDK
1. minSdkVersion را روی 23 یا بالاتر تنظیم کنید.
2. targetSdkVersion را روی 33 یا بالاتر تنظیم کنید.
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 برای اپلیکیشن آورده شده است. برنامه‌های نمونه را برای مجموعه‌های به‌روزرسانی شده وابستگی‌ها بررسی کنید، زیرا نسخه 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 33
        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:1.1.9'
}

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

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

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

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

در Android Studio، فایل build.gradle یا build.gradle.kts سطح بالای خود را باز کنید و کد زیر را به عنصر 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 سطح ماژول خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

شیار

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

کاتلین

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

در فایل build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی 34 تنظیم شده اند.
فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزین YOUR_API_KEY کنید. کلید خود را در این فایل ذخیره کنید زیرا 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}" />
```
Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Navigation SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

Groovy

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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 {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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) مراجعه کنید.