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

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

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

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

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

    گرادل

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

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

    گرادل

    موارد زیر را به 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>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 روی ۲۳ یا بالاتر تنظیم کنید.
    2. targetSdkVersion روی ۳۴ یا بالاتر تنظیم کنید.
    3. یک تنظیم dexOptions اضافه کنید که javaMaxHeapSize را افزایش دهد.
    4. مکان کتابخانه‌های اضافی را تنظیم کنید.
    5. repositories و dependencies مربوط به SDK ناوبری را اضافه کنید.
    6. شماره نسخه‌ها را در وابستگی‌ها با آخرین نسخه‌های موجود جایگزین کنید.

    تنظیمات اختیاری برای کاهش زمان ساخت

    • فعال کردن کاهش کد و کاهش منابع با استفاده از R8/ProGuard برای حذف کد و منابع استفاده نشده از وابستگی‌ها. اگر مرحله R8/ProGuard زمان زیادی برای اجرا می‌برد، فعال کردن multidexing را برای کار توسعه در نظر بگیرید.
    • تعداد ترجمه‌های زبان موجود در ساخت را کاهش دهید: در طول توسعه، resConfigs برای یک زبان تنظیم کنید. برای ساخت نهایی، resConfigs برای زبان‌هایی که واقعاً استفاده می‌کنید تنظیم کنید. به طور پیش‌فرض، Gradle شامل رشته‌های منبع برای همه زبان‌های پشتیبانی شده توسط SDK Navigation است.

    اضافه کردن desugaring برای پشتیبانی از Java8

    • اگر برنامه خود را با استفاده از افزونه Android Gradle نسخه ۴.۰.۰ یا بالاتر می‌سازید، این افزونه پشتیبانی از تعدادی از APIهای زبان جاوا ۸ را گسترش می‌دهد. برای اطلاعات بیشتر به پشتیبانی desugaring جاوا ۸ مراجعه کنید. برای نحوه کامپایل و گزینه‌های وابستگی، به قطعه کد اسکریپت ساخت مثال زیر مراجعه کنید.
    • توصیه می‌کنیم از 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 properties files مراجعه کنید.

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

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

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

    کاتلین 

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

    گرووی 

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. در فایل build.gradle.kts یا build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی ۳۴ تنظیم شده‌اند.
  4. پروژه خود را با Gradle همگام‌سازی کنید .
  5. فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. YOUR_API_KEY با کلید API خود جایگزین کنید. کلید خود را در این فایل ذخیره کنید زیرا secrets.properties از بررسی در سیستم کنترل نسخه مستثنی است.
    MAPS_API_KEY=YOUR_API_KEY

  6. فایل local.defaults.properties را در دایرکتوری سطح بالای خود، همان پوشه‌ای که فایل secrets.properties در آن قرار دارد، ایجاد کنید و سپس کد زیر را اضافه کنید.

    MAPS_API_KEY=DEFAULT_API_KEY

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

  7. در فایل 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 یک استثنا ایجاد می‌کند.

  8. در اندروید استودیو، فایل 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

اگر مشتری خدمات تحویل موتور خودرو یا ناوگان هستید

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