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

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

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

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

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

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

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

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

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

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

הפעלת ה-API של ARCore

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

מומלץ להשתמש בהרשאה ללא מפתח, אבל יש תמיכה גם בהרשאה באמצעות מפתח API.

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

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

בקובץ build.gradle של האפליקציה, מגדירים את Google Play Services כך שיכלול את ספריית המיקום של 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:

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

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

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

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

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

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

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

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

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

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

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

  • ACCESS_COARSE_LOCATION לצורך קביעת מיקום המשתמש באופן לא מדויק ובהתאם לדרישות הפרטיות של המשתמשים. עם זאת, אי אפשר להגדיר את Geospatial 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, כפי שמתואר למעלה. עליכם להגדיר את שתי הרשאות המיקום.

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

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

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

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

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