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

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

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

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

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

הפעלת ה-API של ARCore

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ערך תיאור
ERROR_CLOUD_ID_NOT_FOUND הפתרון נכשל כי ARCore API לא הצליח למצוא את מזהה Cloud Anchor שצוין.
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 Anchor כי גרסת ה-SDK ששימשה לפתרון העוגן חדשה יותר מהגרסה ששימשה לאירוח שלו, והיא לא תואמת לה.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD לא ניתן היה לפתור את Cloud Anchor כי גרסת ה-SDK ששימשה לפתרון העוגן ישנה יותר מהגרסה ששימשה לאירוח שלו, והיא לא תואמת לה.
ERROR_RESOURCE_EXHAUSTED האפליקציה חריגה ממכסת הבקשות שהוקצה לפרויקט Google Cloud הנתון. עליך לבקש מכסה נוספת ל-ARCore API של הפרויקט שלך ב-Google Developers Console.
SUCCESS משימה של אירוח או פתרון של ציר ה-anchor הזה הושלמה בהצלחה.

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

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

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

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

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

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

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

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

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

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

מה השלב הבא?