מדריך למפתחים ב-Cloud anchors לטירגוט ל-Unity

זהירות: הדף הזה מתעד את ה-ARCore SDK ל-Unity, שהוצא משימוש וכבר לא נתמך ב-Unity 2020 ואילך. צריך להשתמש ב-SDK הזה רק עבור מפתחים שעובדים על פרויקטים קיימים שלא ניתן לעבור ל-AR&

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

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

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

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

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

• כדאי לבדוק אחת מהדוגמאות ל-Cloud עוגן

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

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

הפעלת עוגנים בענן באפליקציה

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

1. הפעלה של יכולות עוגן ב-Cloud בהגדרה של פעילות ב-AR.

2. המשך סשן AR.

אירוח עוגן בענן באמצעות התמדה

לפני ARCore SDK 1.20.0, אפשר לפתור בעיות ב-Cloud עוגן רק עד 24 שעות אחרי האירוח. בעזרת Cloud עוגן אפשר להשתמש עכשיו ב-XPSession.CreateCloudAnchor() כדי ליצור 'עוגן בענן' עם משך חיים (TTL) בין 1 ל-365 ימים.

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

// ttlDays: The anchor’s lifetime in days. Must be a positive number. The maximum
// allowed value is 1 if you are using an API key to authenticate the Cloud Anchor.
// Otherwise, the maximum allowed value is 365.

AsyncTask<CloudAnchorResult> GoogleARCore.CrossPlatform.XPSession.CreateCloudAnchor(
  UnityARUserAnchorComponent anchor, int ttlDays
)

אימות

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

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

שיטת האימות המוגדרת כברירת מחדל עבור פרויקטים חדשים של Unity שנבנתה באמצעות ARCore SDK מגרסה 1.24.0 ואילך היא לא להשתמש. המטרה היא למנוע יצירה של אפליקציות עם ספריות מיותרות.

אם האפליקציה שלך משתמשת ב-Cloud anchors ונבנתה באמצעות ARCore SDK מגרסה 1.24.0 ואילך, עליך להפעיל אימות באופן ידני Project Settings > XR Plug-in Management > ARCore Extensions.

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

האפשרות Authentication Token יכולה לארח עוגן בענן למשך עד 365 ימים.

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

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

• מנגנון האימות שלכם חייב להגן על נקודת הקצה.

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

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

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

כדי ליצור חשבון שירות Google ומפתח חתימה:

1. בתפריט הניווט של Google Cloud Platform Console, עוברים אל APIs & Services > Credentials.

2. בוחרים את הפרויקט הרצוי ולוחצים על Create Credentials > Service account.

3. בקטע Service account details, מקלידים שם לחשבון החדש ואז לוחצים על Create.

4. בדף Service account permissions, עוברים אל התפריט הנפתח Select a role. בוחרים את Service Accounts > Service Account Token Creator, ואז לוחצים על Continue.

5. בדף Grant users access to this service account לוחצים על Done. הלחיצה תחזיר אותך אל APIs & Services > Credentials.

6. בדף Credentials, יש לגלול למטה אל הקטע Service Accounts וללחוץ על שם החשבון שיצרת כרגע.

7. בדף Service account details, גוללים למטה אל הקטע Keys ובוחרים באפשרות Add Key > Create new key.

8. יש לבחור את סוג המפתח JSON וללחוץ על Create. הפעולה הזו מורידה קובץ JSON שמכיל את המפתח הפרטי למכונה שלך. מאחסנים את קובץ המפתח מסוג JSON שמורידים במיקום מאובטח.

   הערה: הקובץ הזה מכיל מפתח פרטי שלא ניתן לחשוף אותו לציבור. לא להתחייב למאגרים של קוד מקור כמו GitHub.

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

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

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

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

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcorecloudanchor.googleapis.com/"

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

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

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

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

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

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

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

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

1. חובה להעביר אסימון אימות תקף לפני ניסיון לארח או לפתור עוגן.

2. ARCore מתעלמת מהאסימונים לאימות שמכילים רווחים או תווים מיוחדים.

3. ARCore מתעלמת מהאסימונים לאימות שסופקו אם הסשן נוצר עם מפתח API תקין.

   אם השתמשתם בעבר במפתח API ואתם לא צריכים אותו יותר, מומלץ:

   • הסרה של ה-API מהאפליקציה לאחר העברת משתמשים לגרסה החדשה ביותר.
   • מחיקת מפתח ה-API ב-Google Cloud Platform Console

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

אחרי קבלת אסימון, צריך להעביר אותו לסשן ARCore באמצעות XPSession.SetAuthToken():

// Set the token to use when authenticating with the ARCore Cloud Anchor API
// on the iOS platform.
// This should be called each time the application's token is refreshed.
XPSession.SetAuthToken(string authToken);

אימות מפתח API

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

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

1. ניתן לעיין במרכז העזרה של Google Cloud Platform Console כדי לקבל מפתח API.

2. מוסיפים את מפתח ה-API החדש לפרויקט:

• ב-Unity, עוברים אל Edit > Project Settings > ARCore Project Settings.
• יש להוסיף את מפתח ה-API לשדה Cloud Anchor API Keys.

איכות המיפוי

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

FeatureMapQuality quality = GoogleARCore.CrossPlatform.XPSession.EstimateFeatureMapQualityForHosting(pose)

public enum FeatureMapQuality
{
    /// The quality of feature points identified from the pose in the preceding
    /// few seconds is low. This state indicates that ARCore will likely have
    /// more difficulty resolving the Cloud Anchor. Encourage the user to move the
    /// device, so that the desired position of the Cloud Anchor to be hosted is
    /// viewed from different angles.
    Insufficient = 0,

    /// The quality of feature points identified from the pose in the preceding
    /// few seconds is likely sufficient for ARCore to successfully resolve
    /// a Cloud Anchor, although the accuracy of the resolved pose will likely be
    /// reduced. Encourage the user to move the device, so that the desired position of
    /// the Cloud Anchor they wish to host can be viewed from different angles.
    Sufficient = 1,

    /// The quality of feature points identified from the pose in the preceding
    /// few seconds is likely sufficient for ARCore to successfully resolve
    /// a Cloud Anchor with a high degree of accuracy.
    Good = 2,
}

מכסות API

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

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

שיקולי ביצועים

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

השלבים הבאים

• מסמכי עזר של ARCore Unity