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

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

افزودن Navigation SDK به پروژه

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

توجه: این روش با برخی‌از کتابخانه‌هایی که ازطریق شناسه آرتیفکت قبلی به Navigation SDK وابسته هستند ناسازگار است. این شامل نسخه‌های Driver SDK نسخه ۴.۴ یا قدیمی‌تر می‌شود.

1. وابستگی زیر را به پیکربندی Gradle یا Maven خود اضافه کنید، و جای‌بان VERSION_NUMBER را با نسخه موردنظر «کیت توسعه نرم‌افزار ناوبری» برای Android جایگزین کنید.

   Gradle

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

   dependencies {
           ...
           implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
   }
   

   Maven

   مورد زیر را به pom.xml اضافه کنید:

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.libraries.navigation</groupId>
       <artifactId>navigation</artifactId>
       <version>VERSION_NUMBER</version>
     </dependency>
   </dependencies>
   

   توجه: اگر مشتری «خدمات جابه‌جایی» هستید که از مخزن Maven خصوصی اصلی ارتقا می‌دهید، توجه داشته باشید که نام‌های گروه و مصنوع تغییر کرده‌اند و افزونه com.google.cloud.artifactregistry.gradle-plugin دیگر لازم نیست.

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

   Gradle

   موارد زیر را به 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>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 را برآورده کنید و همچنین تنظیم گزینه‌های بهینه‌سازی را نیز درنظر بگیرید.

  تنظیمات لازم برای کیت توسعه نرم‌افزار ناوبری

  1. minSdkVersion را روی ۲۴ یا بالاتر تنظیم کنید.
  2. targetSdkVersion را روی ۳۶ یا بیشتر تنظیم کنید.
  3. تنظیم dexOptions را اضافه کنید که javaMaxHeapSize را افزایش می‌دهد.
  4. مکان کتابخانه‌های تکمیلی را تنظیم کنید.
  5. repositories و dependencies را برای کیت توسعه نرم‌افزار ناوبری اضافه کنید.
  6. شماره‌های نسخه را در وابستگی‌ها با جدیدترین نسخه‌های دردسترس جایگزین کنید.

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

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

  افزودن شکرزدایی برای پشتیبانی از Java8

  • اگر برنامه‌تان را بااستفاده از افزونه Android Gradle نسخه ۴.۰.۰ یا بالاتر می‌سازید، این افزونه پشتیبانی از استفاده از تعدادی از میاناهای برنامه‌سازی کاربردی زبان Java 8 را گسترش می‌دهد. برای اطلاعات بیشتر، به پشتیبانی شکرزدایی Java 8 مراجعه کنید. برای اطلاع از نحوه گزینه‌های کامپایل و وابستگی، قطعه اسکریپت ساخت نمونه زیر را ببینید.
  • از نسخه‌های Gradle، افزونه Android Gradle‏ (AGP)، و کتابخانه Desugar که با نسخه Navigation SDK شما مطابقت دارد استفاده کنید. جدول زیر را ببینید.
  • کتابخانه Desugar باید برای واحد app و هر واحدی که مستقیماً به Navigation SDK وابسته است فعال شود.

جدول زیر نسخه‌های کتابخانه Gradle،‏ AGP، و Desugar را که برای هر نسخه از Navigation SDK لازم است فهرست می‌کند.

نسخه کیت توسعه نرم‌افزار پیمایش	نسخه Gradle	نسخه AGP	کتابخانه Desugar
‫۸.۰.۰ و بالاتر	9.1.0	9.0.1	com.android.tools:desugar_jdk_libs_nio:2.1.5
‫۷.۷.۰ تا ۷.۹.۰	۸.۱۳	8.13.2	com.android.tools:desugar_jdk_libs_nio:2.1.5
‫۷.۳.۰ تا ۷.۶.۰	8.11.1	8.10.0	com.android.tools:desugar_jdk_libs_nio:2.0.3

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

کلید میانای برنامه‌سازی کاربردی را به برنامه‌تان اضافه کنید

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

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

برای نصب افزایه Secrets Gradle ویژه Android و ذخیره کلید میانای برنامه‌سازی کاربردی:

1. در 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
   }

2. فایل 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'
   }

3. اگر از «استودیو Android» استفاده می‌کنید، پروژه‌تان را با Gradle همگام‌سازی کنید.
4. فایل secrets.properties را در دایرکتوری سطح بالا باز کنید، سپس کد زیر را اضافه کنید. YOUR_API_KEY را با کلید میانای API خودتان جایگزین کنید. حتماً secrets.properties را به فایل .gitignore خود اضافه کنید (یا به‌نحوی آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید میانای برنامه‌سازی کاربردی خود را در کنترل نسخه بررسی نکنید.
   توجه: اگر فایل secrets.properties وجود ندارد، آن را در همان پوشه فایل local.properties ایجاد کنید.

   MAPS_API_KEY=YOUR_API_KEY

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

   توجه: کد را همان‌طور که نشان داده شده است وارد کنید. DEFAULT_API_KEY را با کلید میانای API خودتان جایگزین نکنید.

   MAPS_API_KEY=DEFAULT_API_KEY

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

6. می‌توانید کلید میانای 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

     1. عبارت‌های وارد کردن زیر را اضافه کنید:

        import com.google.android.libraries.navigation.NavigationApi

     2. موارد زیر را به روش Application.onCreate() خود اضافه کنید:

        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

     جاوا

     1. عبارت‌های وارد کردن زیر را اضافه کنید:

        import com.google.android.libraries.navigation.NavigationApi;

     2. موارد زیر را به روش Application.onCreate() خود اضافه کنید:

        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);

     توجه: هنگام استفاده از setApiKey()، موارد زیر را به‌خاطر داشته باشید:

     • کلید میانای برنامه‌سازی کاربردی غیرتهی و غیرخالی ارائه دهید.
     • setApiKey() را فقط یک‌بار درطول عمر برنامه‌تان فراخوانی کنید. اگر این روش بیش‌از یک بار فراخوانی شود، IllegalStateException را برمی‌گرداند.
     • پیش‌از مقداردهی اولیه هر مؤلفه دیگر Navigation SDK، مانند Navigator، با setApiKey() تماس بگیرید.
     • کلیدی که با این روش ارائه می‌دهید، هر کلید میانای API را در AndroidManifest.xml شما لغو می‌کند.
     • از «کیت توسعه نرم‌افزار ناوبری» نسخه ۷.۶ یا بالاتر استفاده کنید.

7. در 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.txt
• LICENSES.txt

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

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

وابستگی‌های دستی (غیر Gradle/Maven)

اگر سیستم ساخت شما وابستگی‌های انتقالی را حل نمی‌کند (مانند Bazel)، یا اگر AAR را به‌صورت دستی ادغام می‌کنید، باید این وابستگی‌ها را به پروژه خود اضافه کنید. Gradle و Maven آن‌ها را به‌طور خودکار حل‌وفصل می‌کنند.

• androidx.datastore:datastore-core
• androidx.datastore:datastore-guava
• com.google.guava:listenablefuture
• androidx.concurrent:concurrent-futures