راه‌اندازی پروژه -- نسخه ۴.۹۹ و قدیمی‌تر

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

حداقل الزامات برای استفاده از کیت توسعه نرم‌افزار پیمایش

این پیش‌نیازها برای «کیت توسعه نرم‌افزار پیمایش برای Android» نسخه ۴.۹۹ و قدیمی‌تر اعمال می‌شود.

  • کنسول Google Cloud

    پروژه با Navigation SDK فعال‌شده. برای تدارک، از نماینده «پلاتفرم Google Maps» خود بپرسید.

  • برنامه‌تان باید سطح میانای برنامه‌سازی کاربردی ۳۰ یا بالاتر را هدف‌یابی کند.

  • برای اجرای برنامه‌ای که با Navigation SDK ساخته شده است، دستگاه Android باید خدمات Google Play را نصب و فعال داشته باشد.

  • نوشتار ارجاع و صدور پروانه باید به برنامه اضافه شود.

راه‌اندازی پروژه‌ها: پروژه کنسول Cloud و پروژه Android

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

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

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

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

«کیت توسعه نرم‌افزار ناوبری» بااستفاده از Maven یا به‌عنوان بسته AAR دردسترس است. پس‌از ایجاد پروژه توسعه، می‌توانید بااستفاده از یکی از رویکردهای زیر، کیت توسعه نرم‌افزار را در آن ادغام کنید.

استفاده از Maven برای کیت توسعه نرم‌افزار پیمایش نسخه ۴.۵ و جدیدتر (توصیه‌شده)

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

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

    Gradle

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

    Maven

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

  1. محیط خود را برای دسترسی به مخزن Maven Google همان‌طور که در بخش پیش‌نیازها در مستندات Consumer SDK شرح داده شده است راه‌اندازی کنید. دسترسی به کیت توسعه نرم‌افزار Navigation ازطریق گروه فضای کاری کنترل می‌شود.
  2. وابستگی زیر را به پیکربندی Gradle یا Maven خود اضافه کنید، و جای‌بان VERSION_NUMBER را با نسخه Navigation SDK جایگزین کنید.

    Gradle

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

    Maven

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

    <dependencies>
    ...
    <dependency>
         <groupId>com.google.android.maps</groupId>
         <artifactId>navsdk</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>
    

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

«کیت توسعه نرم‌افزار پیمایش» به‌صورت دسته AAR نیز دردسترس است. پس‌از ایجاد پروژه توسعه، می‌توانید کیت توسعه نرم‌افزار را ادغام کنید. این دستورالعمل‌ها فرض می‌کنند که از Android Studio برای IDE خود استفاده می‌کنید.

  1. جدیدترین نسخه «کیت توسعه نرم‌افزار پیمایش» را از Google Drive مشترک بارگیری و استخراج کنید. اگر دسترسی ندارید، با نماینده‌تان تماس بگیرید.

  2. در Android Studio، پروژه‌ای را باز کنید و بااستفاده از مدیر SDK، بسته خدمات Google Play را اضافه کنید.

  3. از فهرست راهنمای فایل zip،‏ libs/google_navigation_navmap.aar را در فهرست راهنمای app/libs پروژه‌تان کپی کنید.

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

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

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

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

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

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

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

این بخش نحوه ذخیره کردن کلید میانای برنامه‌سازی کاربردی را شرح می‌دهد تا برنامه‌تان بتواند به‌طور ایمن به آن ارجاع دهد. نباید کلید میانای برنامه‌سازی کاربردی را در سیستم کنترل نسخه بررسی کنید، بنابراین توصیه می‌کنیم آن را در فایل 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 خود اضافه کنید (یا به‌نحوی آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید میانای برنامه‌سازی کاربردی خود را در کنترل نسخه بررسی نکنید.
    MAPS_API_KEY=YOUR_API_KEY
  5. فایل local.defaults.properties را در دایرکتوری سطح بالا، همان پوشه فایل secrets.properties، ایجاد کنید و سپس کد زیر را اضافه کنید.

    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