דף זה תורגם על ידי Cloud Translation API.

איך מגדירים פרויקט Android Studio

כדי להגדיר את האפליקציה לשימוש ב-Place SDK ל-Android, יש לפעול לפי לבצע מיליון שלבים. הן נדרשות לכל האפליקציות שמשתמשות ב-Place SDK ל-Android.

שלב 1: הגדרת Android Studio

במסמך הזה מתוארת סביבת פיתוח באמצעות קיפוד ב-Android Studio פלאגין של Android Gradle גרסה 8.2.

שלב 2. הגדרת ה-SDK

ספריית Places SDK ל-Android זמינה דרך מאגר Maven של Google. שפת תרגום להוסיף את ה-SDK לאפליקציה, לבצע את הפעולות הבאות:

בקובץ settings.gradle.kts ברמה העליונה, יש לכלול את התחילית פורטל הפלאגין של Gradle, במאגר Google Maven, ומאגר מרכזי של Maven מתחת לבלוק pluginManagement. בלוק pluginManagement חייבות להופיע לפני כל הצהרה אחרת בסקריפט.
```
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
} 
```
בקובץ settings.gradle.kts ברמה העליונה, יש לכלול את התחילית מאגר Maven של Google ו-המאגר המרכזי של Maven בקטע dependencyResolutionManagement:
```
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
} 
```
בתוך dependencies בקטע של קובץ המודול ברמת build.gradle, יש להוסיף תלות ל-Places SDK ל-Android:

הערה: מקומות SDK לגרסת Android לגרסה 3.5.0 נדרש kotlin-bom מגרסה 1.8.0 ואילך. עבור לקבלת מידע נוסף על התלות של kotlin-bom, אפשר לעיין במאמר שימוש בגרסה העדכנית ביותר של Kotlin-stdlib ביחסי תלות מעבריים.
מגניב
```
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.5.0")
}
```
בקובץ build.gradle ברמת המודול, מגדירים את compileSdk ו-minSdk לערכים הבאים:
הערה: חשוב לוודא שהשדה compileSdk מוגדר ל-34 ומעלה ו-minSdk מוגדר ל-21 ומעלה.
מגניב
```
android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        // ...
    }
}
```
Kotlin
```
android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        // ...
    }
}
```
בקטע buildFeatures בקובץ build.gradle ברמת המודול, מוסיפים את המחלקה BuildConfig, שבה משתמשים כדי לגשת לערכי מטא-נתונים שהוגדרו מאוחר יותר בתהליך הזה:
מגניב
```
android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}
```
Kotlin
```
android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}
```

שלב 3: מוסיפים את מפתח ה-API לפרויקט

בקטע הזה מוסבר איך לאחסן את מפתח ה-API כדי שתהיה אפשרות להפנות אליו באופן מאובטח באפליקציה שלך. אין לבדוק את מפתח ה-API במערכת ניהול הגרסאות, לכן מומלץ לאחסן אותו בקובץ secrets.properties, שממוקם בתיקיית השורש של פרויקט. מידע נוסף על הקובץ secrets.properties זמין בכתובת קובצי מאפייני Gradle.

כדי לייעל את המשימה הזו, מומלץ פלאגין של Secrets Gradle ל-Android.

כדי להתקין את הפלאגין Secrets Gradle ל-Android בפרויקט במפות Google:

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

פותחים את הקובץ 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'
}

בקובץ build.gradle.kts או build.gradle ברמת המודול, מוודאים ההגדרות של targetSdk ו-compileSdk עד 34.
שומרים את הקובץ ואז לסנכרן את הפרויקט עם Gradle
פותחים את הקובץ secrets.properties בספרייה שברמה העליונה, ואז מוסיפים את באמצעות הקוד הבא. מחליפים את YOUR_API_KEY במפתח ה-API שלכם. אחסון המפתח בקובץ הזה כי secrets.properties לא נכלל בבדיקה לניהול גרסאות המערכת.
הערה: אם הקובץ secrets.properties לא קיים, יוצרים אותו באותה תיקייה שבה נמצא הקובץ local.properties.
```
PLACES_API_KEY=YOUR_API_KEY
```
שומרים את הקובץ.
יוצרים את הקובץ local.defaults.properties בספרייה שברמה העליונה, אותה בתיקייה בתור הקובץ secrets.properties, ואז מוסיפים את הקוד הבא.

הערה: צריך להזין את הקוד כמו שמוצג. לא להחליף DEFAULT_API_KEY מחליפים במפתח ה-API.
```
PLACES_API_KEY=DEFAULT_API_KEY
```
מטרת הקובץ הזה היא לספק מיקום לגיבוי של מפתח ה-API אם קובץ secrets.properties לא נמצא כדי שגרסאות ה-build לא ייכשלו. הדבר יכול להתרחש אם משכפלים את האפליקציה ממערכת לניהול גרסאות שמושמטת מ-secrets.properties עדיין לא יצרת קובץ secrets.properties באופן מקומי כדי לספק מפתח API.
שומרים את הקובץ.

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

שלב 4. אתחול הלקוח של Places API

אתחול ה-Places SDK ל-Android בתוך פעילות או מקטע. קודם צריך להחליט באיזו גרסת SDK להשתמש: Places SDK ל-Android או Places SDK ל-Android (חדש). למידע נוסף על גרסאות של מוצרים: אפשר לעיין במאמר בחירת גרסת ה-SDK.

בדוגמה הבאה אפשר לראות איך להפעיל את ה-SDK לשתי הגרסאות.

Places SDK ל-Android (חדש)

העברת מפתח ה-API בזמן ביצוע קריאה 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 של מקומות ל-Android

העברת מפתח ה-API בזמן ביצוע קריאה 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);

עכשיו אתה מוכן להתחיל להשתמש ב-Place SDK ל-Android!

שלב 5: הגדרת מכשיר Android

כדי להריץ אפליקציה שמשתמשת ב- Places SDK ל-Android, עליך לפרוס אותו במכשיר Android או Android אמולטור שמבוסס על Android 5.0 ואילך וכולל ממשקי Google API.

כדי להשתמש במכשיר Android, יש לפעול לפי ההוראות שבכתובת הפעלת אפליקציות במכשיר חומרה
כדי להשתמש באמולטור Android, אפשר ליצור מכשיר וירטואלי ולהתקין את האמולטור באמצעות מנהל המכשיר הווירטואלי (AVD) של Android שכלול ב-Android Studio.
הערה: אם בוחרים להשתמש באמולטור Android, צריך לוודא בוחרים מכשיר שמוצג בו סמל Play ו- בעמודה חנות Play. הסמל הזה מציין שהפרופילים האלה הם CTS מלאים. תואמות ועשויות להשתמש בתמונות מערכת שכוללות את האפליקציה של חנות Play:

השלבים הבאים

אחרי שסיימתם להגדיר את הפרויקט, אתם יכולים לעיין אפליקציות לדוגמה.