پروژه خود را راه اندازی کنید -- نسخه 4.99 و قبل از آن

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

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

این الزامات برای Navigation SDK برای اندروید نسخه 4.99 و نسخه های قبلی اعمال می شود.

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

  • برنامه شما باید سطح API 30 یا بالاتر را هدف قرار دهد.

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

  • اسناد و متن مجوز باید به برنامه اضافه شود.

پروژه های خود را راه اندازی کنید: پروژه کنسول ابری و پروژه اندروید

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

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

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

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

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

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

  1. وابستگی زیر را به پیکربندی 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>

استفاده از Maven برای Navigation SDK قبل از نسخه 4.5 یا با Driver SDK

Navigation SDK همچنان از طریق مخزن اصلی Maven در بقیه نسخه‌های v4 در دسترس است. این همان کتابخانه با تمام به‌روزرسانی‌های نسخه بالا است و سازگاری با Driver SDK و سایر کتابخانه‌ها را در طول انتقال فراهم می‌کند. استفاده از این وابستگی مستلزم ورود به پروژه ابری خود از طریق gcloud هنگام کامپایل است.

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

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

    گریدل

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

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

  1. آخرین نسخه Navigation SDK را از Google Drive مشترک دانلود کرده و آن را از حالت فشرده خارج کنید. اگر دسترسی ندارید، با نماینده خود تماس بگیرید.

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

  3. از فهرست فایل فشرده، 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. 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'
        }
    }
}

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

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

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

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

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

  • فایل build.gradle (Module:app) را باز کنید و از دستورالعمل‌های زیر برای به‌روزرسانی تنظیمات برای برآورده کردن الزامات Navigation SDK استفاده کنید و گزینه‌های بهینه‌سازی را نیز در نظر بگیرید.

    تنظیمات لازم برای Navigation SDK

    1. minSdkVersion روی 23 یا بالاتر تنظیم کنید.
    2. targetSdkVersion روی 30 یا بالاتر تنظیم کنید.
    3. یک تنظیم dexOptions اضافه کنید که javaMaxHeapSize را افزایش می دهد.
    4. مکان را برای کتابخانه های اضافی تنظیم کنید.
    5. repositories و dependencies را برای Navigation SDK اضافه کنید.
    6. شماره نسخه های موجود در وابستگی ها را با آخرین نسخه های موجود جایگزین کنید.

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

    • برای حذف کد و منابع استفاده نشده از وابستگی ها ، کوچک کردن کد و کوچک شدن منابع را با استفاده از R8/ProGuard فعال کنید. اگر مرحله R8/ProGuard برای اجرا زمان زیادی می برد، فعال کردن Multidex برای کار توسعه را در نظر بگیرید.
    • کاهش تعداد ترجمه‌های زبان موجود در ساخت: 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. Ensure 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'
}

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

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

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

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

  1. در 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"
    }
}
  2. فایل 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'
}
  3. در فایل build.gradle.kts یا build.gradle در سطح ماژول، مطمئن شوید که targetSdk و compileSdk روی 34 تنظیم شده اند.
  4. فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
  5. فایل secrets.properties را در دایرکتوری سطح بالای خود باز کنید و سپس کد زیر را اضافه کنید. کلید API خود را جایگزین YOUR_API_KEY کنید. کلید خود را در این فایل ذخیره کنید زیرا secrets.properties از بررسی سیستم کنترل نسخه حذف شده است.
    NAV_API_KEY=YOUR_API_KEY
  6. فایل را ذخیره کنید.

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

    NAV_API_KEY=DEFAULT_API_KEY

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

  8. فایل را ذخیره کنید.
  9. در فایل 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 یک استثنا ایجاد می کند.

  10. در 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