استخدام ARCore API على Google Cloud

اختيار النظام الأساسي: نظام التشغيل Android Unity (AR Foundation) iOS

ميزات ARCore مثل Geospatial تستخدم واجهة برمجة التطبيقات وCloud Anchors ARCore API مستضافة على Google Cloud. عند استخدام هذه الميزات، لن يتمكن تطبيقك بيانات الاعتماد للوصول إلى خدمة واجهة برمجة تطبيقات ARCore.

تصف هذه البدء السريع كيفية إعداد تطبيقك بحيث يمكنه التواصل مع خدمة ARCore API المستضافة على Google Cloud.

إنشاء مشروع جديد على Google Cloud أو استخدام مشروع حالي

إذا كان لديك مشروع حالي، اختَره.

الانتقال إلى أداة اختيار المشروع

إذا لم يكن لديك مشروع حالي على Google Cloud، أنشِئ مشروعًا.

إنشاء مشروع جديد

تفعيل ARCore API

لاستخدام ARCore API، عليك تفعيلها في مشروعك.

تفعيل ARCore API

إعداد طريقة التفويض

يمكن لتطبيق Unity الاتصال بواجهة برمجة تطبيقات ARCore باستخدام نظامين مختلفين طرق التفويض: المصادقة بدون مفتاح، والتي تعني الطريقة الموصى بها، وتفويض مفتاح واجهة برمجة التطبيقات:

• على نظام التشغيل Android، تستخدم ميزة الترخيص بدون مفتاح مجموعة من اسم حزمة التطبيق وبصمة مفتاح التوقيع لمصادقة تطبيقك.

  في نظام التشغيل iOS، يستخدم التفويض بدون مفتاح رمزًا مميزًا تم توقيعه للتحكم في الوصول إلى واجهة برمجة التطبيقات. هذا النمط تتطلب خادمًا تملكه أنت للتوقيع على الرموز المميزة والتحكم في الوصول إلى واجهة برمجة التطبيقات.

• مفتاح واجهة برمجة التطبيقات هو سلسلة تحدِّد مشروعًا على Google Cloud. مفاتيح واجهة برمجة التطبيقات هي لا تعتبر آمنة بشكل عام حيث يمكن للعملاء الوصول إليها عادةً. يمكنك استخدام التفويض بدون مفتاح للاتصال بواجهة برمجة تطبيقات ARCore.

بدون مفتاحبدون مفتاحمفتاح واجهة برمجة التطبيقات

للسماح لتطبيقك باستخدام المصادقة بدون مفتاح، عليك إنشاء برنامج OAuth 2.0. المعرفات.

تحديد بصمات الإصبع الرئيسية للتوقيع

يستخدم معرِّف عميل OAuth 2.0 بصمة مفتاح توقيع تطبيقك لتحديد هويتك. التطبيق.

ملاحظة مهمة: من الشائع توقيع تطبيقك باستخدام مفاتيح توقيع مختلفة. يجب إنشاء معرِّف عميل لكل مفتاح توقيع تخطط لاستخدامه. وعادةً ما يكون هذا هو توقيع لتصحيح الأخطاء والمفتاح مفاتيح توقيع الإصدار

كيفية الحصول على بصمة التوقيع لتصحيح الأخطاء

عند تشغيل مشروعك أو تصحيح الأخطاء فيه، يتم تلقائيًا توقيع أدوات حزمة تطوير البرامج (SDK) لنظام التشغيل Android تطبيقك بشهادة تصحيح أخطاء تم إنشاؤها.

استخدِم الأمر التالي للحصول على الملف المرجعي لشهادة تصحيح الأخطاء.

نظام التشغيل Mac/Linuxنظام التشغيل Windows

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، افتح صفحة "بيانات الاعتماد".

  بيانات الاعتماد

• انقر على إنشاء بيانات اعتماد، ثم اختَر معرِّف عميل OAuth من القائمة.

• املأ الحقول المطلوبة كما يلي:

  • نوع التطبيق: اختَر 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 تفويض طلبات البيانات من واجهة برمجة التطبيقات في نظام التشغيل iOS باستخدام (JSON Web رمز مميّز). يجب أن يوقّع Google على الرمز المميّز حساب الخدمة.

لإنشاء رموز مميّزة لنظام التشغيل iOS، يجب أن تتوفّر لديك نقطة نهاية على الخادم. تستوفي المتطلبات التالية:

• يجب أن تحمي آلية التفويض التي تستخدمها نقطة النهاية.

• يجب أن تنشئ نقطة النهاية رمزًا مميزًا جديدًا في كل مرة، على النحو التالي:

  • ويحصل كل مستخدم على رمز مميّز فريد.
  • لا تنتهي صلاحية الرموز المميّزة على الفور.

إنشاء حساب خدمة ومفتاح توقيع

اتّبِع الخطوات التالية لإنشاء حساب خدمة على Google ومفتاح توقيع:

1. في Google Cloud، افتح صفحة "بيانات الاعتماد".
   بيانات الاعتماد
2. انقر على إنشاء بيانات اعتماد > حساب الخدمة:
3. ضمن تفاصيل حساب الخدمة، اكتب اسمًا للحساب الجديد، ثم انقر على إنشاء:
4. في صفحة أذونات حساب الخدمة، انتقِل إلى القائمة المنسدلة اختيار دور. اختَر حسابات الخدمة >. مُنشئ الرمز المميّز لحساب الخدمة، ثم انقر على "متابعة":
5. في صفحة منح المستخدمين إذن الوصول إلى حساب الخدمة هذا، انقر على "تم".
6. في بيانات الاعتماد ابحث عن قسم "حسابات الخدمة" وانقر على اسم الحساب الذي قمتَ بإنشائه للتو.
7. في صفحة تفاصيل حساب الخدمة، مرِّر لأسفل إلى قسم "المفاتيح" حدد إضافة مفتاح > إنشاء مفتاح جديد

8. اختَر JSON كنوع المفتاح وانقر على إنشاء.

   سيؤدي هذا الإجراء إلى تنزيل ملف JSON يتضمّن المفتاح الخاص إلى جهازك. متجر ملف مفتاح JSON الذي تم تنزيله في موقع آمن.

   ملاحظة: يحتوي هذا الملف على مفتاح خاص يجب ألا يظهر عامة. لا تلتزم به في مستودعات رموز المصدر، مثل GitHub.

إنشاء رموز مميّزة على خادمك

لإنشاء رموز مميزة جديدة (JWT) على خادمك، استخدم رموز JWT القياسية المكتبات وملف JSON الذي نزّلته بأمان من حساب الخدمة الجديد.

إنشاء رموز مميزة على جهاز التطوير

لإنشاء JWT على جهاز التطوير، استخدِم ما يلي: الأمر oauth2l:

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

يجب تحديد موقع ذاكرة تخزين مؤقت فارغ باستخدام علامة --cache من أجل ضمان إنشاء رمز مميز مختلف في كل مرة. تأكد من قطع السلسلة الناتجة. ستؤدي المسافات الزائدة أو الأحرف في الأسطر الجديدة إلى رفض الرمز المميّز.

التوقيع على الرمز المميّز

يجب استخدام خوارزمية RS256 والادعاءات التالية للتوقيع على JWT:

• iss — عنوان البريد الإلكتروني لحساب الخدمة.
• sub — عنوان البريد الإلكتروني لحساب الخدمة.
• iat — وقت حقبة Unix الذي تم فيه إنشاء الرمز المميز، بالثواني
• exp — iat + 3600 (ساعة واحدة) هو وقت حقبة يونكس عند انتهاء صلاحية الرمز المميز، بالثواني.
• aud — الجمهور يجب ضبطها على https://arcore.googleapis.com/

لا يلزم تقديم مطالبات غير قياسية في حمولة JWT، ولكن قد تجد مطالبة واحدة (uid) مفيدة في تحديد المستخدم المعني

إذا استخدمت أسلوبًا مختلفًا لإنشاء JWT الخاص بك، مثل استخدام ملف واجهة برمجة التطبيقات في بيئة تديرها Google، احرص على توقيع JWT مع المطالبات في هذا القسم. قبل كل شيء، تأكد من صحة الجمهور.

تمرير الرمز المميّز في جلسة ARCore

1. تأكّد من ضبط استراتيجية مصادقة iOS على AuthenticationToken: في Unity، انتقِل إلى تعديل >. إعدادات المشروع > إدارة المكون الإضافي XR > إضافات ARCore. في القائمة المنسدلة استراتيجية مصادقة iOS اختر الرمز المميّز للمصادقة.

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);
   

تم إعداد تطبيقك الآن لاستخدام المصادقة بدون مفتاح.

يُرجى مراعاة ما يلي عند تمرير رمز مميّز إلى الجلسة:

• في حال استخدام مفتاح واجهة برمجة التطبيقات لإنشاء الجلسة، سيتجاهل ARCore الرمز المميز وتسجيل خطأ.

  إذا لم تعد بحاجة إلى مفتاح واجهة برمجة التطبيقات، يمكنك حذفه من خلال Google Developers. Console وإزالته من التطبيق.

• يتجاهل ARCore الرموز المميزة التي تحتوي على مسافات أو رموز خاصة.

• تنتهي صلاحية الرموز المميزة عادةً بعد ساعة واحدة. إذا كان هناك احتمال أن أن تنتهي صلاحية الرمز أثناء استخدامه، ويحصل على رمز مميز جديد ويمرره إلى واجهة برمجة التطبيقات.

1. في Google Cloud، افتح صفحة "بيانات الاعتماد".
   بيانات الاعتماد
2. انقر على إنشاء بيانات اعتماد، ثم اختَر مفتاح واجهة برمجة التطبيقات من القائمة.
   يعرض مربّع الحوار "إنشاء مفتاح واجهة برمجة التطبيقات" السلسلة الخاصة بالمفتاح الذي تم إنشاؤه حديثًا.

3. في Unity، انتقِل إلى تعديل >. إعدادات المشروع > إدارة المكون الإضافي XR > إضافات ARCore. لكل نظام أساسي مستهدف (Android وiOS)، وذلك في استراتيجية المصادقة، انقر على الخيار مفتاح واجهة برمجة التطبيقات. بعد ذلك، يُرجى اتّباع الخطوات التالية: أدخِل مفتاح واجهة برمجة التطبيقات في حقول مفتاح واجهة برمجة التطبيقات.

4. مراجعة مستندات حول القيود المفروضة على مفتاح واجهة برمجة التطبيقات لتأمين مفتاح واجهة برمجة التطبيقات.

تم إعداد تطبيقك الآن لاستخدام مفاتيح واجهة برمجة التطبيقات.

الخطوات التالية

بعد تهيئة التفويض، اطلع على ميزات ARCore التالية التي تستخدم فهو:

• واجهة برمجة التطبيقات Geospatial
• Cloud Anchor API