Menyiapkan project

Panduan ini mencantumkan persyaratan konfigurasi build untuk menggunakan Navigation SDK untuk Android versi 5.0.0 dan yang lebih baru.

Catatan: Jika project Anda menggunakan Navigation SDK untuk Android tanpa menggunakan dependensi Maven, yang tersedia dalam versi hingga 4.99.2, ikuti petunjuk penyiapan pada bagian Menyiapkan project Anda -- Versi 4.99.2 dan yang lebih lama.

Petunjuk ini mengasumsikan bahwa Anda telah menginstal Android IDE dan sudah memahami pengembangan Android.

Peringatan: Mulai dari Navigation SDK (Versi 5.0.0), API tidak lagi mendukung Lollipop (4.4-5.1).

Persyaratan minimum untuk menggunakan Navigation SDK

Persyaratan ini berlaku untuk Navigation SDK untuk Android versi 5.0.0 dan yang lebih baru.

• Project Konsol Google Cloud dengan Navigation SDK diaktifkan. Untuk penyediaan, tanyakan kepada perwakilan Google Maps Platform Anda.

• Aplikasi Anda harus menentukan versi Android sebagai berikut:

  • versi target harus Android 13 (level API 33) atau yang lebih tinggi.
  • versi minimum harus Android 6 (API level 23) atau yang lebih tinggi.

• Untuk menjalankan aplikasi yang dibangun dengan Navigation SDK, perangkat Android harus memenuhi persyaratan berikut:

  • Layanan Google Play yang diinstal dan diaktifkan.

  • RAM 2 GB atau lebih.

  • Dukungan OpenGL ES 2.0. Lihat dokumentasi Kompatibilitas Android 6.0 Open Source Android untuk Akselerasi Grafis 2D dan 3D

• Teks atribusi dan pemberian lisensi harus ditambahkan ke aplikasi.

Menyiapkan project: project Konsol Cloud dan project Android

Sebelum dapat membangun atau menguji aplikasi, Anda harus membuat project Konsol Cloud dan menambahkan kredensial kunci API. Project harus memiliki penyediaan untuk mengakses Navigation SDK. Semua kunci dalam project Konsol Cloud diberi akses yang sama ke Navigation SDK. Sebuah kunci dapat memiliki lebih dari satu project pengembangan yang terkait dengannya. Jika sudah memiliki project konsol, Anda dapat menambahkan kunci ke project saat ini.

Informasi yang diperlukan untuk menyiapkan project

• Nama perwakilan Google Maps Platform Anda.
• Nama untuk project Konsol Cloud Anda.
• Nama untuk project pengembangan aplikasi Android Anda yang memiliki nama paket yang akan Anda perlukan nanti.
• Sidik jari sertifikat SHA-1 untuk mesin pengembangan Anda.

Untuk menyiapkan

1. Di browser web favorit Anda, login ke Cloud Console dan buat project Cloud Console.
2. Di IDE, seperti Android Studio, buat project pengembangan aplikasi Android dan catat nama paketnya.
3. Hubungi perwakilan Google Maps Platform untuk memberikan akses ke Navigation SDK untuk project Konsol Cloud Anda.
4. Saat berada di dasbor Konsol Cloud di browser web Anda, buat kredensial untuk membuat kunci API dengan pembatasan.
5. Di halaman API key, klik aplikasi Android di area Application restrictions.
6. Klik Add the package name and fingerprint, lalu masukkan nama paket project pengembangan Anda dan sidik jari SHA-1 untuk kunci tersebut.
7. Klik Save.

Menambahkan Navigation SDK ke project Anda

Navigation SDK tersedia melalui Maven. Setelah membuat project pengembangan, Anda dapat mengintegrasikan SDK ke dalamnya dengan menggunakan salah satu pendekatan berikut.

Penting: Anda harus menggunakan dependensi Maven dalam project untuk menautkan Navigation SDK untuk Android.

Menggunakan Maven untuk Navigation SDK v4.5 dan yang lebih baru (direkomendasikan)

Berikut ini menggunakan repositori Maven google(), yang merupakan cara paling sederhana dan direkomendasikan untuk menambahkan Navigation SDK ke project Anda.

Catatan: Metode ini tidak kompatibel dengan beberapa library yang bergantung pada Navigation SDK melalui ID artefak sebelumnya. Hal ini termasuk rilis Driver SDK v4.4 atau yang lebih lama.

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

   Gradle

   Tambahkan kode berikut ke build.gradle level modul:

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

   Jika mengupgrade dari repositori Maven asli, perhatikan bahwa nama grup dan artefak telah berubah, dan plugin com.google.cloud.artifactregistry.gradle-plugin tidak lagi diperlukan.

   Dan tambahkan kode berikut ke build.gradle level teratas:

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

   Maven

   Tambahkan kode berikut ke pom.xml Anda:

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

   Jika memiliki dependensi yang menggunakan Maps SDK, Anda harus mengecualikan dependensi dalam setiap dependensi yang dideklarasikan, yang bergantung pada 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>
   

Mengonfigurasi build

Setelah membuat project, Anda dapat mengonfigurasi setelan untuk build dan penggunaan Navigation SDK yang berhasil.

Perbarui properti lokal

• Dalam folder Gradle Scripts, buka file local.properties, lalu tambahkan android.useDeprecatedNdk=true.

Mengupdate skrip build Gradle

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

  Setelan yang diperlukan untuk Navigation SDK

  1. Tetapkan minSdkVersion ke versi 23 atau lebih tinggi.
  2. Tetapkan targetSdkVersion ke versi 33 atau lebih tinggi.
  3. Tambahkan setelan dexOptions yang meningkatkan javaMaxHeapSize.
  4. Tetapkan lokasi untuk library tambahan.
  5. Menambahkan 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 terlalu banyak waktu 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 sebenarnya 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 ini 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 cara opsi kompilasi dan dependensi.

Berikut adalah contoh skrip build Gradle untuk aplikasi. Periksa aplikasi contoh untuk melihat kumpulan dependensi yang telah diupdate, karena versi Navigation SDK yang Anda gunakan mungkin sedikit lebih awal atau di belakang 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 33
        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:1.1.9'
}

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, yang terletak di direktori root project Anda. Untuk informasi selengkapnya tentang file secrets.properties, lihat file properti Gradle.

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

Catatan: Lihat dokumentasi Plugin Secrets Gradle untuk Android di GitHub guna mengetahui petunjuk penginstalan dan persyaratan sistem terbaru.

Untuk menginstal Plugin Secrets Gradle untuk Android di project Google Maps:

1. Di Android Studio, buka file build.gradle atau build.gradle.kts tingkat teratas dan tambahkan kode berikut ke elemen dependencies di bagian buildscript.

   Groovy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }
   

2. Buka file build.gradle tingkat modul dan tambahkan kode berikut ke elemen plugins.

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

   plugins {
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. Di file build.gradle tingkat modul, pastikan targetSdk dan compileSdk ditetapkan ke 34.
4. Simpan file dan sinkronkan project Anda dengan Gradle.
5. Buka file secrets.properties di direktori tingkat teratas, lalu tambahkan kode berikut. Ganti YOUR_API_KEY dengan kunci API Anda. Simpan kunci Anda dalam file ini karena secrets.properties tidak di-check in ke dalam sistem kontrol versi.
   Catatan: Jika file secrets.properties tidak ada, buat file tersebut di folder yang sama dengan file local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. Simpan file.

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

   Catatan: Masukkan kode sebagaimana yang ditampilkan. Jangan ganti DEFAULT_API_KEY dengan Kunci API Anda.

   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 memberi Anda Kunci API.

8. Simpan file.
9. Di file AndroidManifest.xml, buka com.google.android.geo.API_KEY, lalu perbarui android:value attribute. Jika tag <meta-data> tidak ada, buat tag tersebut sebagai turunan dari tag <application>.

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Navigation SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

Menyertakan atribusi yang diperlukan dalam aplikasi Anda

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

Poin utama: Untuk menyertakan atribusi, tambahkan atribusi sebagai item menu independen atau item pada menu Tentang.

Anda dapat menemukan teks atribusi dan lisensi open source yang diperlukan di file ZIP Navigation SDK untuk Android:

• NOTICE.txt
• LICENSES.txt

Jika Anda adalah pelanggan Mobility atau Fleet Engine Pengiriman

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