הגדרה

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

הגדרת פרויקט ו-API key ב-Google Cloud

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

שלב 1

המסוף

  1. במסוף Google Cloud, בדף לבחירת הפרויקט לוחצים על Create Project כדי ליצור פרויקט חדש ב-Cloud.

    כניסה לדף לבחירת הפרויקט

  2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. מוודאים שהחיוב מופעל בפרויקט.

    ב-Google Cloud יש תקופת ניסיון ללא תשלום. תוקף תקופת הניסיון יפוג אחרי 90 יום או אחרי שיצטברו בחשבון חיובים בסך 300$, המוקדם מביניהם. תמיד אפשר לבטל. מידע נוסף זמין במאמרים זיכויים בחשבון לחיוב וחיוב.

Cloud SDK

gcloud projects create "PROJECT"

מידע נוסף על Google Cloud SDK, על התקנת Cloud SDK ועל הפקודות הבאות:

שלב 2

כדי להשתמש בפלטפורמה של מפות Google, צריך להפעיל את ממשקי ה-API או ערכות ה-SDK שבהם אתם מתכננים להשתמש בפרויקט.

חשוב לזכור שבשילובים מסוימים צריך להפעיל כמה ממשקי API או SDK. אם אתם לא בטוחים אילו ממשקי API או ערכות SDK צריך להפעיל, תוכלו להשתמש בבורר ממשקי ה-API או לעיין במסמכי התיעוד של ה-API או ה-SDK שבהם אתם רוצים להשתמש.

כדי להפעיל ממשק API או ערכת SDK אחת או יותר:

המסוף

  1. בדף Maps API Library במסוף Cloud תוכלו לראות את ממשקי ה-API וערכות ה-SDK של הפלטפורמה של מפות Google שאפשר להפעיל:

    נכנסים לדף Maps API Library

  2. לוחצים על ה-API או ה-SDK שרוצים להפעיל.
    • אם הלחצן כתוב ENABLE, לוחצים עליו כדי להפעיל את ה-API או את ה-SDK.
    • אם הכיתוב על הלחצן הוא ניהול, ה-API או ה-SDK כבר מופעלים ואין צורך לבצע פעולה נוספת.
    • לחיצה על אחד מהלחצנים תציג את לוח הבקרה של ה-API או ה-SDK. (לוחצים על הלחצן DISABLE כדי להסיר את ה-API או את ה-SDK מהפרויקט הזה).

Cloud SDK

הפקודה הבאה מפעילה את כל ממשקי ה-API של מפות Google, מסלולים ומקומות:

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"

מידע נוסף על Google Cloud SDK, על התקנת Cloud SDK ועל הפקודות הבאות:

משתמשים בפקודה הבאה כדי להפעיל את ממשקי ה-API של הסביבה:

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

שלב 3

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

מפתח ה-API הוא מזהה ייחודי שמאמת בקשות המשויכות לפרויקט שלכם לצורכי שימוש וחיובים. צריך להיות לפחות מפתח API אחד שמשויך לפרויקט.

כך יוצרים מפתח API:

המסוף

  1. עוברים לדף פלטפורמת מפות Google > פרטי כניסה.

    כניסה לדף Credentials

  2. בדף Credentials, לוחצים על Create credentials > API key.
    תיבת הדו-שיח API key created מציגה את מפתח ה-API החדש שיצרתם.
  3. לוחצים על סגירה.
    מפתח ה-API החדש מופיע בדף Credentials בקטע API keys.
    (חשוב להגביל את מפתח ה-API לפני שמשתמשים בו בסביבת הייצור).

Cloud SDK

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

מידע נוסף על Google Cloud SDK, על התקנת Cloud SDK ועל הפקודות הבאות:

כדי להפעיל את ה-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 ושל הפלאגין של Gradle ל-Secrets:

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

    -   In the library section, add the SDK library:

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

    -   In the plugin section, add the Secrets Gradle plugin:

    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
}

    -   In the `dependencies` block, add the SDK:

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

    -   At the end of the file, outside of the `android` and `dependencies`
    blocks, add the secrets configuration:

    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
``` Note: Make sure you
    replace `YOUR_API_KEY_HERE` with the API key that you configured for use
with the Maps 3D SDK for Android.

  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>

    במהלך תהליך ה-build, הפלאגין של Secrets Gradle יחליף את placeholder‏ ${MAPS3D_API_KEY} במפתח מהקובץ secrets.properties.

השלבים הבאים

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