Thiết lập dự án Android Studio

Để định cấu hình ứng dụng nhằm sử dụng SDK Địa điểm dành cho Android, hãy làm theo các bước sau. Đây là những yêu cầu bắt buộc đối với tất cả các ứng dụng sử dụng SDK Địa điểm dành cho Android.

Bước 1: Thiết lập Android Studio

Tài liệu này mô tả một môi trường phát triển sử dụng Android Studio Hedgehogtrình bổ trợ Android cho Gradle phiên bản 8.2.

Bước 2. Thiết lập SDK

SDK Địa điểm dành cho thư viện Android hiện có trong Kho lưu trữ Maven của Google. Để thêm SDK vào ứng dụng, hãy làm như sau:

  1. Trong tệp settings.gradle cấp cao nhất, hãy thêm cổng trình bổ trợ Gradle, Kho lưu trữ Google Mavenkho lưu trữ trung tâm Maven trong khối pluginManagement. Khối pluginManagement phải xuất hiện trước mọi câu lệnh khác trong tập lệnh.
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    } 
  2. Trong tệp settings.gradle cấp cao nhất, hãy đưa Kho lưu trữ Maven của GoogleKho lưu trữ trung tâm Maven vào khối dependencyResolutionManagement:
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
        }
    } 
  3. Trong phần dependencies của tệp build.gradle cấp mô-đun, hãy thêm phần phụ thuộc vào SDK Địa điểm dành cho Android:

    Groovy

    dependencies {
        // If updating kotlin-bom version number above, also edit project-level build.gradle definition of $kotlin_version variable
        implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
        implementation 'com.google.android.libraries.places:places:3.3.0'
    }

    Kotlin

    dependencies {
        implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
        implementation("com.google.android.libraries.places:places:3.3.0")
    }
  4. Trong tệp build.gradle ở cấp mô-đun, hãy đặt compileSdkminSdk thành các giá trị sau:

    Groovy

    android {
        compileSdk 34
    
        defaultConfig {
            minSdk 21
            // ...
        }
    }

    Kotlin

    android {
        compileSdk = 34
    
        defaultConfig {
            minSdk = 21
            // ...
        }
    }
  5. Trong phần buildFeatures của tệp build.gradle ở cấp mô-đun, hãy thêm lớp BuildConfig mà bạn sử dụng để truy cập vào các giá trị siêu dữ liệu được xác định sau trong quy trình này:

    Groovy

    android {
      // ...
      buildFeatures {
        buildConfig true
        // ...
      }
    }

    Kotlin

    android {
      // ...
      buildFeatures {
        buildConfig = true
        // ...
      }
    }

Bước 3: Thêm khoá API vào dự án

Phần này mô tả cách lưu trữ khoá API để ứng dụng của bạn có thể tham chiếu khoá một cách an toàn. Bạn không nên kiểm tra khoá API trong hệ thống quản lý phiên bản. Vì vậy, bạn nên lưu trữ khoá đó trong tệp secrets.properties, nằm trong thư mục gốc của dự án. Để biết thêm thông tin về tệp secrets.properties, hãy xem các tệp thuộc tính Gradle.

Để đơn giản hoá tác vụ này, bạn nên sử dụng Trình bổ trợ Bí mật cho Gradle cho Android.

Cách cài đặt Trình bổ trợ Secrets Gradle cho Android trong dự án Google Maps:

  1. Trong Android Studio, hãy mở tệp build.gradle hoặc build.gradle.kts cấp cao nhất rồi thêm mã sau vào phần tử dependencies trong 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. Mở tệp build.gradle ở cấp mô-đun và thêm mã sau vào phần tử plugins.

    Groovy

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

    Kotlin

    plugins {
        id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    }
  3. Trong tệp build.gradle ở cấp mô-đun, hãy đảm bảo rằng targetSdkcompileSdk được đặt thành 34.
  4. Lưu tệp và đồng bộ hoá dự án của bạn với Gradle.
  5. Mở tệp secrets.properties trong thư mục cấp cao nhất của bạn, sau đó thêm mã sau. Thay thế YOUR_API_KEY bằng khoá API. Lưu trữ khoá của bạn trong tệp này vì secrets.properties không được phép kiểm tra trong một hệ thống quản lý phiên bản.
    PLACES_API_KEY=YOUR_API_KEY
  6. Lưu tệp.
  7. Tạo tệp local.defaults.properties trong thư mục cấp cao nhất, cùng thư mục với tệp secrets.properties, sau đó thêm mã sau.

    PLACES_API_KEY=DEFAULT_API_KEY

    Mục đích của tệp này là cung cấp vị trí sao lưu cho khoá API nếu không tìm thấy tệp secrets.properties để các bản dựng không bị lỗi. Điều này có thể xảy ra nếu bạn sao chép ứng dụng từ một hệ thống quản lý phiên bản, trong đó bỏ qua secrets.properties và bạn chưa tạo tệp secrets.properties cục bộ để cung cấp khoá API của mình.

  8. Lưu tệp.
  9. Trong Android Studio, hãy mở tệp build.gradle hoặc build.gradle.kts ở cấp mô-đun rồi chỉnh sửa thuộc tính secrets. Hãy thêm thuộc tính secrets nếu chưa có.

    Chỉnh sửa các thuộc tính của trình bổ trợ để đặt propertiesFileName thành secrets.properties, đặt defaultPropertiesFileName thành local.defaults.properties và đặt mọi thuộc tính khác.

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

Bước 4. Khởi chạy ứng dụng Places API

Khởi chạy Places SDK dành cho Android trong một hoạt động hoặc mảnh. Trước tiên, bạn phải quyết định phiên bản SDK sẽ sử dụng: SDK Địa điểm dành cho Android hoặc SDK Địa điểm dành cho Android (Mới). Để biết thêm thông tin về các phiên bản sản phẩm, hãy xem phần Chọn phiên bản SDK của bạn.

Ví dụ sau cho thấy cách khởi chạy SDK cho cả hai phiên bản.

SDK Địa điểm dành cho Android (Mới)

Truyền khoá API khi gọi Places.initializeWithNewPlacesApiEnabled():

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)
    

Java

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);
    

SDK Địa điểm dành cho Android

Truyền khoá API khi gọi Places.initialize():

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

    // Initialize the SDK
    Places.initialize(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)
    

Java

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

    // Initialize the SDK
    Places.initialize(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);
    

Giờ đây, bạn đã sẵn sàng để bắt đầu sử dụng SDK Địa điểm dành cho Android!

Bước 5: Thiết lập thiết bị Android

Để chạy một ứng dụng sử dụng SDK Địa điểm dành cho Android, bạn phải triển khai SDK đó cho thiết bị Android hoặc trình mô phỏng Android dựa trên Android 4.0 trở lên và có chứa các API của Google.

  • Để sử dụng thiết bị Android, hãy làm theo hướng dẫn trong bài viết Chạy ứng dụng trên thiết bị phần cứng.
  • Để sử dụng trình mô phỏng Android, bạn có thể tạo một thiết bị ảo và cài đặt trình mô phỏng bằng cách sử dụng Trình quản lý thiết bị Android ảo (AVD) đi kèm với Android Studio.

Các bước tiếp theo

Sau khi định cấu hình dự án, bạn có thể khám phá ứng dụng mẫu.