ตั้งค่าโครงการของคุณ -- เวอร์ชัน 4.99 และเวอร์ชันก่อนหน้า

คู่มือนี้แสดงข้อกำหนดการกำหนดค่าบิลด์สำหรับการใช้ Navigation SDK สําหรับ Android วิธีการนี้จะถือว่าคุณมี Android IDE และคุ้นเคยกับการพัฒนาซอฟต์แวร์ Android

ข้อกำหนดขั้นต่ำสำหรับการใช้ Navigation SDK

ข้อกำหนดเหล่านี้มีผลกับ Navigation SDK สำหรับ Android เวอร์ชัน 4.99 และเวอร์ชันก่อนหน้า

ตั้งค่าโปรเจ็กต์: โปรเจ็กต์ Cloud Console และโปรเจ็กต์ Android

ก่อนจะสร้างหรือทดสอบแอป คุณต้องสร้างโปรเจ็กต์ Cloud Console และเพิ่มข้อมูลเข้าสู่ระบบคีย์ API โปรเจ็กต์ต้องมีการจัดสรรเพื่อเข้าถึง SDK การนำทาง คีย์ทั้งหมดในโปรเจ็กต์ Cloud Console ได้รับสิทธิ์เข้าถึง Navigation SDK ในระดับเดียวกัน คีย์อาจมีโปรเจ็กต์การพัฒนาเชื่อมโยงอยู่มากกว่า 1 โปรเจ็กต์ หากมีโปรเจ็กต์คอนโซลอยู่แล้ว คุณจะเพิ่มคีย์ในโปรเจ็กต์ปัจจุบันได้

วิธีตั้งค่า

  1. ลงชื่อเข้าใช้ Cloud Console ในเว็บเบราว์เซอร์ที่คุณชื่นชอบ แล้วสร้างโปรเจ็กต์ Cloud Console
  2. ใน IDE เช่น Android Studio ให้สร้างโปรเจ็กต์การพัฒนาแอป Android และจดชื่อแพ็กเกจไว้
  3. โปรดติดต่อตัวแทนของ Google Maps Platform เพื่อขอสิทธิ์เข้าถึง Navigation SDK สําหรับโปรเจ็กต์ในคอนโซลระบบคลาวด์
  4. ขณะที่อยู่ในแดชบอร์ด Cloud Console ในเว็บเบราว์เซอร์ ให้สร้างข้อมูลเข้าสู่ระบบเพื่อสร้างคีย์ API ที่มีข้อจำกัด
  5. ในหน้าคีย์ API ให้คลิกแอป Android ในพื้นที่ข้อจำกัดของแอปพลิเคชัน
  6. คลิกเพิ่มชื่อแพ็กเกจและลายนิ้วมือ แล้วป้อนชื่อแพ็กเกจของโปรเจ็กต์การพัฒนาและลายนิ้วมือ SHA-1 ของคีย์นั้น
  7. คลิกบันทึก

เพิ่ม Navigation SDK ลงในโปรเจ็กต์

Navigation SDK มีให้ใช้งานผ่าน Maven หรือแพ็กเกจ AAR หลังจากสร้างโปรเจ็กต์การพัฒนาแล้ว คุณสามารถผสานรวม SDK เข้ากับโปรเจ็กต์ได้โดยใช้แนวทางใดแนวทางหนึ่งต่อไปนี้

รายการต่อไปนี้ใช้ที่เก็บ google() Maven ซึ่งเป็นวิธีที่ง่ายที่สุดในการเพิ่ม Navigation SDK ไปยังโปรเจ็กต์ของคุณ

  1. เพิ่มทรัพยากร Dependency ต่อไปนี้ในการกำหนดค่า Gradle หรือ Maven ของคุณ โดยแทนที่ตัวยึดตำแหน่ง VERSION_NUMBER สำหรับ Navigation SDK สำหรับ 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. 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

    เพิ่มสิ่งต่อไปนี้ใน pom.xml

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

    หากคุณมีทรัพยากร Dependency ที่ใช้ Maps SDK คุณต้องยกเว้นการขึ้นต่อกันที่ Dependency ที่ประกาศแต่ละรายการซึ่งอาศัย 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 สำหรับ SDK การนำทางเวอร์ชันก่อนหน้าเวอร์ชัน 4.5 หรือ SDK ไดรเวอร์

Navigation SDK จะยังคงพร้อมใช้งานผ่านที่เก็บ Maven เดิมในเวอร์ชัน v4 ที่เหลือ ไลบรารีนี้เป็นไลบรารีเดียวกันที่มีการอัปเดตทั้งหมดเหมือนกับเวอร์ชันด้านบน และเข้ากันได้กับ Driver SDK และไลบรารีอื่นๆ ในระหว่างการเปลี่ยนผ่าน การใช้ข้อกำหนดนี้ต้องเข้าสู่ระบบโปรเจ็กต์ที่อยู่ในระบบคลาวด์ผ่าน gcloud เมื่อคอมไพล์

  1. ตั้งค่าสภาพแวดล้อมเพื่อเข้าถึงที่เก็บ Maven ของ Google ตามที่อธิบายไว้ในส่วนข้อกําหนดเบื้องต้นของเอกสารประกอบ SDK สําหรับผู้บริโภค การเข้าถึง Navigation SDK จะควบคุมผ่านกลุ่มพื้นที่ทํางาน
  2. เพิ่มทรัพยากร Dependency ต่อไปนี้ในการกําหนดค่า 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. 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

    เพิ่มสิ่งต่อไปนี้ใน pom.xml

    <dependencies>
      ...
      <dependency>
        <groupId>com.google.android.maps</groupId>
        <artifactId>navsdk</artifactId>
        <version>VERSION_NUMBER</version>
      </dependency>
    </dependencies>
    

    หากมี Dependency ที่ใช้ Maps SDK คุณต้องยกเว้น Dependency นั้นใน Dependency ที่ประกาศแต่ละรายการซึ่งใช้ 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 ไดรฟ์ที่แชร์ แล้วแตกไฟล์ หากไม่มีสิทธิ์เข้าถึง โปรดติดต่อตัวแทนของคุณ

  2. ใน Android Studio ให้เปิดโปรเจ็กต์และเพิ่มแพ็กเกจบริการ Google Play โดยใช้ SDK Manager

  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. 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 ให้เปิดไฟล์ local.properties แล้วเพิ่ม android.useDeprecatedNdk=true

อัปเดตสคริปต์การบิลด์ Gradle

  • เปิดไฟล์ build.gradle (Module:app) และใช้หลักเกณฑ์ต่อไปนี้เพื่ออัปเดตการตั้งค่าให้เป็นไปตามข้อกำหนดของ Navigation SDK และพิจารณาตั้งค่าตัวเลือกการเพิ่มประสิทธิภาพด้วย

    การตั้งค่าที่จำเป็นสำหรับ SDK การนำทาง

    1. ตั้งค่า minSdkVersion เป็น 23 ขึ้นไป
    2. ตั้งค่า targetSdkVersion เป็น 30 ขึ้นไป
    3. เพิ่มการตั้งค่า dexOptions ที่เพิ่ม javaMaxHeapSize
    4. กำหนดตำแหน่งสำหรับคลังเพิ่มเติม
    5. เพิ่ม repositories และ dependencies สำหรับ Navigation SDK
    6. แทนที่หมายเลขเวอร์ชันในทรัพยากร Dependency ด้วยเวอร์ชันล่าสุดที่มีอยู่

    การตั้งค่าที่ไม่บังคับเพื่อลดเวลาบิลด์

    • เปิดใช้การลดขนาดโค้ดและการลดขนาดทรัพยากรโดยใช้ R8/ProGuard เพื่อนำโค้ดและทรัพยากรที่ไม่ได้ใช้งานออกจากทรัพยากร Dependency หากขั้นตอน R8/ProGuard ใช้เวลานานเกินไป ให้พิจารณาเปิดใช้ multidex สำหรับงานพัฒนา
    • ลดจำนวนคำแปลภาษาที่รวมอยู่ในบิลด์: ตั้งค่า resConfigs สำหรับ 1 ภาษาในระหว่างการพัฒนา สําหรับบิลด์สุดท้าย ให้ตั้งค่า resConfigs สำหรับภาษาที่คุณใช้จริง โดยค่าเริ่มต้น Gradle รวมสตริงทรัพยากรสำหรับทุกภาษาที่ Navigation SDK รองรับ

ด้านล่างเป็นตัวอย่างของสคริปต์บิลด์ Gradle สำหรับแอปพลิเคชัน ตรวจสอบตัวอย่างแอปเพื่อดูชุดทรัพยากร Dependency ที่อัปเดตใหม่ เนื่องจากเวอร์ชัน 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 สำหรับ Android เพื่อปรับปรุงการทำงานนี้ให้มีประสิทธิภาพยิ่งขึ้น

วิธีติดตั้งปลั๊กอิน Secrets Gradle สำหรับ Android ในโปรเจ็กต์ Google Maps

  1. ใน Android Studio ให้เปิดไฟล์ build.gradle.kts หรือ build.gradle ระดับบนสุด แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ dependencies ใต้ buildscript

    Kotlin

    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

    Kotlin

    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 ในไดเรกทอรีระดับบนสุด แล้วเพิ่มโค้ดต่อไปนี้ แทนที่ YOUR_API_KEY ด้วยคีย์ API เก็บคีย์ไว้ในไฟล์นี้เนื่องจาก 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 v2 เท่านั้น แอปพลิเคชันจะระบุชื่อข้อมูลเมตาของคีย์ API ได้เพียงชื่อเดียวเท่านั้น หากระบุทั้ง 2 รายการ API จะแสดงข้อยกเว้น

  10. ใน 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 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 ในแอป คุณต้องใส่ข้อความระบุแหล่งที่มาและใบอนุญาตโอเพนซอร์สในส่วนประกาศทางกฎหมายของแอป

คุณดูข้อความระบุแหล่งที่มาที่จําเป็นและใบอนุญาตโอเพนซอร์สได้ในไฟล์ ZIP ของ Navigation SDK สําหรับ Android

  • NOTICE.txt
  • LICENSES.txt