בדף זה נסביר איך להגדיר פרויקט ב-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
לערכים הבאים: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.
שלב 6: אפשרות לבדוק אם יש תמיכה ב-Play Service
כדי להשתמש ב-SDK של מפות Google ל-Android, יש להתקין את שירותי Google Play במכשיר שבו פורסים את האפליקציה. Google מספקת שיטה שאפשר להתקשר אליה מהאפליקציה כדי לבדוק אותה. למידע נוסף, קראו את המאמר בדיקה אם Google Play Services מותקנים.
השלבים הבאים
לאחר הגדרת הפרויקט, אפשר להוסיף מפה.