הגדרה

בדף הזה מוסבר מה צריך לעשות כדי להתחיל לפתח באמצעות Maps 3D SDK ל-Android. תהליך ההגדרה כולל הגדרה של פרויקט ב-Google Cloud ו-API לשימוש עם ה-SDK, ואז הגדרה של פרויקט ב-Android Studio. לפני שמוסיפים את מפת התלת-ממד הראשונה לאפליקציה, צריך לבצע את השלבים הבאים.

דרישות מוקדמות

כדי להשתמש ב-Maps 3D SDK ל-Android, הפרויקט ומכשירי היעד צריכים לעמוד בדרישות הבאות:

• רמת API מינימלית: רמת API‏ 24 ב-Android‏ (Android 7.0) ומעלה. האפליקציה צריכה לטרגט ל-minSdk של 24 ומעלה.
• ‫Google Play Services: ערכת Maps 3D SDK ל-Android תלויה ב-Google Play Services. במכשירי היעד (ובאמולטורים עם Google APIs) צריכה להיות מותקנת אפליקציית Google Play Services.

הגדרת פרויקט בענן ב-Google Cloud ומפתח API

כדי להתחיל לפתח באמצעות Maps 3D SDK ל-Android, צריך להגדיר פרויקט בענן ב-Google Cloud ומפתח API לשימוש עם Maps 3D SDK ל-Android. לשם כך, צריך לבצע את השלבים הבאים:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

כדי להפעיל את ה-SDK, נכנסים לדף Maps 3D SDK ל-Android במסוף Google Cloud. מידע נוסף על השלבים האלה מופיע במאמר תחילת השימוש ב-Google Maps Platform.

הגדרת פרויקט ב-Android Studio

בקטע הזה מוסבר איך ליצור ולהגדיר פרויקט ב-Android Studio לשימוש עם Maps 3D SDK ל-Android.

חלק 1: הגדרת הפרויקט והגדרת Gradle

1. יוצרים פרויקט חדש ב-Android Studio באמצעות התבנית Empty Views Activity. בהגדרות הפרויקט, מגדירים את גרסת ה-SDK המינימלית לAPI 24 או לגרסה מתקדמת יותר.

2. אם אתם משתמשים ב-Git לניהול גרסאות, שנו את הקובץ .gitignore של הפרויקט כדי למנוע את הוספת קובץ הסודות לניהול הגרסאות:

   • בתיקיית השורש של הפרויקט, פותחים את הקובץ .gitignore.
   • מוסיפים את השורה הבאה:

   secrets.properties
   

3. מעדכנים את הקובץ build.gradle.kts ברמת הפרויקט:

   • בתיקיית השורש של הפרויקט, פותחים את הקובץ build.gradle.kts.
   • בבלוק plugins, מוסיפים את הפלאגין Secrets Gradle:

   plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
   }
   

4. מעדכנים את הקובץ gradle/libs.versions.toml:

   • פותחים את הקובץ gradle/libs.versions.toml, שבדרך כלל נמצא בספרייה gradle בתוך תיקיית השורש של הפרויקט.
   • בקטע [versions], מוסיפים את הגרסאות של ה-SDK ושל הפלאגין Secrets Gradle:

   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "16.0.1"
   # See https://github.com/google/secrets-gradle-plugin/releases for available releases
   secretsGradlePlugin = "2.0.1"
   

   • בקטע [library], מוסיפים את ספריית ה-SDK:

   play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
   

   • בקטע [plugins], מוסיפים את הפלאגין Secrets Gradle:

   secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }
   

5. מעדכנים את הקובץ app/build.gradle.kts ברמת המודול:

   • פותחים את הקובץ build.gradle.kts ברמת המודול, שבדרך כלל נמצא בספרייה app.
   • בחלק העליון של הקובץ, מוסיפים את הפלאגין Secrets Gradle לבלוק plugins:

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.secrets.gradle.plugin) // Add this line
   }
   

   • בבלוק dependencies, מוסיפים את התלות ב-Google Play Services בשביל Maps 3D SDK ל-Android:

   dependencies {
       // ... other dependencies
       implementation(libs.play.services.maps3d) // Add this line
   }
   

   • בסוף הקובץ, מחוץ לבלוקים android ו-dependencies, מוסיפים את הגדרת הסודות:

   secrets {
       // Optionally specify a different filename 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"
   }
   

חלק 2: הוספת מפתח ה-API לפרויקט

1. יוצרים קובץ secrets.properties:

   • בתיקיית השורש של מודול האפליקציה (בדרך כלל התיקייה app), יוצרים קובץ חדש בשם secrets.properties.
   • מוסיפים את מפתח ה-API לקובץ:

   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   

2. יוצרים קובץ local.defaults.properties: - בתיקיית השורש של מודול האפליקציה, יוצרים קובץ חדש בשם local.defaults.properties. ‫- מוסיפים מפתח API של ברירת מחדל או placeholder לקובץ. אפשר להכניס את הקובץ הזה לניהול גרסאות:

   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   

חלק 3: מעדכנים את הקובץ AndroidManifest.xml

1. פותחים את הקובץ app/src/main/AndroidManifest.xml.

2. בתוך התג <application>, לפני התג <activity>, מוסיפים את הרכיב <meta-data> הבא כדי להצהיר על מפתח ה-API:

   <application
       ...>
   
       <meta-data
           android:name="com.google.android.geo.maps3d.API_KEY"
           android:value="${MAPS3D_API_KEY}" />
   
       <activity
           ...>
       </activity>
   </application>
   

   במהלך תהליך הבנייה, התוסף Secrets Gradle יחליף את הפלייסולדר ${MAPS3D_API_KEY} במפתח מקובץ secrets.properties.

אתחול תצוגה פרוגרמטית (אופציונלי)

אם אתם מעדיפים להפעיל את תצוגת המפה באופן פרוגרמטי ולא בפריסות XML, השתמשו ב-Map3DInitConfig.

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

השלבים הבאים

אחרי שמגדירים פרויקט בענן ב-Google Cloud, מפתח API ופרויקט ב-Android Studio לשימוש עם Maps 3D SDK ל-Android, אפשר להוסיף מפה תלת-ממדית לאפליקציה.