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

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

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

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

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

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

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

אם עוד אין לכם פרויקט קיים ב-Google Cloud, אפשר ליצור פרויקט כזה.

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

הפעלת ARCore API

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

הפעלה של ARCore API

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

אפליקציית Unity יכולה לתקשר עם ה-API של ARCore באמצעות שתי שיטות הרשאה שונות: הרשאה ללא מפתח (Keyless) – השיטה המומלצת, והרשאה באמצעות מפתח API:

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

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

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

ללא מפתח

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

זיהוי טביעות אצבע לחתימה

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

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

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

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

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

Mac/Linux

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

Windows

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 App Signing

כשמשתמשים בחתימת אפליקציה ב-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.

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

  • סוג האפליקציה: בוחרים Android.
  • שם החבילה: יש להשתמש בשם החבילה כפי שהוצהר בקובץ AndroidManifest.xml.
  • טביעת אצבע לאישור SHA-1: יש להשתמש בטביעת אצבע שהושגה בשלבים הקודמים.

• לוחצים על יצירה.

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

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. האסימון חייב להיות חתום על ידי חשבון שירות של Google.

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

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

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

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

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

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

1. ב-Google Cloud, פותחים את הדף Credentials.
   פרטי כניסה
2. לוחצים על Create Credentials > Service account.
3. בקטע Service account details, מזינים שם לחשבון החדש ולוחצים על Create.
4. בדף ההרשאות של חשבון השירות, לוחצים על התפריט הנפתח בחירת תפקיד. בוחרים באפשרות Service Accounts > Service Account Token Creator (יצירת אסימונים בחשבון שירות) ולוחצים על Continue (המשך).
5. בדף הענקת גישה למשתמשים לחשבון השירות הזה, לוחצים על 'סיום'.
6. בדף Credentials, מאתרים את הקטע Service Accounts ולוחצים על שם החשבון שיצרתם.
7. בדף Service account details, גוללים למטה אל הקטע Keys ולוחצים על Add Key > Create new key.

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 – פרק הזמן של מערכת Unix, בשניות, שבו נוצר האסימון.
• exp – iat + 3600 (שעה אחת). משך הזמן של מערכת Unix, בשניות, שבו יפוג תוקף האסימון.
• aud - הקהל. הערך צריך להיות https://arcore.googleapis.com/.

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

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

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

1. מוודאים ששיטת האימות של iOS מוגדרת לערך AuthenticationToken. ב-Unity, עוברים אל Edit (עריכה) > Project Settings (הגדרות הפרויקט) > XR Plugins Management > תוספי ARCore. בתפריט הנפתח iOS Authentication Strategy, בוחרים באפשרות 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.

מפתח ממשק API

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

3. ב-Unity, עוברים אל Edit (עריכה) > Project Settings (הגדרות הפרויקט) > XR Plug-in Management (ניהול פלאגין XR) > תוספי ARCore. לכל פלטפורמת יעד (Android, iOS), בתפריט הנפתח Authentication Strategy, בוחרים באפשרות API Key. לאחר מכן, מזינים את מפתח ה-API בשדות של מפתח ה-API.

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

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

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

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

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