המדריך למפתחים של Cloud anchors ל-Unity (AR Foundation)

רוצים לדעת איך משתמשים במודעות עוגן בענן באפליקציות שלכם?

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

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

אם זו הפעם הראשונה שאתם משתמשים ב-Cloud anchors, חשוב לוודא שאתם מבינים איך פועלים מודעות עוגן ומודעות עוגן בענן.

הפעלת ARCore API

כדי להשתמש ב-Cloud anchors באפליקציה, צריך קודם להפעיל את ARCore API באפליקציה.

הפעלת יכולות של Cloud עוגן בהגדרות הסשן

לאחר שהפעלתם באפליקציה את הפונקציונליות של Cloud anchors, עליכם להפעיל את היכולות של Cloud anchors בהגדרות של פעילות ה-AR באפליקציה כדי שהיא תוכל לתקשר עם ARCore API:

אירוח של Cloud עוגן

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

אפשר גם להאריך את משך החיים של עוגן מתארח באמצעות ARCore Cloud anchor Management API.

כדי להשלים את האירוח של Cloud עוגן, האפליקציה צריכה לבצע את השלבים הבאים:

  1. קוראים לפונקציה ARAnchorManager.HostCloudAnchorAsync().
  2. כדאי להתחיל שגרת חזרה ולהמתין עד שה-Promise תשיג תוצאה. מידע נוסף זמין במאמר Coroutines ב-Unity.
  3. יש לבדוק את מצב התוצאה כדי לראות אם הפעולה הצליחה, או לפרש את קוד השגיאה אם היא נכשלה.
  4. אפשר לשתף את מזהה ה-Cloud anchor של התוצאה עם לקוחות אחרים, ולהשתמש בו כדי לתקן את ה-Cloud anchor באמצעות ARAnchorManagerExtensions.ResolveCloudAnchorAsync().

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

ARCoreExtensions.FeatureMapQuality מציין את האיכות של נקודות מהתכונות שנצפו על ידי ARCore בשניות הקודמות מתנוחה נתונה במצלמה. בדרך כלל, תגובות עוגן בענן שמתארחות בתכונות באיכות גבוהה יותר יטופלו בצורה מדויקת יותר. באמצעות ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() ניתן לקבל הערכה לגבי איכות מפת התכונות בתנוחת מצלמה נתונה.

Value תיאור
Insufficient איכות הנקודות על התכונות שזוהו מהתנוחה במספר השניות הקודמות היא נמוכה. המצב הזה מצביע על כך שככל הנראה ARCore יתקשה יותר לפתור את העוגן בענן. כדאי לעודד את המשתמשים להזיז את המכשיר כדי שניתן יהיה לצפות במיקום הרצוי של ה-Cloud עוגן שהוא רוצה לארח מזוויות שונות.
Sufficient סביר להניח שהאיכות של נקודות הפיצ'ר שזוהו מהתנוחה במספר השניות הקודמות תספיק ל-ARCore כדי לפענח בהצלחה עוגן בענן, אם כי סביר להניח שהדיוק של התנוחה שטופלה יפחת. כדאי לעודד את המשתמשים להזיז את המכשיר כדי שניתן יהיה לצפות במיקום הרצוי של ה-Cloud עוגן שהוא רוצה לארח מזוויות שונות.
Good סביר להניח שהאיכות של נקודות הפיצ'ר שזוהו מהתנוחה בשניות הקודמות תספיק ל-ARCore כדי לתקן עוגן בענן ברמת דיוק גבוהה.

תיקון עוגן שמתארח בעבר

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

אפשר ליזום ברצף מספר הגדרות של עוגנים בענן. יכולות להתקיים עד 40 פעולות בו-זמניות של Cloud עוגן.

ביטול פעולה או הסרה של Cloud עוגן

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

בדיקת מצב התוצאה של פעולה של Cloud anchor

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

Value תיאור
ErrorResolvingCloudIdNotFound פתרון הבעיה נכשל כי ממשק ה-API של ARCore לא מצא את מזהה ה-Cloud עוגן שסופק.
ErrorHostingDatasetProcessingFailed האירוח נכשל כי השרת לא הצליח לעבד את מערך הנתונים עבור העוגן הנתון. יש לנסות שוב אחרי שהמכשיר יאסוף עוד נתונים מהסביבה.
ErrorHostingServiceUnavailable לא ניתן היה לגשת ל-ARCore API. מספר סיבות עלולות לגרום לבעיה. ייתכן שהמכשיר במצב טיסה או שאין לו חיבור פעיל לאינטרנט. ייתכן שתם הזמן הקצוב לתפוגה של הבקשה שנשלחה לשרת ולא התקבלה תגובה. יכול להיות שיש חיבור רשת בעייתי, חוסר זמינות ב-DNS, בעיות בחומת האש או כל דבר אחר שעלול להשפיע על היכולת של המכשיר להתחבר ל-ARCore API.
ErrorInternal משימת אירוח או פתרון של עוגן זה הסתיימה עם שגיאה פנימית. האפליקציה לא אמורה לנסות לשחזר את השגיאה.
ErrorNotAuthorized האפליקציה לא יכולה לתקשר עם ממשק ה-API של ARCore בגלל הרשאה לא חוקית. עוברים לקטע Project Settings (הגדרות הפרויקט) > XR > ARCore extensions (תוספי ARCore) כדי לבדוק אם יש אסטרטגיית הרשאה חוקית.
ErrorResolvingPackageTooNew לא ניתן היה לפתור את העוגן בענן כי החבילה של תוספי ARCore שמשמשת לפתרון 'עוגן בענן' חדשה יותר מהגרסה שבה נעשה שימוש לאירוח של ה-Cloud עוגן ולא תואמת לה.
ErrorResolvingPackageTooOld לא ניתן היה לפתור את הבעיה ב'עוגן בענן' כי החבילה של תוספי ARCore שמשמשת לפתרון 'עוגן בענן' ישנה יותר מהגרסה שבה נעשה שימוש לאירוח של Cloud ולא תואמת לה.
ErrorResourceExhausted האפליקציה מיצתה את מכסת הבקשות שהוקצתה לפרויקט Google Cloud שצוין. עליך לבקש מכסה נוספת ל-ARCore API לפרויקט שלך דרך Google Developers Console.
Success משימת אירוח או פתרון של עוגן זה הושלמה בהצלחה.

מכסות API למארחים ובקשות לטיפול

ל-ARCore API יש את המכסות הבאות לרוחב הפס של בקשות:

סוג המכסה מקסימום משך הזמן תחולה
מספר הדיבלים ללא הגבלה לא רלוונטי פרויקט
בקשות מארח עוגן 30 דקה כתובת IP ופרויקט
עוגן בקשות resolve 300 דקה כתובת IP ופרויקט

שיטות מומלצות לשיפור חוויית המשתמש

הנחה את המשתמשים לבצע את הפעולות הבאות כדי להבטיח חוויית משתמש טובה באפליקציה:

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

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

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

מדיניות הוצאה משימוש

  • אפליקציות שפותחו עם ARCore SDK מגרסה 1.12.0 ואילך כפופות למדיניות ההוצאה משימוש של Cloud anchor API.
  • אפליקציות שפותחו באמצעות SDK מגרסה 1.11.0 ומטה של ARCore לא יכולות לארח או לטפל בעוגנים בענן, בגלל השימוש ב-ARCore API ישן יותר שהוצא משימוש.

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