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

اختَر نظامًا أساسيًا: Android Unity (AR Foundation) iOS

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

يصف دليل البدء السريع هذا كيفية إعداد تطبيقك لكي يتواصل مع خدمة 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

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

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

• انقر على إنشاء بيانات اعتماد، ثم اختَر معرِّف عميل 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 Service.

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

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

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

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

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

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

1. في Google Cloud، افتح صفحة "بيانات الاعتماد".
   بيانات الاعتماد
2. انقر على إنشاء بيانات اعتماد > حساب الخدمة.
3. ضمن تفاصيل حساب الخدمة، اكتب اسمًا للحساب الجديد، ثم انقر على إنشاء.
4. في صفحة أذونات حساب الخدمة، انتقِل إلى القائمة المنسدلة اختيار دور. اختَر Service accounts > Service Account Token Creator (حسابات الخدمة)، ثم انقر على Continue (متابعة).
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 (ساعة واحدة) تبدأ حقبة Unix عند انتهاء صلاحية الرمز المميز، بالثواني.
• aud — الجمهور يجب ضبطها على https://arcore.googleapis.com/.

لا يُشترط تقديم المطالبات غير العادية في حمولة بيانات JWT، ولكن قد ترى أنّ مطالبة uid مفيدة لتحديد المستخدم المناسب.

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

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

1. احرص على ضبط استراتيجية مصادقة iOS على AuthToken. في Unity، انتقِل إلى Edit > Project Settings (إعدادات المشروع) > XR Plug-in Management (إدارة مكوّنات 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 وإزالته من تطبيقك.

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

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

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

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

3. في برنامج Unity، انتقِل إلى Edit > Project Settings (إعدادات المشروع) > XR Plug-in Management (إدارة مكوّنات XR الإضافية) > ARCore متوفّرة. بالنسبة إلى كل نظام أساسي مستهدَف (Android وiOS)، في القائمة المنسدلة استراتيجية المصادقة، حدِّد الخيار مفتاح واجهة برمجة التطبيقات. بعد ذلك، أدخِل مفتاح واجهة برمجة التطبيقات في حقول مفتاح واجهة برمجة التطبيقات.

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

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

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

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

• واجهة برمجة التطبيقات الجغرافية المكانية
• واجهة برمجة تطبيقات Cloud Anchor