שימוש ב-ARCore API ב-Google Cloud

בחירת פלטפורמה: Android Unity (AR Foundation) iOS

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

המדריך למתחילים הזה מתאר איך להגדיר את האפליקציה כך לתקשר עם שירות ARCore API שמתארח ב-Google Cloud.

יצירת פרויקט חדש ב-Google Cloud או שימוש בפרויקט קיים

אם יש פרויקט קיים, בוחרים אותו.

כניסה לדף לבחירת הפרויקט

אם אין לכם פרויקט ב-Google Cloud, אתם צריכים ליצור פרויקט קיים.

יצירת פרויקט חדש

הפעלה של ARCore API

כדי להשתמש ב-ARCore API, צריך להפעיל אותו בפרויקט.

הפעלה של ARCore API

הגדרה של שיטת הרשאה

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

• ב-Android, הרשאה ללא מפתח משתמשת בשילוב של שם החבילה של האפליקציה ואת טביעת האצבע של מפתח החתימה כדי לאשר את האפליקציה.

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

• מפתח API הוא מחרוזת שמזהה פרויקט ב-Google Cloud. מפתחות ה-API הם: בדרך כלל לא נחשבים מאובטחים, כי בדרך כלל הם נגישים ללקוחות. כדאי להשתמש בהרשאה ללא מפתח כדי לתקשר עם ARCore API.

ללא מפתחללא מפתחמפתח ממשק API

כדי לאשר את האפליקציה באמצעות אימות ללא מפתח, צריך ליצור לקוח OAuth 2.0 המזהים.

קביעת טביעות האצבעות של מפתח החתימה

מזהה לקוח ב-OAuth 2.0 משתמש בטביעת האצבע של מפתח החתימה של האפליקציה כדי לזהות את אפליקציה.

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

איך מקבלים את טביעת האצבע לחתימת ניפוי באגים

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

משתמשים בפקודה הבאה כדי לקבל את טביעת האצבע לאישור של ניפוי באגים.

Mac/Linuxחלונות

keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore

keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

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

   Certificate fingerprint: SHA1: <strong>DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

איך מקבלים טביעת אצבע ממאגר מפתחות

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

keytool -list -v -alias your-key-name -keystore path-to-production-keystore

לאחר מכן אפליקציית השירות keytool מדפיסה את טביעת האצבע בטרמינל. לדוגמה:

   Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

איך לקבל את חתימת האפליקציה מהתכונה 'חתימת אפליקציה ב-Play'

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

1. בדף חתימת אפליקציה ב-Google Play Console, גוללים אל אישור חתימת אפליקציה.
2. משתמשים בטביעת האצבע לאישור SHA-1.

יצירת מזהי לקוחות ב-OAuth 2.0

עבור כל מפתח חתימה רלוונטי מהשלבים הקודמים, צריך ליצור מזהה לקוח OAuth 2.0 ב פרטי הכניסה לפרויקט ב-Google Cloud.

• ב-Google Cloud, פותחים את הדף Credentials.

  פרטי כניסה

• לוחצים על Create credentials ובתפריט בוחרים באפשרות OAuth client ID.

• ממלאים את שדות החובה באופן הבא:

  • Application type (סוג האפליקציה): בוחרים באפשרות Android.
  • Package name: יש להשתמש בשם החבילה כפי שהוצהר ב-AndroidManifest.xml.
  • טביעת אצבע לאישור SHA-1: צריך להשתמש בטביעת אצבע שקיבלתם בשלבים הקודמים.

• לוחצים על Create.

לכלול את הספריות הנדרשות

1. יש לכלול את com.google.android.gms:play-services-auth:16+ ביחסי התלות של האפליקציה שלך.

2. אם אתם משתמשים בהקטנת קוד, הוסף אותו לקובץ build.gradle של האפליקציה שלך:

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

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

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

האפליקציה שלך מוגדרת עכשיו לשימוש באימות ללא מפתח.

ARCore תומך בהרשאה של קריאות ל-API ב-iOS באמצעות (JSON Web) ). האסימון חייב להיות חתום על ידי Google חשבון שירות.

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

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

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

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

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

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

1. ב-Google Cloud, פותחים את הדף Credentials.
   פרטי כניסה
2. לוחצים על Create Credentials > חשבון שירות.
3. בקטע פרטי חשבון שירות, מקלידים שם לחשבון החדש ולוחצים על יצירה.
4. בדף 'הרשאות חשבון שירות', לוחצים על התפריט הנפתח בחירת תפקיד. בוחרים באפשרות חשבונות שירות > יצירת אסימונים בחשבון שירות, ואז לוחצים על המשך.
5. בדף Grant users access to this service account, לוחצים על Done.
6. בדף Credentials מוצאים את הקטע 'חשבונות שירות' ולוחצים על שם החשבון שאתם יצרתם.
7. בדף Service account details, גוללים למטה לקטע 'מפתחות'. בוחרים באפשרות הוספת מפתח > יצירת מפתח חדש.

8. בוחרים באפשרות JSON בתור סוג המפתח ולוחצים על יצירה.

   תתבצע הורדה של קובץ JSON שמכיל את המפתח הפרטי למחשב שלכם. חנות את קובץ מפתח ה-JSON שהורדתם נמצא במיקום מאובטח.

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

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

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

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

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

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

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

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

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

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

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

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

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

1. מוודאים שאסטרטגיית האימות ל-iOS מוגדרת לערך AuthenticationToken. ב-Unity, עוברים אל Edit (עריכה) > (עריכה) הגדרות פרויקט > ניהול יישומי פלאגין של XR > ARCore extensions (תוספי ARCore). בתפריט הנפתח אסטרטגיית אימות ל-iOS בוחרים באפשרות Authentication Token.

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

   // Designate the token to authorize ARCore API calls
   // on the iOS platform. This should be called each time the application's token is refreshed.
   ARAnchorManager.SetAuthToken(authToken);
   

האפליקציה שלך מוגדרת עכשיו לשימוש באימות ללא מפתח.

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

• אם השתמשתם במפתח API כדי ליצור את הסשן, ARCore תתעלם ולרשום שגיאה.

  אם אתם לא צריכים יותר את מפתח ה-API, אפשר למחוק אותו מ-Google Developers המסוף ומסירים אותו אפליקציה.

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

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

1. ב-Google Cloud, פותחים את הדף Credentials.
   פרטי כניסה
2. לוחצים על Create credentials ובתפריט בוחרים באפשרות API key.
   תיבת הדו-שיח של מפתח API שנוצר מציגה את המחרוזת של המפתח החדש שיצרתם.

3. ב-Unity, עוברים אל Edit (עריכה) > (עריכה) הגדרות פרויקט > ניהול יישומי פלאגין של XR > ARCore extensions (תוספי ARCore). לכל פלטפורמת יעד (Android, iOS), בתפריט הנפתח אסטרטגיית אימות בוחרים באפשרות מפתח API. לאחר מכן: מזינים את מפתח ה-API בשדות של מפתח ה-API.

4. מסמכי העזרה בנושא הגבלות על מפתחות API כדי לאבטח את מפתח ה-API.

האפליקציה שלך מוגדרת עכשיו לשימוש במפתחות API.

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

אחרי שההרשאה מוגדרת, אפשר לבדוק את תכונות ARCore הבאות שמשתמשות זה:

• API גיאו-מרחבי
• Cloud GCM API