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

اختيار النظام الأساسي:

تستخدم ميزات ARCore، مثل Geospatial API ونقاط ارتكاز السحابة الإلكترونية، واجهة برمجة التطبيقات 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، تستخدم ميزة "المصادقة بدون مفتاح" رمزًا مميزًا موقّعًا للتحكّم في الوصول إلى واجهة برمجة التطبيقات. تتطلّب هذه الطريقة توفّر خادم تملكه لتوقيع الرموز المميزة والتحكّم في الوصول إلى واجهة برمجة التطبيقات.

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

بدون مفتاح

للسماح بتطبيقك باستخدام المصادقة بدون مفتاح، أنشئ معرّفات عميل 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

كيفية الحصول على بصمة توقيع من ملف تخزين مفاتيح

إذا كان لديك ملف keystore، استخدِم أداة 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. يجب أن يكون الرمز المميّز موقّعًا من حساب خدمة تابع لـ Google.

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

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

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

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

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

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

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

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

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

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

لإنشاء رموز مميّزة جديدة (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 API في بيئة تديرها Google، احرص على توقيع رموز JWT باستخدام المطالبات الواردة في هذا القسم. قبل كل شيء، تأكَّد من صحة الجمهور.

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

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

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

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

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

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