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

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

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

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

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

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

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

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

בקטע dependencies בקובץ build.gradle ברמת המודול, מוסיפים תלות ל-Places SDK ל-Android:

הערה: Places 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 או build.gradle.kts ברמה העליונה, ומוסיפים את הקוד הבא לרכיב dependencies בקטע buildscript.

מגניב

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

פותחים את הקובץ build.gradle ברמת המודול ומוסיפים את הקוד הבא לרכיב plugins.

מגניב

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

Kotlin

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

בקובץ 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 או build.gradle.kts ברמת המודול ועורכים את המאפיין secrets. אם הנכס secrets לא קיים, צריך להוסיף אותו.

עורכים את המאפיינים של הפלאגין כדי להגדיר את propertiesFileName לערך secrets.properties, מגדירים את defaultPropertiesFileName לערך local.defaults.properties ומגדירים מאפיינים אחרים.

מגניב

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

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

לאתחל את ה-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

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

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

השלבים הבאים

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