استخدام 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

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

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

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

بدون مفتاح

يتيح 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. إنشاء جلسة باستخدام GARSession#sessionWithError:

    NSError *error = nil;
GARSession *garSession = [GARSession sessionWithError:&error];

  2. عند الحصول على رمز مميّز، مرِّره إلى الجلسة باستخدام setAuthToken:. بخلاف ذلك، ستستخدِم الجلسة أحدث رمز مميّز صالح للتفويض أدخلته. استدعِ هذه الطريقة في كل مرة تعيد فيها تحميل الرمز المميّز:

    [garSession setAuthToken: authToken]

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

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

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

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

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

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

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

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

  3. عند إنشاء GARSession، استخدِم GARSession#sessionWithAPIKey:bundleIdentifier:error: وأدرِج مفتاح واجهة برمجة التطبيقات:

    self.garSession = [GARSession sessionWithAPIKey:@"your-api-key"
                               bundleIdentifier:nil
                                          error:&error];
  4. راجِع المستندات حول القيود المفروضة على مفتاح واجهة برمجة التطبيقات لتأمين مفتاح واجهة برمجة التطبيقات.

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

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

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