הגדרת פרויקט ב-Android Studio

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

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

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

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

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

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

1. בקובץ settings.gradle ברמה העליונה, יש לכלול את פורטל הפלאגין של Gradle, מאגר Google Maven ומאגר מרכזי של Maven בבלוק של pluginManagement. הבלוק pluginManagement חייב להופיע לפני כל הצהרה אחרת בסקריפט.

   pluginManagement {
       repositories {
           gradlePluginPortal()
           google()
           mavenCentral()
       }
   } 

2. בקובץ settings.gradle ברמה העליונה, יש לכלול את מאגר Maven ב-Google ואת המאגר המרכזי של Maven בבלוק dependencyResolutionManagement:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. בקובץ build.gradle ברמת המודול, מוסיפים את התלות של שירותי Google Play ל-SDK של מפות Google ל-Android.

   dependencies {
       implementation 'com.google.android.gms:play-services-maps:18.1.0'
       // ...
   } 

4. בקובץ build.gradle ברמת המודול, מגדירים את הערכים compileSdk ו-minSdk לערכים הבאים:
   הערה: יש לוודא שהערך של compileSdk הוא 31 ומעלה, והמדיניות minSdk מוגדרת לערך 19 ומעלה.

   android {
       compileSdk 31
   
       defaultConfig {
           minSdk 19
           // ...
       }

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

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

כדי לייעל את המשימה, מומלץ להשתמש בפלאגין Secrets Gradle ל-Android. כדי להתקין את הפלאגין ולאחסן את מפתח ה-API:

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

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

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

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
       

3. שומרים את הקובץ ומסנכרנים את הפרויקט עם Gradle.
4. פותחים את local.properties בספרייה ברמת הפרויקט ואז מוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API.

   MAPS_API_KEY=YOUR_API_KEY
       

5. שומרים את הקובץ.
6. בקובץ 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}" />
       

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

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

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

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

צריך להוסיף את ההצהרה הבאה ברכיב application. כך מטמיעה את הגרסה של שירותי Google Play שבאמצעותה נוצרה האפליקציה.

<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ההתחלה המהירה מופעלת ב-ACCESS_FINE_LOCATION.

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

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

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

אם אתם מטרגטים את גרסה 8.3 ואילך של ה-SDK של Google Play Services, אתם לא זקוקים להרשאה ב-WRITE_EXTERNAL_STORAGE. אם הגדרות הטירגוט שלך הן לגרסאות קודמות של ה-SDK של Google Play Services, עליך לבקש את ההרשאה 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 ואילך שכוללת את ממשקי ה-API של Google.

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

  

השלבים הבאים

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