Menyiapkan project Android Studio

Halaman ini menjelaskan cara mengintegrasikan Navigation SDK ke dalam project pengembangan Anda.

Menambahkan Navigation SDK ke project Anda

Navigation SDK tersedia melalui Google Maven Repository. Anda dapat menambahkan SDK ke project menggunakan konfigurasi Gradle build.gradle atau Maven pom.xml.

  1. Tambahkan dependensi berikut ke konfigurasi Gradle atau Maven Anda, dengan mengganti placeholder VERSION_NUMBER dengan versi Navigation SDK for Android yang diinginkan.

    Gradle

    Tambahkan kode berikut ke build.gradle level modul Anda:

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

    Maven

    Tambahkan kode berikut ke pom.xml:

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

  2. Jika memiliki dependensi yang menggunakan Maps SDK, Anda harus mengecualikan dependensi di setiap dependensi yang dideklarasikan yang mengandalkan Maps SDK.

    Gradle

    Tambahkan kode berikut ke build.gradle level teratas Anda:

    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

    Tambahkan kode berikut ke 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>

Mengonfigurasi build

Setelah membuat project, Anda dapat mengonfigurasi setelan agar berhasil mem-build dan menggunakan Navigation SDK.

Memperbarui properti lokal

  • Di folder Gradle Scripts, buka file local.properties dan tambahkan android.useDeprecatedNdk=true.

Memperbarui skrip build Gradle

  • Buka file build.gradle (Module:app) dan gunakan panduan berikut untuk memperbarui setelan agar memenuhi persyaratan Navigation SDK dan pertimbangkan untuk menetapkan opsi pengoptimalan juga.

    Setelan yang diperlukan untuk Navigation SDK

    1. Tetapkan minSdkVersion ke 24 atau yang lebih tinggi.
    2. Tetapkan targetSdkVersion ke 36 atau lebih tinggi.
    3. Tambahkan setelan dexOptions yang meningkatkan javaMaxHeapSize.
    4. Tetapkan lokasi untuk library tambahan.
    5. Tambahkan repositories dan dependencies untuk Navigation SDK.
    6. Ganti nomor versi dalam dependensi dengan versi terbaru yang tersedia.

    Setelan opsional untuk mengurangi waktu build

    • Aktifkan penyingkatan kode dan penyingkatan resource menggunakan R8/ProGuard untuk menghapus kode dan resource yang tidak digunakan dari dependensi. Jika langkah R8/ProGuard memerlukan waktu terlalu lama untuk dijalankan, pertimbangkan untuk mengaktifkan multidex untuk pekerjaan pengembangan.
    • Kurangi jumlah terjemahan bahasa yang disertakan dalam build: Tetapkan resConfigs untuk satu bahasa selama pengembangan. Untuk build akhir, tetapkan resConfigs untuk bahasa yang benar-benar Anda gunakan. Secara default, Gradle menyertakan string resource untuk semua bahasa yang didukung oleh Navigation SDK.

    Menambahkan desugaring untuk dukungan Java8

    • Jika Anda mem-build aplikasi menggunakan plugin Android Gradle 4.0.0 atau yang lebih tinggi, plugin tersebut akan memperluas dukungan untuk penggunaan sejumlah API bahasa Java 8. Lihat dukungan desugaring Java 8 untuk mengetahui informasi selengkapnya. Lihat contoh cuplikan skrip build di bawah untuk mengetahui opsi kompilasi dan dependensi.
    • Gunakan versi Gradle, plugin Android Gradle (AGP), dan library Desugar yang sesuai dengan versi Navigation SDK Anda. Lihat tabel berikut.
    • Library Desugar harus diaktifkan untuk modul app dan modul apa pun yang secara langsung bergantung pada Navigation SDK.

Tabel berikut mencantumkan versi library Gradle, AGP, dan Desugar yang diperlukan untuk setiap versi Navigation SDK.

Versi Navigation SDK Versi Gradle Versi AGP Library desugar
8.0.0 dan yang lebih baru 9.1.0 9.0.1 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.7.0 hingga 7.9.0 8.13 8.13.2 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.3.0 hingga 7.6.0 8.11.1 8.10.0 com.android.tools:desugar_jdk_libs_nio:2.0.3

Berikut adalah contoh skrip build Gradle untuk aplikasi. Periksa aplikasi contoh untuk mengetahui set dependensi yang diperbarui, karena versi Navigation SDK yang Anda gunakan mungkin sedikit lebih baru atau lebih lama dari dokumentasi ini.

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'
}

Menambahkan kunci API ke aplikasi

Bagian ini menjelaskan cara menyimpan kunci API sehingga dapat dirujuk dengan aman oleh aplikasi Anda. Anda tidak boleh memasukkan kunci API ke dalam sistem kontrol versi Anda, jadi sebaiknya simpan kunci tersebut dalam file secrets.properties di direktori root project Anda dan kecualikan file tersebut dari kontrol versi. Untuk informasi selengkapnya tentang file properti Gradle, lihat File properti Gradle.

Untuk menyederhanakan tugas ini, sebaiknya gunakan Plugin Secrets Gradle untuk Android.

Untuk menginstal Plugin Secrets Gradle untuk Android dan menyimpan kunci API Anda:

  1. Di Android Studio, buka file build.gradle.kts atau build.gradle tingkat teratas dan tambahkan kode berikut ke blok 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. Buka file build.gradle.kts atau build.gradle tingkat modul dan tambahkan kode berikut ke elemen 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. Jika Anda menggunakan Android Studio, sinkronkan project Anda dengan Gradle.
  4. Buka file secrets.properties di direktori tingkat teratas, lalu tambahkan kode berikut. Ganti YOUR_API_KEY dengan kunci API Anda. Pastikan untuk menambahkan secrets.properties ke file .gitignore (atau mengecualikannya dari sistem kontrol versi) agar Anda tidak memasukkan kunci API ke dalam kontrol versi. 
    MAPS_API_KEY=YOUR_API_KEY

  5. Buat file local.defaults.properties di direktori tingkat teratas, folder yang sama dengan file secrets.properties, lalu tambahkan kode berikut.

    MAPS_API_KEY=DEFAULT_API_KEY

    File ini ditujukan untuk menyediakan lokasi cadangan Kunci API jika file secrets.properties tidak dapat ditemukan agar build tidak gagal. Build dapat gagal jika Anda meng-clone aplikasi dari sistem kontrol versi yang menghapus secrets.properties dan Anda belum membuat file secrets.properties secara lokal untuk memberikan Kunci API Anda.

  6. Anda dapat menambahkan kunci API ke file AndroidManifest.xml atau memberikan kunci API secara terprogram.
    • Tambahkan kunci API Anda ke AndroidManifest.xml: 
      <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

      Catatan: com.google.android.geo.API_KEY adalah nama metadata yang direkomendasikan untuk kunci API. Kunci dengan nama ini dapat digunakan untuk mengautentikasi beberapa API berbasis Google Maps sekaligus di platform Android, termasuk Navigation SDK for Android. Untuk kompatibilitas mundur, API tersebut juga mendukung nama com.google.android.maps.v2.API_KEY. Nama lama ini hanya memungkinkan autentikasi untuk Android Maps API v2. Aplikasi hanya dapat menetapkan salah satu nama metadata kunci API. Jika keduanya ditetapkan, API akan menampilkan pengecualian.

    • Berikan kunci API secara terprogram:

      Plugin Secrets Gradle menyediakan kunci di class BuildConfig. Dalam inisialisasi aplikasi Anda (misalnya, dalam metode Application.onCreate()), panggil metode sebagai berikut:

      Kotlin

      1. Tambahkan pernyataan impor berikut: 
        import com.google.android.libraries.navigation.NavigationApi
      2. Tambahkan kode berikut ke metode Application.onCreate() Anda: 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

      Java

      1. Tambahkan pernyataan impor berikut: 
        import com.google.android.libraries.navigation.NavigationApi;
      2. Tambahkan kode berikut ke metode Application.onCreate() Anda: 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
      Catatan: Saat menggunakan setApiKey(), perhatikan hal berikut:
      • Berikan kunci API yang tidak null dan tidak kosong.
      • Panggil setApiKey() hanya sekali selama masa aktif aplikasi Anda. Metode ini menampilkan IllegalStateException jika dipanggil lebih dari sekali.
      • Panggil setApiKey() sebelum melakukan inisialisasi komponen Navigation SDK lainnya, seperti Navigator.
      • Kunci yang Anda berikan dengan metode ini akan menggantikan kunci API apa pun di AndroidManifest.xml Anda.
      • Gunakan Navigation SDK versi 7.6 atau yang lebih tinggi.

  7. Di Android Studio, buka file build.gradle.kts atau build.gradle tingkat modul dan edit properti secrets. Jika properti secrets tidak ada, tambahkan properti tersebut.

    Edit properti plugin untuk menetapkan propertiesFileName ke "secrets.properties", tetapkan defaultPropertiesFileName ke "local.defaults.properties", dan tetapkan properti lainnya.

    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"
}

Menyertakan atribusi yang diperlukan di aplikasi Anda

Jika Anda menggunakan Navigation SDK for Android di aplikasi Anda, Anda harus menyertakan teks atribusi dan lisensi open source sebagai bagian dari bagian pemberitahuan hukum aplikasi Anda.

Anda dapat menemukan teks atribusi dan lisensi open source yang diperlukan dalam file zip Navigation SDK for Android:

  • NOTICE.txt
  • LICENSES.txt

Jika Anda adalah pelanggan Mobility atau Fleet Engine Deliveries

Jika Anda adalah pelanggan Mobility atau Fleet Engine Deliveries, pelajari penagihan dalam dokumentasi Mobility. Untuk mengetahui informasi selengkapnya tentang pencatatan transaksi, lihat Menyiapkan penagihan, Mencatat transaksi yang dapat ditagih, Pelaporan, dan Mencatat transaksi yang dapat ditagih (Android).

Dependensi manual (non-Gradle/Maven)

Jika sistem build Anda tidak menyelesaikan dependensi transitif (seperti Bazel), atau jika Anda mengintegrasikan AAR secara manual, Anda harus menambahkan dependensi ini ke project Anda. Gradle dan Maven menyelesaikannya secara otomatis.

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