הגדרה

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

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

לפני שמתחילים לפתח באמצעות 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. כדי לראות את ממשקי ה-API וערכות ה-SDK של הפלטפורמה של מפות Google שאפשר להפעיל, עוברים לדף Maps API Library במסוף Cloud:

    עוברים לדף Maps API Library

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

Cloud SDK

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

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" \
    "weather.googleapis.com"

שלב 3

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

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

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

המסוף

  1. עוברים לדף Google Maps Platform > Credentials (הפלטפורמה של מפות 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 ושל התוסף Secrets Gradle:

    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 שמוגדר כברירת מחדל או מציין מיקום לקובץ. אפשר להכניס את הקובץ הזה לבקרת גרסאות:

    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, אתם יכולים להוסיף מפה תלת-ממדית לאפליקציה.