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

Để định cấu hình ứng dụng sử dụng Places SDK 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 Places SDK 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 bằng Android Studio Hedgehog và trình bổ trợ Android cho Gradle phiên bản 8.2.

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

Thư viện SDK Địa điểm cho Android được cung cấp thông qua 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.kts cấp cao nhất, hãy thêm Cổng trình bổ trợ Gradle, Kho lưu trữ Maven của Google và Kho lưu trữ trung tâm Maven vào 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 {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
  2. Trong tệp settings.gradle.kts cấp cao nhất, hãy thêm kho lưu trữ Maven của Google và kho lưu trữ trung tâm Maven vào khối dependencyResolutionManagement: 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
    }
}

  3. Trong mục dependencies của tệp build.gradle.kts ở cấp mô-đun, hãy thêm một phần phụ thuộc vào Places SDK cho Android:

    Groovy

    dependencies {
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
    implementation("com.google.android.libraries.places:places:3.5.0")
}

    Kotlin

              dependencies {

    // Places and Maps SDKs
    implementation("com.google.android.libraries.places:places:6.0.2")
}
  4. Trong tệp build.gradle.kts ở cấp mô-đun, hãy đặt compileSdk và minSdk thành các giá trị sau:

    Groovy

    android {
    compileSdk 34

    defaultConfig {
        minSdk 23
        // ...
    }
}

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 23
        // ...
    }
}
  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 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 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 trong thư mục gốc của dự án và loại trừ tệp đó khỏi hệ thống quản lý phiên bản. Để biết thêm thông tin về tệp thuộc tính Gradle, hãy xem phần 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ợ Secrets Gradle cho Android.

Cách cài đặt Trình bổ trợ Secrets Gradle cho Android và lưu trữ khoá API:

  1. Trong Android Studio, hãy mở tệp build.gradle.kts hoặc build.gradle cấp cao nhất rồi thêm mã sau vào khối 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. Mở tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun rồi thêm mã sau vào phần tử 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. Nếu bạn sử dụng Android Studio, hãy đồng bộ hoá dự án với Gradle.
  4. Mở tệp secrets.properties trong thư mục cấp cao nhất, rồi thêm đoạn mã sau. Thay thế YOUR_API_KEY bằng khoá API của bạn. Hãy nhớ thêm secrets.properties vào tệp .gitignore (hoặc loại trừ tệp này khỏi hệ thống quản lý phiên bản) để không đưa khoá API vào hệ thống quản lý phiên bản. 
    PLACES_API_KEY=YOUR_API_KEY

  5. 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, rồi thêm mã sau.

    PLACES_API_KEY=DEFAULT_API_KEY

    Mục đích của tệp này là cung cấp một 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 kiểm soát phiên bản bỏ qua secrets.properties và bạn chưa tạo tệp secrets.properties cục bộ để cung cấp khoá API.

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

    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.

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

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

Để khởi chạy Places SDK for Android trong một hoạt động hoặc mảnh, hãy 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);

Giờ đây, bạn đã sẵn sàng bắt đầu sử dụng Places SDK 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 cho Android, bạn phải triển khai ứng dụng đó cho một thiết bị Android hoặc trình mô phỏng Android dựa trên Android 6.0 trở lên và có các API của Google.

  • Để sử dụng thiết bị Android, hãy làm theo hướng dẫn tại phần 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 Trình quản lý thiết bị đ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.