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

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

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

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

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

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

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

    מגניב

    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. בקובץ build.gradle ברמת המודול, מגדירים את compileSdk ואת minSdk לערכים הבאים:

    מגניב

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

    Kotlin

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

    מגניב

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

    Kotlin

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

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

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

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

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

  1. ב-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")
        }
    }
    
  2. פותחים את הקובץ build.gradle ברמת המודול ומוסיפים את הקוד הבא לרכיב plugins.

    מגניב

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

    Kotlin

    plugins {
        id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    }
  3. בקובץ build.gradle ברמת המודול, מוודאים ש-targetSdk ו-compileSdk מוגדרים ל-34.
  4. שומרים את הקובץ ומסנכרנים את הפרויקט עם Gradle.
  5. פותחים את הקובץ secrets.properties בספרייה ברמה העליונה ומוסיפים את הקוד הבא. מחליפים את YOUR_API_KEY במפתח ה-API. אפשר לאחסן את המפתח בקובץ הזה כי אין אפשרות לבדוק את secrets.properties במערכת לניהול גרסאות.
    PLACES_API_KEY=YOUR_API_KEY
  6. שומרים את הקובץ.
  7. יוצרים את הקובץ local.defaults.properties בספרייה ברמה העליונה, באותה תיקייה שבה נמצא הקובץ secrets.properties, ולאחר מכן מוסיפים את הקוד הבא.

    PLACES_API_KEY=DEFAULT_API_KEY

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

  8. שומרים את הקובץ.
  9. ב-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. הפעל את לקוח ה-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 4.0 ואילך וכולל את Google APIs.

  • כדי להשתמש במכשיר Android, צריך לפעול לפי ההוראות במאמר הפעלת אפליקציות במכשיר חומרה.
  • כדי להשתמש באמולטור Android, אפשר ליצור מכשיר וירטואלי ולהתקין את האמולטור באמצעות מנהל המכשיר הווירטואלי (AVD) של Android שכלול ב-Android Studio.

השלבים הבאים

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