כדי לעמוד בדרישות הפרטיות המעודכנות שלנו לשימוש ב-ARCore SDK 1.12 ואילך, עליך לחשוף את השימוש ב-Cloud Anchors באופן בולט באפליקציה שלך. עיין בדרישות הפרטיות של Cloud Anchors לפרטים.

מדריך למפתחים ל-Cloud עוגנים ל-Android

בקישורים הבאים מוסבר איך להשתמש ב-ARCore Cloud anchor API או ב-ARCore Cloud anchor באפליקציות שלך.

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

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

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

הפעלת ARCore Cloud API API

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

כמו כן, צריך להפעיל יכולות של Cloud עוגן בתצורת הסשן של AR באפליקציה, כדי לתקשר עם ה-ARCore Cloud 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)

מתן הרשאה לאפליקציה לקרוא ל-ARCore Cloud עוגן API

צריך לתת לאפליקציה הרשאה לקרוא ל-ARCore Cloud עוגן API כדי לארח ולפתור את הענן. אפליקציות שמארחות ופותרות בעיות בענן עם TTL מעל יום אחד (1) חייבות להשתמש בהרשאה ללא מפתח.

הרשאה ללא מפתח

אפשר להשתמש בהרשאה ללא מפתח כדי לארח ולפתור עוגן בענן עם TTL בין 1 ל-365 ימים.

  1. הפעלת ARCore Cloud anchor API לפרויקט חדש או קיים ב-Google Cloud Platform.

  2. יוצרים מזהה לקוח ב-OAuth לאפליקציית Android שלכם ב-Google Cloud Console, באמצעות מזהה האפליקציה וחתימת SHA-1 של האישור. פעולה זו משייכת את האפליקציה ל-Android בפרויקט ב-Google Cloud Platform.

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

    • פותחים את ארגז הכלים של גראד בפרויקט Android Studio שלכם.
    • מנווטים אל <project-name> > Tasks > android.
    • מריצים את המשימה SignatureReport.

    • מעתיקים את טביעת האצבע SHA-1 עבור הווריאנט ניפוי באגים בשדה טביעת אצבע לאישור SHA-1 ב-Google Cloud Console.

  3. מציינים את com.google.android.gms:play-services-auth:16+ בהתאם לתלויות של האפליקציה.

  4. אם נעשה שימוש ב-Proguard, צריך להוסיף אותו לקובץ build.gradle של האפליקציה באמצעות

    buildTypes {
  release {
    ...
    proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
  }
}

    יש להוסיף את הפרטים הבאים לקובץ proguard-rules.pro של האפליקציה:

    -keep class com.google.android.gms.common.** { *; }
-keep class com.google.android.gms.auth.** { *; }
-keep class com.google.android.gms.tasks.** { *; }

הרשאת מפתח API

שימוש בהרשאה למפתח API לאירוח ופתרון עוגנים בענן עם TTL עד 24 שעות (יום 1).

  1. הפעלת ARCore Cloud anchor API לפרויקט חדש או קיים ב-Google Cloud Platform.
  2. השגת מפתח API לפרויקט הזה ב-Google Cloud Console.

  3. ב-Android Studio, מוסיפים את מפתח ה-API החדש לפרויקט. יש לכלול את מפתח ה-API ברכיב <meta-data> ברכיב <application> באפליקציה app/manifests/AndroidManifest.xml של #:3

    <meta-data
   android:name="com.google.android.ar.API_KEY"
   android:value="API_KEY"/>

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

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

אתם יכולים גם להתקשר אל hostCloudAnchor() כדי לארח עוגן עם TTL עד 24 שעות (יום 1), או להאריך את כל משך הזמן של עוגן מתארח באמצעות ARCore Cloud anchor Management API.

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

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

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

פתרון עוגן שהוזמן בעבר

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

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

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

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

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

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

ערך תיאור
ERROR_CLOUD_ID_NOT_FOUND הפתרון נכשל כי לא ניתן היה למצוא את מזהה העוגן בענן של ARCore Cloud.
ERROR_HOSTING_DATASET_PROCESSING_FAILED האירוח נכשל כי השרת לא הצליח לעבד את מערך הנתונים עבור העוגן הנתון. יש לנסות שוב אחרי שהמכשיר יאסוף עוד נתונים מהסביבה.
ERROR_HOSTING_SERVICE_UNAVAILABLE לא ניתן היה לגשת ל-ARCore Cloud עוגן API. מספר סיבות עלולות לגרום לבעיה. ייתכן שהמכשיר במצב טיסה או שאין לו חיבור תקין לאינטרנט. ייתכן שפג הזמן הקצוב של הבקשה שנשלחה לשרת בלי תגובה. ייתכן שהחיבור לרשת מקוטע, ה-DNS לא זמין, יש בעיות של חומת אש או כל דבר אחר שעשוי להשפיע על היכולת של המכשיר להתחבר ל-ARCore Cloud עוגן API.
ERROR_INTERNAL אירוח או פתרון של עוגן זה הסתיים עם שגיאה פנימית. האפליקציה לא יכולה לנסות לשחזר מהשגיאה הזו.
ERROR_NOT_AUTHORIZED ההרשאה שסופקה על ידי האפליקציה אינה חוקית.
  • ייתכן שפרויקט Google Cloud לא הפעיל את ARCore Cloud עוגן API או שהפעולה שניסית לבצע אינה מותרת.
  • אם משתמשים בהרשאת מפתח API: מפתח ה-API במניפסט אינו חוקי, לא מורשה או חסר. בנוסף, ייתכן שהפעולה הזו תיכשל אם מפתח ה-API מוגבל לקבוצת אפליקציות שאינן כוללות את האפליקציה הנוכחית.
  • אם משתמשים בהרשאה ללא מפתח: לא הצלחתם ליצור לקוח OAuth.
  • Google Play Services לא מותקנת, ישנה מדי או לא תקינה מסיבה כלשהי (למשל, שירותים שנפלו עקב לחץ זיכרון).
ERROR_RESOLVING_SDK_VERSION_TOO_NEW לא ניתן היה לפענח את העוגן בענן כי גרסת ה-SDK שמשמשת לפתרון העוגן חדשה יותר, ולכן היא לא תואמת לגרסה המשמשת לאירוח שלו.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD לא ניתן לפענח את ה-Cloud עוגן כי גרסת ה-SDK המשמשת לפתרון העוגן ישנה יותר, ולכן לא תואמת לגרסה המשמשת לאירוח שלו.
ERROR_RESOURCE_EXHAUSTED האפליקציה מיצתה את מכסת הבקשות שהוקצו לפרויקט Google Cloud הנתון. עליך לבקש עוד מכסה ל-ARCore Cloud API API לפרויקט שלך מ-Google Developers Console.
NONE העוגן הוא מקומי בלבד. הוא מעולם לא מתארח באמצעות hostCloudAnchor() ולא נפתר באמצעות resolveCloudAnchor().
SUCCESS אירוח או פתרון של עוגן זו הושלם בהצלחה.
TASK_IN_PROGRESS מתבצע אירוח או פתרון של אירועי עוגן. כשהמשימה תבוצע ברקע, העוגן יקבל מצב ענן חדש אחרי השיחה הבאה אל Session.update().

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

ל-ARCore Cloud עוגן API יש את המכסות הבאות לרוחב הפס:

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

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

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

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

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

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

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

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

מה השלב הבא?