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

בדף הזה מוסבר איך להגדיר פרויקט ב-Android Studio לשימוש ב- SDK של מפות ל-Android בלי להשתמש בתבנית של מפות Google שמפורטת במדריך למתחילים.

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

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

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

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

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

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

    Kotlin

    dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

    Groovy

    dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:20.0.0"
}
  4. בקובץ build.gradle.kts או build.gradle ברמת המודול, מגדירים את compileSdk ו-minSdk לערכים הבאים:

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 23
        // ...
    }
}

    Groovy

    android {
    compileSdk 34

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

    Kotlin

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

    Groovy

    android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}
  6. בקובץ libs.versions.toml, מוסיפים את הקוד הבא: 
    [versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

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

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

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

כדי להתקין את הפלאגין Secrets Gradle ל-Android ולאחסן את מפתח ה-API:

  1. ב-Android Studio, פותחים את הקובץ build.gradle ברמת הבסיס ומוסיפים את הקוד הבא לרכיב dependencies בקטע buildscript.

    Groovy

    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.

    Groovy

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

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. אם אתם משתמשים ב-Android Studio, סנכרנו את הפרויקט עם Gradle.
  4. פותחים את הקובץ local.properties בספרייה ברמת הפרויקט ומוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם. 
    MAPS_API_KEY=YOUR_API_KEY
  5. בקובץ AndroidManifest.xml, עוברים אל com.google.android.geo.API_KEY ומעדכנים את המאפיין android:value באופן הבא: 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

    הערה: com.google.android.geo.API_KEY הוא שם המטא-נתונים המומלץ למפתח ה-API. אפשר להשתמש במפתח עם השם הזה כדי לאמת כמה ממשקי API שמבוססים על מפות Google בפלטפורמת Android, כולל ה-SDK של מפות ל-Android. לצורך תאימות לדורות קודמים, ה-API תומך גם בשם com.google.android.maps.v2.API_KEY. השם הזה הוא שם מדור קודם ומאפשר אימות רק לגרסה 2 של Android Maps API. אפליקציה יכולה לציין רק שם אחד של מטא-נתונים של מפתח API. אם מציינים את שניהם, ה-API זורק חריגה.

שלב 4: מעדכנים את קובץ המניפסט של האפליקציה

בקטע הזה מוסבר על ההגדרות שצריך להוסיף לקובץ AndroidManifest.xml.

מספר הגרסה של Google Play Services

מוסיפים את ההצהרה הבאה לרכיב application. הפעולה הזו מטמיעה את הגרסה של Google Play Services שאיתה האפליקציה עברה הידור.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version"/>

הרשאת מיקום

אם האפליקציה שלכם צריכה לגשת למיקום של המשתמש, אתם צריכים לבקש את הרשאת המיקום בקובץ AndroidManifest.xml. האפשרויות הן ACCESS_FINE_LOCATION, שמספקת את מיקום המכשיר המדויק, וACCESS_COARSE_LOCATION, שהיא פחות מדויקת. פרטים נוספים זמינים במדריך בנושא נתוני מיקום.

כדי לבקש את ההרשאה ACCESS_FINE_LOCATION, מוסיפים את הקוד הזה לרכיב manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

הרשאה לניהול אחסון חיצוני

אם אתם מטרגטים גרסה 8.3 ואילך של Google Play Services SDK, לא צריך את ההרשאה WRITE_EXTERNAL_STORAGE. אם אתם מכוונים לגרסאות קודמות של Google Play services SDK, אתם צריכים לבקש את ההרשאה WRITE_EXTERNAL_STORAGE ברכיב manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

ספריית Apache HTTP מדור קודם

אם אתם משתמשים בגרסה com.google.android.gms:play-services-maps:16.0.0 או בגרסה קודמת, והאפליקציה שלכם מטרגטת את רמת ה-API המיועדת 28 (Android 9.0) או רמה גבוהה יותר, אתם צריכים לכלול את ההצהרה הבאה ברכיב <application> של AndroidManifest.xml. אם לא, אפשר לדלג על ההצהרה הזו.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false"/>

שלב 5: הגדרת מכשיר Android

כדי להפעיל אפליקציה שמשתמשת ב-SDK של מפות ל-Android, צריך לפרוס אותה במכשיר Android או באמולטור של Android שמבוסס על Android בגרסה 6.0 ואילך וכולל את Google APIs.

  • כדי להשתמש במכשיר Android, פועלים לפי ההוראות במאמר הפעלת אפליקציות במכשיר חומרה.
  • כדי להשתמש באמולטור Android, אפשר ליצור מכשיר וירטואלי ולהתקין את האמולטור באמצעות Android Virtual Device (AVD) Manager שמגיע עם Android Studio.

‫שלב 6: בודקים אם יש תמיכה ב-Play Services (אופציונלי)

כדי להשתמש ב-SDK של מפות ל-Android, צריך להתקין את Google Play Services במכשיר שבו פורסים את האפליקציה. ‫Google מספקת שיטה שאפשר להפעיל מהאפליקציה כדי לבדוק. מידע נוסף זמין במאמר בנושא בדיקה אם Google Play Services מותקן.

השלבים הבאים

אחרי שמגדירים את הפרויקט, אפשר להוסיף מפה.