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

בחירת פלטפורמה:

תכונות של 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 יכולה לתקשר עם ARCore API באמצעות שתי שיטות הרשאה שונות: הרשאה ללא מפתח, שהיא השיטה המומלצת, והרשאה באמצעות מפתח API:

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

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

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

ללא מפתח

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

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

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

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

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

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

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

כשמשתמשים בחתימת אפליקציות ב-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 Web Token. הטוקן צריך להיות חתום על ידי חשבון שירות של Google.

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

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

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

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

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

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

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

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

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

יצירת טוקנים בשרת

כדי ליצור אסימונים חדשים (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 Plug-in Management (ניהול תוספים של XR) > ARCore Extensions (תוספים של ARCore). בתפריט הנפתח iOS Authentication Strategy (אסטרטגיית אימות ב-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 Console ולהסיר אותו מהאפליקציה.

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

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

מפתח API

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

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

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

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

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

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