דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

נדרשת גרסת Android Studio Arctic Fox ואילך. אם עדיין לא עשית זאת, מורידים ומתקינים אותו.
מוודאים שמשתמשים בפלאגין של Android Gradle בגרסה 7.0 ואילך ב-Android Studio.

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

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

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

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
} 
```
בקובץ build.gradle ברמת המודול, מגדירים את compileSdk ואת minSdk לערכים הבאים:
הערה: חשוב לוודא שהערך של compileSdk מוגדר ל-31 ואילך וש-minSdk מוגדרת לערך 19 ואילך.
```
android {
    compileSdk 31

    defaultConfig {
        minSdk 19
        // ...
    }
```

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

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

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

כדי להתקין את הפלאגין Secrets Gradle ל-Android בפרויקט מפות Google:

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

מגניב

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")
    }
}

פותחים את הקובץ build.gradle ברמת המודול ומוסיפים את הקוד הבא לרכיב plugins.

מגניב

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

Kotlin

plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

שומרים את הקובץ ומסנכרנים את הפרויקט עם Gradle.
פותחים את secrets.properties בספרייה ברמת הפרויקט ומוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם.
```
MAPS_API_KEY=YOUR_API_KEY 
```
שומרים את הקובץ.
בקובץ AndroidManifest.xml, עוברים אל com.google.android.geo.API_KEY ומעדכנים את android:value attribute באופן הבא:
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
```

אפשר לערוך את מאפייני הפלאגין כדי לציין קובץ סודות אחר או מאפיינים אחרים. ב-Android Studio, פותחים את הקובץ build.gradle ברמת הפרויקט ועורכים את הנכס secrets:

secrets {
    // Optionally specify a different file name 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'

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

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

כדי להשתמש במכשיר Android, צריך לפעול לפי ההוראות במאמר הפעלת אפליקציות בחומרה.
כדי להשתמש באמולטור של Android, אפשר ליצור מכשיר וירטואלי ולהתקין אותו באמצעות מנהל המכשירים הווירטואליים (AVD) של Android שכלול ב-Android Studio.
הערה: אם בוחרים להשתמש באמולטור של Android, חשוב לבחור מכשיר עם סמל Play, , שמוצג בעמודה חנות Play. הסמל הזה מציין שהפרופילים האלה תואמים לחלוטין ל-CTS ועשויים להשתמש בתמונות מערכת שכוללות את אפליקציית חנות Play:

שלב 6: אפשרות לבדוק אם יש תמיכה ב-Play Service

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

השלבים הבאים

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