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

اختَر نظامًا أساسيًا:

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

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

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

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

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

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

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

تفعيل ARCore API

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

تفعيل ARCore API

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

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

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

بدون مفتاح

يتيح 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 الذي تم تنزيله في مكان آمن.

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

لإنشاء رموز مميزة جديدة (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. أنشِئ جلسة باستخدام GARSession#sessionWithError:.

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

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

    [garSession setAuthToken: authToken]

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

لاحظ ما يلي عند إدخال رمز مميز في الجلسة:

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

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

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

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

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

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

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

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

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

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

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