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

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

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

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

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

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

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

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

הפעלה של ARCore API

לפני השימוש במערכת המיקום החזותי (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:

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

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

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

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

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

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

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

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

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

כדי להשתמש ב-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 משתמש בשילוב של VPS ו-GPS כדי לקבוע תנוחה גיאוספטית, אפשר להשתמש ב-API כל עוד המכשיר יכול לקבוע את המיקום שלו. באזורים שבהם רמת הדיוק של ה-GPS נמוכה, כמו מקומות סגורים וסביבות עירוניות צפופות, ה-API יתבסס על כיסוי VPS כדי ליצור תנוחות עם רמת דיוק גבוהה. בתנאים רגילים, ה-VPS צפוי לספק דיוק תלוי מיקום של כ-5 מטרים, ודיוק סיבובי של 5 מעלות. אפשר להשתמש ב-ArSession_checkVpsAvailabilityAsync() כדי לבדוק אם יש כיסוי של VPS במיקום נתון.

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

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