از ARCore API در Google Cloud استفاده کنید

انتخاب پلتفرم:

ویژگی‌های ARCore مانند Geospatial API و Cloud Anchors از ARCore API میزبانی شده در Google Cloud استفاده می‌کنند. هنگام استفاده از این ویژگی‌ها، برنامه شما از اعتبارنامه‌ها برای دسترسی به سرویس ARCore API استفاده می‌کند.

این راهنمای سریع نحوه تنظیم برنامه شما را شرح می‌دهد تا بتواند با سرویس ARCore API میزبانی شده در Google Cloud ارتباط برقرار کند.

یک پروژه جدید Google Cloud ایجاد کنید یا از یک پروژه موجود استفاده کنید

اگر پروژه‌ای از قبل دارید، آن را انتخاب کنید.

به انتخابگر پروژه بروید

اگر پروژه Google Cloud ندارید، یکی ایجاد کنید.

ایجاد پروژه جدید

فعال کردن API ARCore

برای استفاده از API ARCore، باید آن را در پروژه خود فعال کنید.

فعال کردن API ARCore

یک روش مجوزدهی تنظیم کنید

یک برنامه Unity می‌تواند با استفاده از دو روش مختلف احراز هویت با API ARCore ارتباط برقرار کند: احراز هویت بدون کلید، که روش پیشنهادی است، و احراز هویت با کلید API:

  • در اندروید، احراز هویت بدون کلید (Keyless authorization) از ترکیبی از نام بسته برنامه و اثر انگشت کلید امضا برای احراز هویت برنامه شما استفاده می‌کند.

    در iOS، احراز هویت بدون کلید از یک توکن امضا شده برای کنترل دسترسی به API استفاده می‌کند. این روش به سروری متعلق به شما نیاز دارد تا توکن‌ها را امضا کرده و دسترسی به API را کنترل کند.

  • کلید API رشته‌ای است که یک پروژه Google Cloud را مشخص می‌کند. کلیدهای API معمولاً امن در نظر گرفته نمی‌شوند زیرا معمولاً برای کلاینت‌ها قابل دسترسی هستند. برای ارتباط با API ARCore، استفاده از احراز هویت بدون کلید را در نظر بگیرید.

بدون کلید

برای تأیید اعتبار برنامه خود با استفاده از احراز هویت بدون کلید ، شناسه‌های کلاینت OAuth 2.0 ایجاد کنید.

تعیین اثر انگشت کلید امضا

شناسه کلاینت OAuth 2.0 از اثر انگشت کلید امضای برنامه شما برای شناسایی برنامه‌تان استفاده می‌کند.

چگونه اثر انگشت امضای اشکال‌زدایی خود را به دست آورید

هنگام اجرا یا اشکال‌زدایی پروژه، ابزارهای Android SDK به طور خودکار برنامه شما را با یک گواهی اشکال‌زدایی تولید شده امضا می‌کنند.

برای دریافت اثر انگشت گواهی اشکال‌زدایی از دستور زیر استفاده کنید.

مک/لینوکس 
keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore
ویندوز 
keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

ابزار keytool از شما می‌خواهد که رمز عبوری برای keystore وارد کنید. رمز عبور پیش‌فرض برای debug keystore، 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 ، گوگل کلید امضای برنامه شما را مدیریت می‌کند و از آن برای امضای APK های شما استفاده می‌کند. این کلید باید برای اثر انگشت امضا استفاده شود.

  1. در صفحه امضای برنامه در کنسول گوگل پلی، به گواهی کلید امضای برنامه بروید.
  2. از اثر انگشت گواهی SHA-1 استفاده کنید.

ایجاد شناسه‌های کلاینت OAuth 2.0

برای هر کلید امضای قابل اجرا از مراحل قبلی، یک شناسه کلاینت OAuth 2.0 در اعتبارنامه‌های پروژه Google Cloud خود ایجاد کنید.

  • در گوگل کلود، صفحه اعتبارنامه‌ها (Credentials) را باز کنید.

    مدارک تحصیلی

  • روی ایجاد اعتبارنامه کلیک کنید، سپس شناسه کلاینت OAuth را از منو انتخاب کنید.

  • فیلدهای مورد نیاز را به شرح زیر پر کنید:

    • نوع برنامه : اندروید را انتخاب کنید.
    • نام بسته : از نام بسته‌ای که در 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 از احراز هویت فراخوانی‌های API در iOS با استفاده از یک ( توکن وب JSON ) پشتیبانی می‌کند. این توکن باید توسط یک حساب سرویس گوگل امضا شود.

برای تولید توکن برای iOS، باید یک نقطه پایانی روی سرور خود داشته باشید که شرایط زیر را برآورده کند:

  • مکانیزم مجوزدهی شما باید از نقطه پایانی محافظت کند.

  • نقطه پایانی باید هر بار یک توکن جدید تولید کند، به طوری که:

    • هر کاربر یک توکن منحصر به فرد دریافت می‌کند.
    • توکن‌ها بلافاصله منقضی نمی‌شوند.

ایجاد یک حساب کاربری سرویس و کلید امضا

برای ایجاد یک حساب کاربری سرویس گوگل و کلید امضا، این مراحل را دنبال کنید:

  1. در گوگل کلود، صفحه اعتبارنامه‌ها (Credentials) را باز کنید.
    مدارک تحصیلی
  2. روی ایجاد اعتبارنامه‌ها > حساب سرویس کلیک کنید.
  3. در قسمت جزئیات حساب سرویس ، نامی برای حساب جدید تایپ کنید، سپس روی ایجاد کلیک کنید.
  4. در صفحه مجوزهای حساب سرویس، به منوی کشویی «انتخاب یک نقش» بروید. «حساب‌های سرویس» > «ایجادکننده توکن حساب سرویس» را انتخاب کنید، سپس روی «ادامه» کلیک کنید.
  5. در صفحه «اعطای دسترسی به حساب کاربری این سرویس برای کاربران» ، روی «انجام شد» کلیک کنید.
  6. در صفحه اعتبارنامه‌ها ، بخش حساب‌های سرویس (Service Accounts) را پیدا کنید و روی نام حسابی که تازه ایجاد کرده‌اید کلیک کنید.
  7. در صفحه جزئیات حساب سرویس ، به پایین صفحه بروید تا به بخش کلیدها برسید و گزینه افزودن کلید > ایجاد کلید جدید را انتخاب کنید.

  8. نوع کلید را JSON انتخاب کنید و روی Create کلیک کنید.

    این یک فایل JSON حاوی کلید خصوصی دستگاه شما دانلود می‌کند. فایل کلید JSON دانلود شده را در یک مکان امن ذخیره کنید.

توکن‌ها را روی سرور خود ایجاد کنید

برای ایجاد توکن‌های جدید (JWT) روی سرور خود، از کتابخانه‌های استاندارد JWT و فایل JSON که به طور ایمن از حساب سرویس جدید خود دانلود کرده‌اید، استفاده کنید.

توکن‌ها را روی دستگاه توسعه خود ایجاد کنید

برای تولید JWTها در دستگاه توسعه خود، از دستور oauth2l زیر استفاده کنید: 

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

مشخص کردن یک مکان خالی در حافظه پنهان با استفاده از پرچم --cache برای اطمینان از تولید توکن متفاوت در هر بار ضروری است. حتماً رشته حاصل را برش دهید. فاصله‌های اضافی یا کاراکترهای خط جدید باعث می‌شوند API توکن را رد کند .

توکن را امضا کنید

شما باید از الگوریتم RS256 و ادعاهای زیر برای امضای JWT استفاده کنید:

  • iss — آدرس ایمیل حساب کاربری سرویس.
  • sub — آدرس ایمیل حساب کاربری سرویس.
  • iat — زمان تولید توکن در عصر یونیکس، بر حسب ثانیه.
  • exp — iat + 3600 (1 ساعت). زمان انقضای توکن در یونیکس، بر حسب ثانیه.
  • aud — مخاطب. باید روی https://arcore.googleapis.com/ تنظیم شود.

ادعاهای غیر استاندارد در JWT payload الزامی نیستند، اگرچه ممکن است ادعای uid برای شناسایی کاربر مربوطه مفید باشد.

اگر از رویکرد متفاوتی برای تولید JWT های خود استفاده می‌کنید، مانند استفاده از API گوگل در یک محیط مدیریت‌شده توسط گوگل، حتماً JWT های خود را با ادعاهای این بخش امضا کنید. مهم‌تر از همه، مطمئن شوید که مخاطب درست می‌گوید.

توکن را در جلسه ARCore ارسال کنید

  1. مطمئن شوید که گزینه‌ی « راهبرد احراز هویت iOS» روی «نشانه احراز هویت » (AuthenticationToken) تنظیم شده باشد. در یونیتی، به مسیر «ویرایش» > «تنظیمات پروژه» > «مدیریت افزونه‌های XR» > «افزونه‌های ARCore » بروید. در منوی کشویی «راهبرد احراز هویت iOS» ، گزینه‌ی «نشانه احراز هویت» (Authentication Token) را انتخاب کنید.

  2. وقتی یک توکن دریافت کردید، آن را با استفاده از ARAnchorManager.SetAuthToken() به سشن ARCore خود منتقل کنید: 

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

اکنون برنامه شما برای استفاده از احراز هویت بدون کلید پیکربندی شده است.

هنگام ارسال توکن به session به نکات زیر توجه کنید:

  • اگر از کلید API برای ایجاد جلسه استفاده کرده باشید، ARCore توکن را نادیده گرفته و خطایی را ثبت می‌کند.

    اگر دیگر به کلید API نیاز ندارید، آن را در کنسول توسعه‌دهندگان گوگل حذف کنید و از برنامه خود حذف کنید.

  • ARCore توکن‌هایی که حاوی فاصله یا کاراکترهای خاص باشند را نادیده می‌گیرد.

  • توکن‌ها معمولاً پس از یک ساعت منقضی می‌شوند. اگر این احتمال وجود دارد که توکن شما در حین استفاده منقضی شود، یک توکن جدید دریافت کرده و آن را به API ارسال کنید.

کلید API

  1. در گوگل کلود، صفحه اعتبارنامه‌ها (Credentials) را باز کنید.
    مدارک تحصیلی
  2. روی ایجاد اعتبارنامه کلیک کنید، سپس کلید API را از منو انتخاب کنید.
    کادر محاوره‌ای ایجاد کلید API، رشته مربوط به کلید تازه ایجاد شده شما را نمایش می‌دهد.

  3. در یونیتی، به مسیر Edit > Project Settings > XR Plug-in Management > ARCore Extensions بروید. برای هر پلتفرم هدف (اندروید، iOS)، در منوی کشویی Authentication Strategy آن، گزینه API Key را انتخاب کنید. سپس، کلید API خود را در فیلدهای API key وارد کنید.

  4. برای ایمن‌سازی کلید API خود ، مستندات مربوط به محدودیت‌های کلید API را بررسی کنید.

اکنون برنامه شما برای استفاده از کلیدهای API پیکربندی شده است.

قدم بعدی چیست؟

پس از پیکربندی مجوز، ویژگی‌های ARCore زیر را که از آن استفاده می‌کنند، بررسی کنید: