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

מדריך למפתחים של Cloud עוגן לתוספים של ARCore ל-iOS

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

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

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

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

הפעלת ARCore Cloud עוגן API

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

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

  1. מוודאים שתיקיית הנכסים של הפרויקט מכילה אובייקט סקריפט של ARCoreExtensionsConfig. כדי ליצור נכס, לוחצים לחיצה ימנית בחלונית נכסים ובוחרים באפשרות יצירה > ARCore extensions > ARCore extensions Config.
  2. בוחרים באובייקט ARCoreExtensionsConfig בתיקייה נכסים ומגדירים את מצב העוגן בענן כמופעל.
  3. צריך להגדיר את האובייקט של ARCore extensions לשימוש בתצורה ARCoreExtensionsConfig. בחלונית היררכיות, מאתרים את אובייקט המשחק ARCore extensions שיצרתם כשהגדרתם את תוספי ARCore, ומחברים את השדה ARCore extensions Config לאובייקט הסקריפט ARCoreExtensionsConfig בתיקייה נכסים.

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

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

הרשאת אסימון (JWT חתום)

צריך להשתמש בהרשאה לאסימון (חתום ב-JWT) כדי לארח ולפתור עוגנים בענן באמצעות TTL בין 1 ל-365 ימים. נכון לעכשיו, סוג האסימון הנתמך היחיד הוא אסימון אינטרנט מסוג JSON (JWT). אסימון זה חייב להיות חתום על ידי חשבון שירות של Google.

  1. עוברים אל Edit (עריכה) > Project Settings (הגדרות הפרויקט) > XR הפלאגין Plugins ו-gt; ARCore extensions ומסמנים את התמיכה ב-iOS מופעלת.

  2. בתפריט הנפתח שיטת אימות ב-iOS, בוחרים באפשרות אסימון אימות.

דרישות לגבי נקודות קצה של שרת

כדי ליצור אסימונים ל-iOS, צריכה להיות לך נקודת קצה בשרת שעומדת בדרישות הבאות:

  1. מנגנון ההרשאה שלכם מגן על נקודת הקצה.
  2. נקודת הקצה חייבת ליצור אסימון חדש בכל פעם שכל משתמש יקבל אסימון ייחודי, והתוקף של אסימונים אלה לא יפוג באופן מיידי.

יצירת חשבון שירות ומפתח חתימה

יש לבצע את השלבים הבאים כדי ליצור חשבון שירות Google ומפתח חתימה.

  1. בתפריט הניווט של Google Cloud Platform Console, עוברים אל APIs & Services > credentials (פרטי כניסה).
  2. בוחרים את הפרויקט הרצוי ולוחצים על יצירת פרטי כניסה > חשבון שירות.
  3. בקטע פרטי חשבון השירות, מקלידים שם לחשבון החדש ולוחצים על יצירה.
  4. בדף הרשאות לחשבון שירות, עוברים לתפריט הנפתח בחירת תפקיד. בוחרים באפשרות Service Account> Service Account Token Token ולוחצים על Continue.
  5. בדף הענקת גישה למשתמשים לחשבון השירות הזה, לוחצים על סיום. פעולה זו תחזיר אתכם אל APIs & Services > פרטי כניסה.
  6. בדף פרטי כניסה, גוללים למטה לקטע חשבונות שירות ולוחצים על שם החשבון שיצרתם.
  7. בדף פרטי חשבון שירות, גוללים למטה אל הקטע מפתחות ובוחרים באפשרות הוספת מפתח &gt. יצירת מפתח חדש.
  8. בוחרים באפשרות JSON בתור סוג המפתח ולוחצים על Create (יצירה). מתבצעת הורדה של קובץ JSON שמכיל את המפתח הפרטי למחשב. יש לאחסן את קובץ מפתח ה-JSON שהורדת במיקום מאובטח.

קובץ ה-JSON מכיל מפתח פרטי שאסור לחשוף לציבור. אין להתחייב לשימוש במאגרי קוד מקור כמו GitHub.

יצירת אסימונים בשרת

כדי ליצור אסימונים חדשים (JWT) בשרת, השתמשו בספריות JWT הרגילות ובקובץ ה-JSON שהורדתם באופן מאובטח מחשבון השירות החדש.

יצירת אסימונים במכשיר הפיתוח שלך

כדי ליצור JWT במכונת הפיתוח, משתמשים בפקודה oauth2l הבאה:

// "oauth2l" uses a lowercase L, not a 1, as the last character.
// Specifying an empty cache location using the --cache flag is necessary
// to ensure that a different token is produced each time.
oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcorecloudanchor.googleapis.com/"

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

חתימה על האסימון

כדי לחתום על ה-JWT, יש להשתמש באלגוריתם RS256 ובתלונות הבאות:

  • iss — כתובת האימייל של חשבון השירות.
  • sub — כתובת האימייל של חשבון השירות.
  • iat — זמן ה-Unix שבו נוצר האסימון, בשניות.
  • expiat + 3600 (שעה אחת). פרק הזמן שבו תוקף האסימון יפוג בשניות.
  • aud — הקהל. חייב להיות https://arcorecloudanchor.googleapis.com/.

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

אם אתם משתמשים בגישה אחרת ליצירת מסמכי JWT, כמו שימוש ב-Google API בסביבה שמנוהלת על ידי Google, חשוב לחתום על ה-JWTs עם התלונות שבקטע הזה. מעל הכול, צריך לוודא שהקהל נכון.

העברת אסימון לסשן ARCore

כשמקבלים אסימון, צריך להעביר אותו לסשן ה-ARCore שלך באמצעות ARAnchorManager.SetAuthToken():

// Designate the token to use when authorizing the ARCore Cloud Anchor API call
// on the iOS platform. The API should be called each time the application's token is refreshed.
ARAnchorManager.SetAuthToken(string authToken);

חשוב לשים לב לנקודות הבאות כשמעבירים אסימון לסשן:

  • עליך להעביר אסימון הרשאה תקף לפני ניסיון לארח או לפתור עוגן.
  • מערכת ARCore מתעלמת מאסימוני הרשאות שמכילים רווחים או תווים מיוחדים.
  • מערכת ARCore מתעלמת מאסימוני ההרשאה שסופקו אם הסשן נוצר באמצעות מפתח API תקין. אם השתמשתם בעבר במפתח API ואין לכם צורך בו, מומלץ למחוק אותו ב-Google Cloud Platform Console ולהסיר אותו מהאפליקציה לאחר העברת המשתמשים לגרסה החדשה ביותר.
  • בדרך כלל תוקף האסימונים פג לאחר שעה. אם יכול להיות שתוקף האסימון שלך יפוג, עליך להשתמש באסימון חדש ולהתקשר אל ARAnchorManager.SetAuthToken(string authToken) עם האסימון החדש.

הרשאת מפתח API

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

שיטת ההרשאה המוגדרת כברירת מחדל לפרויקטים חדשים של Unity שנבנתה באמצעות ARCore SDK 1.24.0 ואילך היא DoNotUse. זאת כדי למנוע בניית אפליקציות עם ספריות מיותרות. אם האפליקציה שלכם משתמשת ב-Cloud עוגן ובנויה באמצעות ARCore SDK בגרסה 1.24.0 ואילך, עליכם להפעיל באופן ידני את ההרשאה בהגדרות הפרויקט > XR Plugins Plugins > ARCore extensions.

  1. עוברים אל Edit (עריכה) > Project Settings (הגדרות הפרויקט) > XR הפלאגין Plugins ו-gt; ARCore extensions ומסמנים את התמיכה ב-iOS מופעלת.

  2. בתפריט הנפתח אסטרטגיית אימות ל-iOS, בוחרים באפשרות מפתח API.

  3. יש לקבל מפתח API לפרויקט הזה מ-Google Cloud Console.

  4. עוברים אל Edit (עריכה) > Project Settings (הגדרות הפרויקט) ו-gt; XR הפלאגין Plugins > ARCore extensions ומוסיפים את מפתח ה-API לשדה Cloud עוגן API Keys (מפתחות ענן ב-Cloud עוגן).

אירוח עוגן של ענן

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

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

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

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

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

פתרון עוגן שהיה מתארח בעבר

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

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

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

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

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

כדי לבדוק את הסטטוס של העוגן המתארח או את הבקשה לפתרון, כולל שגיאות, כולל ARCloudanchor.cloudanchorState() .

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

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

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

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

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

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

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

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

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

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

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