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

پیوند 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. امضای برنامه تماس را تأیید کنید.

   توجه: باید نام بسته و امضای برنامه Google را مطابقت دهید.

   نام بسته : com.google.android.googlequicksearchbox

   امضا : F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91: 04:80:AD:6B:2D:60:DB:83

   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. اگر خطایی رخ داد، به جای آن یک نتیجه خطا را برگردانید.

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

   // 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 ، اختیاری): پیام وضعیت قابل خواندن توسط انسان که خطا را توصیف می کند.

  توجه: برای اطلاعات بیشتر در مورد خطاهای احتمالی و محتوای اختیاری فیلد error_description به استاندارد OAuth 2.0 مراجعه کنید.

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

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

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

کد خطا	معنی	قابل بازیابی	غیر قابل بازیابی
1	INVALID_REQUEST	✔
2	NO_INTERNET_CONNECTION		✔
3	OFFLINE_MODE_ACTIVE	✔
4	CONNECTION_TIMEOUT	✔
5	INTERNAL_ERROR	✔
6	AUTHENTICATION_SERVICE_UNAVAILABLE		✔
8	CLIENT_VERIFICATION_FAILED	✔
9	INVALID_CLIENT	✔
10	INVALID_APP_ID	✔
11	INVALID_REQUEST	✔
12	AUTHENTICATION_SERVICE_UNKNOWN_ERROR		✔
13	AUTHENTICATION_DENIED_BY_USER		✔
14	CANCELLED_BY_USER		✔
15	FAILURE_OTHER		✔
16	USER_AUTHENTICATION_FAILED	✔

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