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

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

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

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

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

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

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

לצפייה מבוא ל-API Geospatial – מידע נוסף מידע על ה-API הגיאו-מרחבי.

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

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

הפעלת ה-API של ARCore

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

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

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

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

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

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, כפי שמתואר במדריך למתחילים.

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

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

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

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

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

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