מדריך למפתחים של Cloud anchors ל-Android (Kotlin/Java)

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

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

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

אם זו הפעם הראשונה שאתם משתמשים בעוגנים של Cloud:

הפעלה של ARCore API

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

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

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

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

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

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

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

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

  1. קוראים לפונקציה hostCloudAnchorAsync().
  2. ממתינים לקריאה החוזרת או בודקים כל הזמן את המצב העתידי עד שהוא מסתיים.
  3. בדיקת מצב התוצאה כדי לקבוע אם הפעולה הצליחה, או לפרש את קוד השגיאה אם היא נכשלה.
  4. שיתוף מזהה ה-Cloud עוגן של התוצאה עם לקוחות אחרים ושימוש בו כדי לפענח את העוגן של Cloud עם resolveCloudAnchorAsync()

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

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

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

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

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

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

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

קוראים לפונקציה cancel() כדי לבטל פעולה שנמצאת בהמתנה ב-Cloud עוגן. קוראים לפונקציה detach() כדי להסיר מהאפליקציה עוגן בענן שכבר נפתר.

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

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

ערך תיאור
ERROR_CLOUD_ID_NOT_FOUND הפתרון נכשל כי ARCore API לא הצליח למצוא את מזהה ה-Cloud עוגן שסופק.
ERROR_HOSTING_DATASET_PROCESSING_FAILED האירוח נכשל כי השרת לא הצליח לעבד את מערך הנתונים עבור העוגן הנתון. אפשר לנסות שוב אחרי שהמכשיר יאסוף יותר נתונים מהסביבה.
ERROR_HOSTING_SERVICE_UNAVAILABLE לא ניתן היה לגשת ל-ARCore API. מספר סיבות עלולות לגרום לכך. ייתכן שהמכשיר נמצא במצב טיסה או שאין לו חיבור פעיל לאינטרנט. ייתכן שתם הזמן הקצוב לבקשה שנשלחה לשרת ולא התקבלה תגובה. ייתכן שיש חיבור לא טוב לרשת, אי זמינות של DNS, בעיות בחומת אש או כל דבר אחר שעשוי להשפיע על יכולת המכשיר להתחבר ל-ARCore API.
ERROR_INTERNAL משימת אירוח או פתרון של העוגן הזה הסתיימה עם שגיאה פנימית. האפליקציה לא צריכה לנסות להתאושש מהשגיאה הזו.
ERROR_NOT_AUTHORIZED ההרשאה שסופקה על ידי האפליקציה לא תקפה. ראו פתרון בעיות הקשורות להרשאה של ARCore API.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW לא ניתן היה לפתור את הבעיה בעוגן של Cloud כי גרסת ה-SDK שמשמשת לפענוח העוגן חדשה יותר מהגרסה ששימשה לאירוח העוגן ולא תואמת לה.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD לא ניתן היה לפתור את הבעיה בעוגן של הענן כי גרסת ה-SDK שמשמשת לפענוח העוגן ישנה יותר מהגרסה ששימשה לאירוח העוגן ולא תואמת לה.
ERROR_RESOURCE_EXHAUSTED האפליקציה מיצה את מכסת הבקשות שהוקצתה לפרויקט הנתון ב-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 שהוצא משימוש.

מה השלב הבא?