אפשר ליצור אפליקציה ל-Android שמציגה מפה באמצעות התבנית של מפות Google ל-Android Studio. אם יש לכם פרויקט Android Studio שאתם רוצים להגדיר, תוכלו לקרוא את המאמר Project Configuration.
המדריך למתחילים מיועד למפתחים שמכירים בפיתוח בסיסי של Android באמצעות Java או Kotlin.
הגדרת סביבת הפיתוח
- נדרשת גרסת Android Studio Arctic Fox ואילך. אם עדיין לא עשית זאת, מורידים ומתקינים אותו.
- מוודאים שמשתמשים בפלאגין של Android Gradle בגרסה 7.0 ואילך ב-Android Studio.
הגדרת מכשיר Android
כדי להפעיל אפליקציה שמשתמשת ב-SDK של מפות Google ל-Android, צריך לפרוס אותה במכשיר Android או באמולטור Android שמבוסס על Android 4.0 ואילך וכולל את Google APIs.
- כדי להשתמש במכשיר Android, צריך לפעול לפי ההוראות במאמר הפעלת אפליקציות במכשיר חומרה.
- כדי להשתמש באמולטור של Android, אפשר ליצור מכשיר וירטואלי ולהתקין אותו באמצעות מנהל המכשירים הווירטואליים (AVD) של Android שכלול ב-Android Studio.
יצירת פרויקט של מפות Google ב-Android Studio
תהליך היצירה של פרויקט במפות Google ב-Android Studio השתנה ב-Flamingo ובגרסאות מאוחרות יותר של Android Studio. הקפידו לבצע את השלבים הבאים בגרסה הספציפית של Android Studio.
פותחים את Android Studio ולוחצים על Create New Project (יצירת פרויקט חדש) בחלון Welcome to Android Studio.
בחלון New Project, בקטגוריה Phone and Tablet, בוחרים באפשרות Empty Activity ולוחצים על Next.
ממלאים את הטופס פעילות במפות Google:
מגדירים את השפה ל-Java או ל-Kotlin. שתי השפות נתמכות באופן מלא על ידי ה-SDK של מפות Google ל-Android. מידע נוסף על Kotlin זמין במאמר פיתוח אפליקציות ל-Android בעזרת Kotlin.
יש להגדיר את ה-SDK המינימלי לגרסת SDK שתואמת למכשיר הבדיקה. עליכם לבחור גרסה חדשה יותר מהגרסה המינימלית שנדרשת על ידי ה-SDK של מפות Google ל-Android מגרסה 18.0.x ואילך, כלומר Android API ברמה 19 (Android 4.4, KitKat) ואילך. מידע עדכני על הדרישות לגרסת ה-SDK זמין בנתוני הגרסה.
לוחצים על סיום.
מערכת Android Studio מפעילה את Gradle ויוצרת את הפרויקט. פעולה זו עשויה להימשך זמן מה.
בסיום ה-build, Android Studio פותח את הקבצים
AndroidManifest.xmlו-MapsActivity. לפעילות שלכם עשוי להיות שם אחר, אבל זהו השם שהגדרתם במהלך ההגדרה.הוספת פעילות הצפיות במפות Google:
- לחצו לחיצה ימנית על החבילה שאליה תרצו להוסיף את 'פעילות צפיות במפות Google'.
- בוחרים חדש > Google > פעילות צפיות במפות Google.
מידע נוסף זמין במאמר הוספת קוד מתבנית.
הקובץ
AndroidManifest.xmlמכיל הוראות לקבלת מפתח API של מפות Google ולהוספה שלו לקובץ local.properties. אין להוסיף את מפתח ה-API לקובץAndroidManifest.xml. פעולה זו שומרת את מפתח ה-API באופן פחות מאובטח. במקום זאת, בצעו את ההוראות שמפורטות בסעיפים הבאים כדי ליצור פרויקט ב-Cloud ולהגדיר מפתח API.
הגדרת פרויקט ב-Google Cloud
מבצעים את השלבים הנדרשים להגדרה של מסוף Cloud בלחיצה על הכרטיסיות הבאות:
שלב 1
מסוף
-
במסוף Google Cloud, בדף לבחירת הפרויקט לוחצים על Create Project כדי ליצור פרויקט חדש ב-Cloud.
-
הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. מוודאים שהחיוב מופעל בפרויקט.
ב-Google Cloud מוצעת תקופת ניסיון לחיוב בסך 0.00$. תקופת הניסיון מסתיימת בתום 90 הימים או אחרי שהחשבון יצבור חיובים בסך 300$, המוקדם מביניהם. אפשר לבטל את המינוי בכל שלב. הפלטפורמה של מפות Google כוללת קרדיט חודשי בסך 200$. למידע נוסף אפשר לקרוא את המאמרים זיכויים בחשבון לחיוב וחיוב.
Cloud SDK
gcloud projects create "PROJECT"
למידע נוסף על Google Cloud SDK , התקנת Cloud SDK , ועל הפקודות הבאות:
שלב 2
כדי להשתמש בפלטפורמה של מפות Google, צריך להפעיל את ממשקי ה-API או את ערכות ה-SDK שבהם אתם מתכוונים להשתמש בפרויקט.
מסוף
Cloud SDK
gcloud services enable \
--project "PROJECT" \
"maps-android-backend.googleapis.com"
למידע נוסף על Google Cloud SDK , התקנת Cloud SDK , ועל הפקודות הבאות:
שלב 3
השלב הזה כולל רק את התהליך ליצירת מפתח API. אם אתם משתמשים במפתח ה-API בסביבת הייצור, מומלץ מאוד להגביל את מפתח ה-API. מידע נוסף זמין בדף שימוש במפתחות API הספציפי למוצר.
מפתח ה-API הוא מזהה ייחודי שמאמת בקשות שמשויכות לפרויקט שלך למטרות שימוש וחיוב. צריך להיות לכם לפחות מפתח API אחד שמשויך לפרויקט.
כך יוצרים מפתח API:
מסוף
-
עוברים לדף הפלטפורמה של מפות Google > פרטי כניסה.
-
בדף Credentials, לוחצים על Create credentials > מפתח API.
תיבת הדו-שיח API key created מציגה את מפתח ה-API החדש שיצרתם. -
לוחצים על סגירה.
מפתח ה-API החדש מופיע בדף Credentials בקטע API keys.
(חשוב לזכור להגביל את מפתח ה-API לפני שמשתמשים בו בסביבת הייצור).
Cloud SDK
gcloud alpha services api-keys create \
--project "PROJECT" \
--display-name "DISPLAY_NAME"
למידע נוסף על Google Cloud SDK , התקנת Cloud SDK , ועל הפקודות הבאות:
מוסיפים את מפתח ה-API לאפליקציה
בקטע הזה נסביר איך לאחסן את מפתח ה-API כך שהאפליקציה תוכל להפנות אליו באופן מאובטח. אין לבדוק את מפתח ה-API במערכת בקרת הגרסאות, לכן מומלץ לשמור אותו בקובץ local.properties, שנמצא בספריית הבסיס של הפרויקט. למידע נוסף על הקובץ local.properties, קראו את המאמר קבצים של מאפייני Gradle.
כדי לייעל את המשימה הזו, מומלץ להשתמש בפלאגין של Secrets Gradle ל-Android. כדי להתקין את הפלאגין ולאחסן את מפתח ה-API:
- ב-Android Studio, פותחים את הקובץ
build.gradleברמת הפרויקט ומוסיפים את הקוד הבא לרכיבdependenciesבקטעbuildscript.plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false } - אחר כך פותחים את הקובץ
build.gradleברמת המודול ומוסיפים את הקוד הבא לרכיבplugins.id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' - שומרים את הקובץ ומסנכרנים את הפרויקט עם Gradle.
- פותחים את
local.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}" />
הערה: כפי שמתואר למעלה, 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 יחריג חריג.
הצגת הקוד
בודקים את הקוד שהתבנית מספקת. חשוב במיוחד לבחון את הקבצים הבאים בפרויקט Android Studio.
קובץ פעילות במפות
קובץ הפעילות במפות הוא הפעילות העיקרית של האפליקציה, והוא מכיל את הקוד לניהול ולהצגה של המפה. השם של הקובץ שמגדיר את הפעילות הוא MapsActivity.java כברירת מחדל, או אם הגדרתם את Kotlin כשפה של האפליקציה, MapsActivity.kt.
המרכיבים העיקריים של פעילות המפות:
האובייקט
SupportMapFragmentמנהל את מחזור החיים של המפה והוא רכיב ההורה בממשק המשתמש של האפליקציה.האובייקט
GoogleMapמספק גישה לנתוני המפה ולתצוגה. זוהי הסיווג הראשי של ה-SDK של מפות Google ל-Android. במדריך מיפוי אובייקטים תוכלו למצוא מידע מפורט יותר על האובייקטיםSupportMapFragmentו-GoogleMap.הפונקציה
moveCameraמרכזת את המפה בקואורדינטותLatLngשל סידני אוסטרליה. ההגדרות הראשונות שצריך לקבוע כשמוסיפים מפה הן בדרך כלל המיקום של המפה והגדרות המצלמה, למשל זווית התצוגה, כיוון המפה ורמת המרחק מהתצוגה. לפרטים נוספים עיינו במדריך מצלמה ותצוגה.הפונקציה
addMarkerמוסיפה סמן לקואורדינטות של סידני. פרטים נוספים זמינים במדריך סמנים.
קובץ הפעילות של מפות Google מכיל את הקוד הבא:
Java
import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;
public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {
private GoogleMap mMap;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_maps);
// Obtain the SupportMapFragment and get notified when the map is ready to be used.
SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
.findFragmentById(R.id.map);
mapFragment.getMapAsync(this);
}
/**
* Manipulates the map once available.
* This callback is triggered when the map is ready to be used.
* This is where we can add markers or lines, add listeners or move the camera. In this case,
* we just add a marker near Sydney, Australia.
*
* If Google Play services is not installed on the device, the user will be prompted to install
* it inside the SupportMapFragment. This method will only be triggered once the user has
* installed Google Play services and returned to the app.
*/
@Override
public void onMapReady(GoogleMap googleMap) {
mMap = googleMap;
// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
mMap.addMarker(new MarkerOptions()
.position(sydney)
.title("Marker in Sydney"));
mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
}
}
Kotlin
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions
internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {
private lateinit var mMap: GoogleMap
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_maps)
// Obtain the SupportMapFragment and get notified when the map is ready to be used.
val mapFragment = supportFragmentManager
.findFragmentById(R.id.map) as SupportMapFragment
mapFragment.getMapAsync(this)
}
/**
* Manipulates the map once available.
* This callback is triggered when the map is ready to be used.
* This is where we can add markers or lines, add listeners or move the camera. In this case,
* we just add a marker near Sydney, Australia.
* If Google Play services is not installed on the device, the user will be prompted to install
* it inside the SupportMapFragment. This method will only be triggered once the user has
* installed Google Play services and returned to the app.
*/
override fun onMapReady(googleMap: GoogleMap) {
mMap = googleMap
// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
mMap.addMarker(MarkerOptions()
.position(sydney)
.title("Marker in Sydney"))
mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
}
}
קובץ Module Gradle
קובץ המודול build.gradle כולל את התלות הבאה של מפות, הנדרשת על ידי ה-SDK של מפות Google ל-Android.
dependencies {
implementation 'com.google.android.gms:play-services-maps:18.1.0'
// ...
}
מידע נוסף על ניהול התלות במפות Google זמין במאמר ניהול גרסאות.
קובץ פריסת XML
הקובץ activity_maps.xml הוא קובץ פריסת ה-XML שמגדיר את המבנה של ממשק המשתמש של האפליקציה. הקובץ נמצא בספרייה res/layout.
בקובץ activity_maps.xml יש הצהרה על מקטע שמכיל את הרכיבים הבאים:
tools:contextמגדיר את פעילות ברירת המחדל של המקטע כ-MapsActivity, שמוגדר בקובץ הפעילות של מפות Google.android:nameמגדיר את שם המחלקה של המקטע כ-SupportMapFragment, שהוא סוג המקטע שנמצא בקובץ הפעילות של מפות.
קובץ פריסת ה-XML מכיל את הקוד הבא:
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:id="@+id/map"
tools:context=".MapsActivity"
android:name="com.google.android.gms.maps.SupportMapFragment" />
פריסה והפעלה של האפליקציה
כשהאפליקציה פועלת בהצלחה, תוצג מפה במרכז בסידני אוסטרליה עם סמן על העיר כפי שנראה בצילום המסך הבא.
כדי לפרוס את האפליקציה ולהפעיל אותה:
- ב-Android Studio, לוחצים על אפשרות התפריט הפעלה (או על סמל לחצן ההפעלה) כדי להפעיל את האפליקציה.
- כשמתבקשים לבחור מכשיר, בוחרים אחת מהאפשרויות הבאות:
- בוחרים את מכשיר Android שמחובר למחשב.
- אפשר גם ללחוץ על לחצן הבחירה Launch emulator (הפעלת אמולטור) ולבחור את המכשיר הווירטואלי שמגדירים.
- לוחצים על אישור. מערכת Android Studio תפעיל את Gradle כדי ליצור את האפליקציה שלך, ולאחר מכן תציג את התוצאות במכשיר או באמולטור שלך. ייתכן שיחלפו כמה דקות עד שהאפליקציה תופעל.
השלבים הבאים
הגדרת מפה: בנושא הזה נסביר איך לקבוע את ההגדרות הראשוניות וזמן הריצה של המפה, כמו מיקום המצלמה, סוג המפה, רכיבי ממשק המשתמש ותנועות.
הוספת מפה לאפליקציה ל-Android (Kotlin): ה-Codelab הזה יעזור לכם להשתמש באפליקציה שמדגימה כמה תכונות נוספות של ה-SDK של מפות Google ל-Android.
שימוש בספריית KTX של מפות Google ל-Android: הספרייה הזו של תוספי Kotlin (KTX) מאפשרת לכם להשתמש במספר תכונות של שפת Kotlin תוך שימוש ב-SDK של מפות ל-Android.