הגדרה

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

הגדרת פרויקט ב-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.

הגדרה של פרויקט Android Studio

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

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

1. יוצרים פרויקט חדש ב-Android Studio באמצעות התבנית Empty Views Activity.

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:

   maps3dSdk = "0.0.1" # Update this value to match the SDK version to include
   secretsGradlePlugin = "2.0.1"
   

   • בקטע Library (ספרייה), מוסיפים את ספריית ה-SDK:

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

   • בקטע הפלאגין, מוסיפים את הפלאגין 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, מוסיפים את ה-SDK:

   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: – בספריית השורש של מודול האפליקציה, יוצרים קובץ חדש בשם secrets.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 Plugin יחליף את ה-placeholder‏ ${MAPS3D_API_KEY} במפתח מקובץ secrets.properties.

השלבים הבאים

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