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

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

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

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

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

הפעלה של ARCore API

לפני שמשתמשים ב-Cloud Anchors באפליקציה, צריך להפעיל את ARCore API באפליקציה.

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

אחרי שמפעילים את הפונקציונליות של 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 מעבד את המידע הזה כדי ליצור מפת תכונות תלת-ממדית, ובסופו של דבר מחזיר למכשיר מזהה ייחודי של Cloud Anchor.

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

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

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

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

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

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

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

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

אפשר להתחיל פתרון של כמה Cloud Anchors ברצף. אפשר להריץ בו-זמנית עד 40 פעולות של Cloud Anchor.

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

כדי לבטל פעולת Cloud Anchor בהמתנה, צריך להתקשר למספר cancel(). כדי להסיר מהאפליקציה Cloud Anchor שכבר נפתר, קוראים ל-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 לא ניתן היה לפתור את Cloud Anchor כי גרסת ה-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 Anchor API.
  • אפליקציות שנוצרו באמצעות SDK 1.11.0 או גרסה ישנה יותר של ARCore לא יכולות לארח או לפתור עוגנים ב-Cloud בגלל שערכת ה-SDK משתמשת ב-ARCore API ישן יותר שהוצא משימוש.

מה השלב הבא?