הפעלה של ממשק API גיאו-מרחבי באפליקציית Android (Kotlin/Java)

קובעים את הגדרות האפליקציה כדי שהיא תוכל להשתמש ב-Geospatial API.

דרישות מוקדמות

לפני שממשיכים, חשוב לוודא שאתם מבינים את המושגים הבסיסיים של AR ואת האופן שבו מגדירים סשן של ARCore.

אפליקציה ו-Codelab לדוגמה

בסרטון הזה מפורטים השלבים לבניית אפליקציה שמציגה נתונים גיאו-מרחביים ומציבה תוכן במיקומים בעולם האמיתי באמצעות ה-API Geospatial.

אפשר גם להיעזר במסמכי התיעוד ב-Geospatial codelab כדי לבצע את אותם השלבים. כדי להריץ את האפליקציה לדוגמה שנוצרה בסרטון, עיינו במדריך למתחילים גיאו-מרחבי ARCore.

לקבלת מידע נוסף על ה-API Geospatial, עיינו במאמר מבוא ל-Geospatial API.

אם רק התחלתם לפתח עם ARCore, קראו את המאמר תחילת העבודה כדי לקבל מידע על דרישות התוכנה והחומרה, דרישות מוקדמות ומידע אחר שספציפי לפלטפורמות שבהן אתם משתמשים.

ודאו שסביבת הפיתוח עומדת בדרישות של ARCore SDK, כפי שמתואר במדריך למתחילים.

הפעלת ARCore API

לפני השימוש במערכת המיקום החזותי (VPS) באפליקציה, צריך להפעיל את ARCore API בפרויקט חדש או קיים ב-Google Cloud. השירות הזה אחראי לאירוח, לאחסון ולזיהוי של עוגנים גיאו-מרחביים.

עדיף להשתמש בהרשאה ללא מפתח, אבל יש גם תמיכה בהרשאה של מפתח API.

צריך להוסיף את הספריות הנדרשות לאפליקציה

אחרי שנתתם לאפליקציה הרשאה לקרוא ל-ARCore API, עליכם להוסיף ספריות כדי להפעיל תכונות גיאו-מרחביות באפליקציה.

בקובץ build.gradle של האפליקציה, מגדירים את שירותי Google Play כך שיכללו את ספריית המיקומים של Play Services.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

הפעלת יכולות גיאו-מרחביות בהגדרת הסשן

לפני יצירת הסשן, צריך לשנות את GeospatialMode בהגדרות של הסשן ל-ENABLED:

Java

Config config = session.getConfig();
config.setGeospatialMode(Config.GeospatialMode.ENABLED);
session.configure(config);

Kotlin

// Enable the Geospatial API.
session.configure(session.config.apply { geospatialMode = Config.GeospatialMode.ENABLED })

בעוד שהמצב הגאו-מרחבי מוגדר כ-ENABLED, האפליקציה יכולה לקבל מידע גיאוגרפי ממערכת המיקום החזותי (VPS).

הצגת בקשה מהמשתמש לאפשר שימוש בנתוני המכשיר

באפליקציות שמשתמשות ב-ARCore Geospatial API, תתבקשו לאשר את השימוש בנתונים מהמכשיר שלהם ולאפשר את השימוש בהם. למידע נוסף, כדאי לעיין בדרישות בנושא פרטיות המשתמשים.

בדיקת תאימות המכשיר

לא כל המכשירים שתומכים ב-ARCore תומכים גם ב-Geospatial API, כפי שמתואר quickstart.

כדי לבדוק את התאימות של מכשיר המשתמש, צריך להתקשר אל Session.checkGeospatialModeSupported(). אם ההגדרה הזו מחזירה את הערך False, אל תנסו להגדיר את הסשן (בהמשך), כי הפעולה הזו תגרום להצגת UnsupportedConfigurationException.

בקשת הרשאות מיקום מהמשתמש בזמן הריצה

האפליקציה צריכה לבקש הרשאות מיקום בזמן הריצה.

כדי להשתמש ב-ARCore Geospatial API, האפליקציה שלכם צריכה לרשום את ההרשאות הנוספות הבאות:

  • ACCESS_FINE_LOCATION כדי לקבוע במדויק את מיקום המשתמש.

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

  • ACCESS_INTERNET כדי ליצור קשר עם שירות ARCore Geospatial API.

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

במכשירים עם Android בגרסה 12 ואילך, המשתמשים יכולים לבקש שלאפליקציה תהיה גישה רק למידע על מיקום משוער. כדי לתת מענה לבקשה הזו, צריך להגדיר באפליקציה את ההרשאה ACCESS_COARSE_LOCATION, יחד עם ACCESS_FINE_LOCATION, כפי שמתואר למעלה. עליכם להגדיר את שתי הרשאות המיקום.

עם זאת, כשמשתמשים מציינים מיקום משוער, הגדרה זו מונעת מה-API הגיאו-מרחבי לקבל את המיקום המדויק שנדרש. השירות הגיאו-מרחבי לא יאפשר לעצמו להגדיר את עצמו אם האפליקציה שלכם נותנת לו מיקום משוער בלבד. האפליקציה שלך לא יכולה להשתמש ב-Geospatial API עם מיקום משוער.

בדיקת הזמינות הגאו-מרחבית במיקום הנוכחי של המכשיר

ה-API הגיאו-מרחבי משתמש בשילוב של VPS ו-GPS כדי לקבוע תנוחה גיאו-מרחבית, ולכן אפשר להשתמש ב-API כל עוד המכשיר מסוגל לקבוע את המיקום שלו. באזורים עם רמת דיוק נמוכה ב-GPS, כמו שטחים פנימיים וסביבות עירוניות צפופות, ה-API יסתמך על כיסוי VPS כדי ליצור תנוחות ברמת דיוק גבוהה. בתנאים אופייניים, VPS יכול לספק דיוק מיקום של כ-5 מטרים ודיוק סיבוב של 5 מעלות. יש להשתמש ב-Session.checkVpsAvailabilityAsync() כדי לבדוק אם למיקום מסוים יש כיסוי VPS.

ניתן להשתמש ב-Geospatial API גם באזורים שאין בהם כיסוי VPS. בסביבות בחוץ שבהן יש מעט הפרעות מתקורה או שאין בהן הפרעות ממבט-על, ייתכן שה-GPS יספיק כדי ליצור תנוחה ברמת דיוק גבוהה.

המאמרים הבאים