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

پس از اجرای OAuth 2.0، می‌توانید به صورت اختیاری App Flip مبتنی بر OAuth را پیکربندی کنید، که به کاربران Android شما امکان می‌دهد سریع‌تر حساب‌های خود را در سیستم احراز هویت شما به حساب‌های Google خود پیوند دهند. بخش های زیر نحوه طراحی و پیاده سازی App Flip برای اکشن smart home شما شرح می دهد.

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

این بخش الزامات طراحی و توصیه‌هایی را برای صفحه رضایت پیوند دادن حساب 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 را بپذیرید.

OAuth-based App Flip linking (App Flip) inserts your Android app into the Google Account Linking flow. A traditional account linking flow requires the user to enter their credentials in the browser. The use of App Flip defers user sign-in to your Android app, which allows you to leverage existing authorizations. If the user is signed in to your app, they don't need to re-enter their credentials to link their account. A minimal amount of code changes are required to implement App Flip on your Android app.

In this document, you learn how to modify your Android app to support App Flip.

Try the sample

The App Flip linking sample app demonstrates an App Flip-compatible account linking integration on Android. You can use this app to verify how to respond to an incoming App Flip intent from Google mobile apps.

The sample app is preconfigured to integrate with the App Flip Test Tool for Android, which you can use to verify your Android app's integration with App Flip before you configure account linking with Google. This app simulates the intent triggered by Google mobile apps when App Flip is enabled.

How it works

The following steps are required to carry out an App Flip integration:

1. The Google app checks if your app is installed on the device using its package name.
2. The Google app uses a package signature check to validate that the installed app is the correct app.
3. The Google app builds an intent to start a designated activity in your app. This intent includes additional data required for linking. It also checks to see if your app supports App Flip by resolving this intent through the Android framework.
4. Your app validates that the request is coming from the Google app. To do so, your app checks the package signature and the provided client ID.
5. Your app requests an authorization code from your OAuth 2.0 server. At the end of this flow, it returns either an authorization code or an error to the Google app.
6. The Google app retrieves the result and continues with account linking. If an authorization code is provided, the token exchange happens server-to-server, the same way it does in the browser-based OAuth linking flow.

Modify your Android app to support App Flip

To support App Flip, make the following code changes to your Android app:

1. Add an <intent-filter> to your AndroidManifest.xml file with an action string that matches the value you entered in the App Flip Intent field.

   <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. Validate the calling app's signature.

   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. Extract the client ID from the intent parameters and verify that the client ID matches the expected value.

   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. Upon successful authorization, return the resulting authorization code back to Google.

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

5. If an error occurred, return an error result instead.

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

Content of the launch intent

The Android intent that launches your app includes the following fields:

• CLIENT_ID (String): Google client_id registered under your app.
• SCOPE (String[]): A list of scopes requested.
• REDIRECT_URI (String): The redirect URL.

Content of the response data

The data returned to the Google app is set in your app by calling setResult(). This data includes the following:

• AUTHORIZATION_CODE (String): The authorization code value.
• resultCode (int): Communicates the success or failure of the process and takes one of the following values:
  • Activity.RESULT_OK: Indicates success; an authorization code is returned.
  • Activity.RESULT_CANCELLED: Signals that the user has cancelled the process. In this case, the Google app will attempt account linking using your authorization URL.
  • -2: Indicates that an error has occurred. Different types of errors are described below.
• ERROR_TYPE (int): The type of error, which takes one of the following values:
  • 1: Recoverable error: The Google app will attempt account linking using the authorization URL.
  • 2: Unrecoverable error: The Google app aborts account linking.
  • 3: Invalid or missing request parameters.
• ERROR_CODE (int): An integer representing the nature of the error. To see what each error code means, refer to the table of error codes.

• ERROR_DESCRIPTION (String, optional): Human-readable status message describing the error.

A value for the AUTHORIZATION_CODE is expected when resultCode == Activity.RESULT_OK. In all other cases, the value for AUTHORIZATION_CODE needs to be empty. If resultCode == -2, then the ERROR_TYPE value is expected to be populated.

Table of error codes

The table below shows the different error codes and whether each is a recoverable or unrecoverable error:

For all error codes, you must return the error result via setResult to ensure the appropriate fallback is triggered.

برنامه 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. بررسی کنید که برنامه شما راه اندازی شده است و شروع به آزمایش جریان مجوز خود کنید.