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

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

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

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

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

הפעלה של ARCore API

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

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

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

אירוח עוגן בענן

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

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

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

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

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

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

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

סימון שהנושא טופל בעוגן שמתארח בעבר

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

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

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

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

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

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

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

מכסות API לבקשות למארח ולפתרון

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

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

שיטות מומלצות לחוויית משתמש טובה

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

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

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

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

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

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

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