App Flip برای اندروید

هنگامی که یک OAuth 2.0 پیاده سازی کردید، می توانید به صورت اختیاری App Flip, which allows your Android users to more quickly link their accounts in your authentication system to their Google accounts. The following sections describe how to design and implement App Flip for your smart home Action.

دستورالعمل های طراحی

این بخش الزامات طراحی و توصیه‌هایی را برای صفحه رضایت پیوند دادن حساب App Flip توضیح می‌دهد. بعد از اینکه Google با برنامه شما تماس گرفت، برنامه شما صفحه رضایت را به کاربر نمایش می دهد.

الزامات

1. باید اعلام کنید که حساب کاربر به Google مرتبط شده است، نه به یک محصول خاص Google، مانند Google Home یا Google Assistant.

توصیه ها

توصیه می کنیم موارد زیر را انجام دهید:

1. سیاست حفظ حریم خصوصی Google را نمایش دهید. پیوندی به خط‌مشی رازداری Google در صفحه رضایت اضافه کنید.

2. داده هایی که باید به اشتراک گذاشته شود. از زبان واضح و مختصر استفاده کنید تا به کاربر بگویید گوگل به چه اطلاعاتی از او نیاز دارد و چرا.

3. پاک کردن فراخوان برای اقدام یک فراخوان برای اقدام واضح در صفحه رضایت خود، مانند "موافق و پیوند" بیان کنید. این به این دلیل است که کاربران باید بدانند چه داده‌هایی را باید با Google به اشتراک بگذارند تا حساب‌های خود را پیوند دهند.

4. قابلیت لغو. راهی برای کاربران فراهم کنید که در صورت عدم پیوند، به عقب برگردند یا لغو کنند.

5. قابلیت قطع لینک مکانیزمی را برای لغو پیوند به کاربران ارائه دهید، مانند URL به تنظیمات حساب آنها در پلتفرم شما. از طرف دیگر، می‌توانید پیوندی به حساب Google اضافه کنید تا کاربران بتوانند حساب پیوند شده خود را مدیریت کنند.

6. امکان تغییر حساب کاربری روشی را به کاربران پیشنهاد کنید تا حساب(های) خود را تغییر دهند. این به ویژه در صورتی مفید است که کاربران تمایل به داشتن چندین حساب داشته باشند.

   • اگر کاربر باید صفحه رضایت را برای تغییر حساب ببندد، یک خطای قابل بازیابی به Google ارسال کنید تا کاربر بتواند با پیوند OAuth و جریان ضمنی به حساب مورد نظر وارد شود.

7. لوگوی خود را درج کنید. لوگوی شرکت خود را روی صفحه رضایت نمایش دهید. از دستورالعمل های سبک خود برای قرار دادن لوگوی خود استفاده کنید. اگر می‌خواهید نشان‌واره Google را نیز نمایش دهید، نشان‌ها و علائم تجاری را ببینید.

برای App Flip مبتنی بر OAuth تنظیم کنید

بخش‌های زیر پیش‌نیازهای App Flip مبتنی بر OAuth و نحوه پیکربندی پروژه App Flip خود را در کنسول Actions شرح می‌دهند.

یک اقدام خانه هوشمند ایجاد کنید و یک سرور OAuth 2.0 راه اندازی کنید

قبل از اینکه بتوانید App Flip را پیکربندی کنید، باید موارد زیر را انجام دهید:

• یک سرور OAuth 2.0 راه اندازی کنید. برای اطلاعات بیشتر درباره راه‌اندازی سرور OAuth، به پیاده‌سازی سرور OAuth 2.0 مراجعه کنید.
• یک اکشن ایجاد کنید. برای ایجاد یک Action، دستورالعمل‌های موجود در Create an Actions را دنبال کنید.

App Flip را در کنسول Actions پیکربندی کنید

بخش زیر نحوه پیکربندی App Flip را در کنسول Actions توضیح می‌دهد.

1. تمام فیلدهای زیر اطلاعات مشتری OAuth را پر کنید. (اگر App Flip پشتیبانی نمی شود، OAuth معمولی به عنوان یک بازگشت استفاده می شود.)
2. در قسمت Use your app for account linking (اختیاری) را علامت بزنید Enable for Android.
3. فیلدهای زیر را پر کنید:
• شناسه برنامه شناسه برنامه یک شناسه منحصر به فرد است که برای برنامه خود تنظیم می کنید.
• امضای برنامه برنامه‌های اندروید قبل از نصب باید با گواهی کلید عمومی «امضا» شوند. برای اطلاعات در مورد به دست آوردن امضای برنامه، به تأیید اعتبار مشتری مراجعه کنید.
• قصد مجوز. در این قسمت رشته ای را وارد کنید که عمل قصد شما را مشخص می کند.
4. اگر می‌خواهید به صورت اختیاری مشتری خود را پیکربندی کنید، دامنه‌ها را اضافه کنید و روی Add scope در زیر Configure your client (اختیاری) کلیک کنید.
5. روی ذخیره کلیک کنید.

App Flip را در برنامه های اندروید خود پیاده کنید

برای اجرای App Flip، باید کد مجوز کاربر را در برنامه خود تغییر دهید تا پیوند عمیق از Google را بپذیرید.

پیوند App Flip مبتنی بر OAuth (App Flip) برنامه Android شما را در جریان پیوند حساب Google وارد می‌کند. یک جریان پیوند دادن حساب سنتی به کاربر نیاز دارد که اعتبار خود را در مرورگر وارد کند. استفاده از App Flip ورود کاربر به برنامه Android شما را به تعویق می‌اندازد، که به شما امکان می‌دهد از مجوزهای موجود استفاده کنید. اگر کاربر به برنامه شما وارد شده باشد، برای پیوند دادن حساب خود نیازی به وارد کردن مجدد اطلاعات کاربری خود ندارد. برای پیاده سازی App Flip در برنامه Android خود، حداقل مقدار تغییر کد مورد نیاز است.

در این سند، یاد می گیرید که چگونه برنامه اندروید خود را برای پشتیبانی از App Flip تغییر دهید.

نمونه را امتحان کنید

برنامه نمونه پیوند App Flip یک پیوند حساب سازگار با App Flip را در Android نشان می دهد. می‌توانید از این برنامه برای تأیید نحوه پاسخگویی به یک هدف App Flip ورودی از برنامه‌های تلفن همراه Google استفاده کنید.

برنامه نمونه برای ادغام با App Flip Test Tool برای Android از پیش پیکربندی شده است، که می توانید قبل از پیکربندی پیوند حساب با Google، از آن برای تأیید یکپارچگی برنامه Android خود با App Flip استفاده کنید. این برنامه قصد ایجاد شده توسط برنامه های تلفن همراه Google را هنگامی که App Flip فعال است، شبیه سازی می کند.

چگونه کار می کند

برای انجام یکپارچه سازی App Flip مراحل زیر لازم است:

1. برنامه Google بررسی می کند که آیا برنامه شما با استفاده از نام بسته آن روی دستگاه نصب شده است یا خیر.
2. برنامه Google از بررسی امضای بسته برای تأیید صحت برنامه نصب شده استفاده می کند.
3. برنامه Google قصدی برای شروع یک فعالیت تعیین شده در برنامه شما ایجاد می کند. این هدف شامل داده های اضافی مورد نیاز برای پیوند است. همچنین بررسی می کند که آیا برنامه شما از App Flip با حل این هدف از طریق چارچوب Android پشتیبانی می کند یا خیر.
4. برنامه شما تأیید می کند که درخواست از برنامه Google می آید. برای انجام این کار، برنامه شما امضای بسته و شناسه مشتری ارائه شده را بررسی می کند.
5. برنامه شما یک کد مجوز از سرور OAuth 2.0 شما درخواست می کند. در پایان این جریان، یک کد مجوز یا یک خطا را به برنامه Google برمی‌گرداند.
6. برنامه Google نتیجه را بازیابی می کند و با پیوند دادن حساب ادامه می دهد. اگر کد مجوز ارائه شود، تبادل توکن سرور به سرور انجام می‌شود، به همان روشی که در جریان پیوند OAuth مبتنی بر مرورگر انجام می‌شود.

برنامه اندروید خود را برای پشتیبانی از App Flip تغییر دهید

برای پشتیبانی از App Flip، کد زیر را در برنامه اندروید خود تغییر دهید:

1. یک <intent-filter> را به فایل AndroidManifest.xml خود با یک رشته اقدام که با مقدار وارد شده در قسمت App Flip Intent مطابقت دارد، اضافه کنید.

   <activity android:name="AuthActivity">
     <!-- Handle the app flip intent -->
     <intent-filter>
       <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
       <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
   </activity>
   

2. امضای برنامه تماس را تأیید کنید.

   private fun verifyFingerprint(
           expectedPackage: String,
           expectedFingerprint: String,
           algorithm: String
   ): Boolean {
   
       callingActivity?.packageName?.let {
           if (expectedPackage == it) {
               val packageInfo =
                   packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
               val signatures = packageInfo.signatures
               val input = ByteArrayInputStream(signatures[0].toByteArray())
   
               val certificateFactory = CertificateFactory.getInstance("X509")
               val certificate =
                   certificateFactory.generateCertificate(input) as X509Certificate
               val md = MessageDigest.getInstance(algorithm)
               val publicKey = md.digest(certificate.encoded)
               val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }
   
               return (expectedFingerprint == fingerprint)
           }
       }
       return false
   }
   

3. شناسه مشتری را از پارامترهای intent استخراج کنید و بررسی کنید که شناسه مشتری با مقدار مورد انتظار مطابقت دارد.

   private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
   private const val EXPECTED_PACKAGE = "<google-app-package-name>"
   private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
   private const val ALGORITHM = "SHA-256"
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {
   
           // ...authorize the user...
       }
   }
   

4. پس از تأیید موفقیت آمیز، کد مجوز حاصل را به Google برگردانید.

   // Successful result
   val data = Intent().apply {
       putExtra("AUTHORIZATION_CODE", authCode)
   }
   setResult(Activity.RESULT_OK, data)
   finish()
   

5. اگر خطایی رخ داد، به جای آن یک نتیجه خطا را برگردانید.

   // Error result
   val error = Intent().apply {
       putExtra("ERROR_TYPE", 1)
       putExtra("ERROR_CODE", 1)
       putExtra("ERROR_DESCRIPTION", "Invalid Request")
   }
   setResult(-2, error)
   finish()
   

محتوای قصد راه اندازی

هدف Android که برنامه شما را راه اندازی می کند شامل فیلدهای زیر است:

• CLIENT_ID ( String ): Google client_id در برنامه شما ثبت شده است.
• SCOPE ( String[] ): فهرستی از محدوده های درخواستی.
• REDIRECT_URI ( String ): URL تغییر مسیر.

محتوای داده های پاسخ

داده های بازگردانده شده به برنامه Google با فراخوانی setResult() در برنامه شما تنظیم می شود. این داده ها شامل موارد زیر است:

• AUTHORIZATION_CODE ( String ): مقدار کد مجوز.
• resultCode ( int ): موفقیت یا شکست فرآیند را به اشتراک می گذارد و یکی از مقادیر زیر را می گیرد:
  • Activity.RESULT_OK : نشان دهنده موفقیت است. یک کد مجوز بازگشت داده می شود.
  • Activity.RESULT_CANCELLED : سیگنال هایی مبنی بر اینکه کاربر فرآیند را لغو کرده است. در این صورت، برنامه Google سعی می‌کند حساب را با استفاده از URL مجوز شما پیوند دهد.
  • -2 : نشان می دهد که خطایی رخ داده است. انواع مختلف خطا در زیر توضیح داده شده است.
• ERROR_TYPE ( int ): نوع خطا که یکی از مقادیر زیر را می گیرد:
  • 1 : خطای قابل بازیابی: برنامه Google سعی می کند حساب را با استفاده از URL مجوز پیوند دهد.
  • 2 : خطای غیرقابل جبران: برنامه Google پیوند حساب را لغو می کند.
  • 3 : پارامترهای درخواست نامعتبر یا گم شده است.
• ERROR_CODE ( int ): یک عدد صحیح که ماهیت خطا را نشان می دهد. برای دیدن معنی هر کد خطا، به جدول کدهای خطا مراجعه کنید.

• ERROR_DESCRIPTION ( String ، اختیاری): پیام وضعیت قابل خواندن توسط انسان که خطا را توصیف می کند.

زمانی که resultCode == Activity.RESULT_OK مقداری برای AUTHORIZATION_CODE انتظار می رود. در همه موارد دیگر، مقدار AUTHORIZATION_CODE باید خالی باشد. اگر resultCode == -2 باشد، انتظار می رود مقدار ERROR_TYPE پر شود.

جدول کدهای خطا

جدول زیر کدهای مختلف خطا و اینکه آیا هر کدام یک خطای قابل بازیابی یا غیرقابل بازیابی هستند را نشان می دهد:

برای همه کدهای خطا، باید نتیجه خطا را از طریق setResult تا مطمئن شوید که بازگشت مناسب فعال شده است.

برنامه Flip را روی دستگاه خود تست کنید

اکنون که یک Action ایجاد کرده اید و App Flip را در کنسول و برنامه خود پیکربندی کرده اید، می توانید App Flip را در دستگاه تلفن همراه خود آزمایش کنید. می‌توانید از برنامه Google Assistant یا برنامه Google Home برای آزمایش App Flip استفاده کنید.

برای آزمایش App Flip از برنامه Assistant، این مراحل را دنبال کنید:

1. به کنسول Actions بروید و پروژه خود را انتخاب کنید.
2. روی تست در پیمایش بالا کلیک کنید.
3. جریان پیوند حساب را از برنامه دستیار فعال کنید:
1. برنامه Google Assistant را باز کنید.
2. روی تنظیمات کلیک کنید.
3. در تب Assistant، روی Home Control کلیک کنید.
4. روی Add(+) کلیک کنید.
5. Action خود را از لیست ارائه دهندگان انتخاب کنید. پیشوند آن با "[test]" در لیست خواهد بود. وقتی اکشن [تست] خود را از لیست انتخاب می‌کنید، باید برنامه شما را باز کند.
6. بررسی کنید که برنامه شما راه اندازی شده است و شروع به آزمایش جریان مجوز خود کنید.

برای آزمایش App Flip از برنامه Home، این مراحل را دنبال کنید:

1. به کنسول Actions بروید و پروژه خود را انتخاب کنید.
2. روی تست در پیمایش بالا کلیک کنید.
3. جریان پیوند حساب را از برنامه Home فعال کنید:
1. برنامه Google Home را باز کنید.
2. روی دکمه + کلیک کنید.
3. روی تنظیم دستگاه کلیک کنید.
4. روی آیا چیزی قبلاً تنظیم شده است؟
5. Action خانه هوشمند خود را از لیست ارائه دهندگان انتخاب کنید. پیشوند آن با "[test]" در لیست خواهد بود. وقتی اکشن [تست] خود را از لیست انتخاب می‌کنید، باید برنامه شما را باز کند.
6. بررسی کنید که برنامه شما راه اندازی شده است و شروع به آزمایش جریان مجوز خود کنید.