هم‌پیوندی برنامه برای Android

وقتی پیاده‌سازی OAuth 2.0 را انجام دادید، می‌توانید به‌طور اختیاری App Flip مبتنی بر OAuth را پیکربندی کنید، که به کاربران Android شما اجازه می‌دهد حساب‌هایشان را در سیستم اصالت‌سنجی شما سریع‌تر به «حساب‌های Google» خود پیوند دهند. بخش‌های زیر نحوه طراحی و پیاده‌سازی App Flip را برای ادغام Cloud-to-cloud در Android شرح می‌دهد.

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

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

الزامات

  1. شما باید یک بیانیه مجوز گوگل مانند «پس از اتصال، گوگل اجازه کنترل دستگاه‌های شما را خواهد داشت» داشته باشید.
  2. شما باید اطلاع دهید که حساب کاربر به گوگل متصل می‌شود، نه به یک محصول خاص گوگل، مانند گوگل هوم یا دستیار گوگل.
  3. شما باید یک فراخوان عمل واضح در صفحه رضایت خود بیان کنید و از عبارت «موافقم و پیوند» برای اقدام پیوند استفاده کنید. دلیل این امر این است که کاربران باید بدانند برای پیوند دادن حساب‌هایشان، چه داده‌هایی را باید با گوگل به اشتراک بگذارند.
  4. شما باید راهی برای کاربران فراهم کنید تا در صورت عدم تمایل به پیوند، بتوانند به عقب برگردند، آن را رد کنند یا لغو کنند. برای لغو پیوند از عبارت «لغو» استفاده کنید.
  5. شما باید این گردش کار را پیاده‌سازی کنید: پس از کلیک روی «موافقت و پیوند»، باید موفقیت پیوند را نشان دهید و کاربر را به طور خودکار به برنامه Google Home هدایت کنید. اکنون کاربر باید دستگاه پیوند شده را با اقدام شما در برنامه Google Home ببیند. پس از کلیک روی «لغو»، باید کاربر را به برنامه Google Home هدایت کنید.

توصیه‌ها

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

  1. سیاست حفظ حریم خصوصی گوگل را نمایش دهید. پیوندی به سیاست حفظ حریم خصوصی گوگل را در صفحه رضایت‌نامه قرار دهید.

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

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

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

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

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

این شکل یک نمونه صفحه رضایت‌نامه را به همراه الزامات فردی و توصیه‌هایی که باید هنگام طراحی صفحه رضایت‌نامه کاربر رعایت شوند، نشان می‌دهد.
شکل ۱: دستورالعمل‌های طراحی صفحه رضایت‌نامه اتصال حساب کاربری.

راه‌اندازی برای App Flip مبتنی بر OAuth

بخش‌های زیر پیش‌نیازهای «هم‌پیوندی برنامه» مبتنی بر OAuth و نحوه پیکربندی پروژه «هم‌پیوندی برنامه» را در «کنسول توسعه‌دهنده Google Home» شرح می‌دهد.

یکپارچه‌سازی «ابر به ابر» ایجاد کنید و سرور OAuth 2.0 راه‌اندازی کنید

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

پیکربندی «هم‌پیوندی برنامه» در «کنسول توسعه‌دهنده»

بخش زیر نحوه پیکربندی «هم‌پیوندی برنامه» را در کنسول توسعه‌دهنده شرح می‌دهد.

  1. همه فیلدهای الزامی(*) را در بخش پیوند دادن حساب تکمیل کنید. (اگر «هم‌پیوندی برنامه» پشتیبانی نشود، OAuth معمولی به‌عنوان جایگزین استفاده می‌شود.)
  2. نشانی وبی برای نشانی وب برآورده‌سازی Cloud ارائه دهید. از نشانی وب اجرای Cloud برای پردازش هدف‌های خانه هوشمند شما استفاده می‌شود. انجام محلی را بررسی کنید.
  3. در بخش هم‌پیوندی برنامه (اختیاری)، برنامه Android را علامت بزنید.
  4. فیلدهای زیر را پر کنید:
    • شناسه برنامه. «شناسه برنامه» شناسه یکتایی است که برای برنامه‌تان تنظیم می‌کنید.
    • امضای برنامه. برنامه‌های Android باید قبل‌از نصب شدن با گواهینامه کلید عمومی «امضا» شوند. برای کسب اطلاعات درباره دریافت امضای برنامه، به اصالت‌سنجی کارخواه مراجعه کنید.
    • قصد مجوز. در این فیلد، رشته‌ای را وارد کنید که کنش هدف شما را مشخص می‌کند.
  5. اگر می‌خواهید به‌طور اختیاری مشتری‌تان را پیکربندی کنید، گستره‌ها را اضافه کنید و روی افزودن گستره در بخش گستره(ها) (اختیاری) کلیک کنید.
  6. اگر کارخواه شما به آن نیاز دارد، Have Google transmit Client ID and secret via HTTP basic auth header (Google شناسه کارخواه و رمز را ازطریق سرصفحه اصالت‌سنجی پایه HTTP منتقل کند) را انتخاب کنید.

اکنون می‌توانید به بخش بعدی بروید تا App Flip را در برنامه Android پیاده‌سازی کنید.

App Flip را در برنامه‌های بومی‌تان پیاده‌سازی کنید

برای پیاده‌سازی App Flip، باید کد مجوز کاربر را در برنامه‌تان اصلاح کنید تا پیوند عمیق از Google را بپذیرد.

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

در این سند، با نحوه اصلاح برنامه Android برای پشتیبانی از «هم‌پیوندی برنامه» آشنا می‌شوید.

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

برنامه نمونه پیونددهی «هم‌پیوندی برنامه» یکپارچه‌سازی پیونددهی حساب سازگار با «هم‌پیوندی برنامه» را در Android نشان می‌دهد. می‌توانید از این برنامه برای درستی‌سنجی نحوه پاسخ دادن به هدف «هم‌پیوندی برنامه» ورودی از برنامه‌های تلفن همراه Google استفاده کنید.

برنامه نمونه ازقبل پیکربندی شده است تا با ابزار آزمایش هم‌پیوندی برنامه برای Android ادغام شود، که می‌توانید از آن برای تأیید ادغام برنامه Android خود با هم‌پیوندی برنامه قبل‌از پیکربندی پیوند حساب با Google استفاده کنید. این برنامه، هدف راه‌اندازی‌شده توسط برنامه‌های تلفن همراه Google را هنگام فعال بودن «هم‌پیوندی برنامه» شبیه‌سازی می‌کند.

روش کار

مراحل زیر برای اجرای ادغام «هم‌پیوندی برنامه» الزامی است:

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

اصلاح برنامه Android برای پشتیبانی از «هم‌پیوندی برنامه»

برای پشتیبانی از «هم‌پیوندی برنامه»، تغییرات کد زیر را در برنامه Android خود اعمال کنید:

  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 که ممکن است کاربران برای پیوند دادن حساب استفاده کنند مطابقت دهید. برای مثال، برای پیوند دادن با برنامه‌های Google Home و «جستجو»، نام بسته و امضای آن‌ها را اضافه کنید:

    • نام بسته: com.google.android.apps.chromecast.app
    • گواهی تبار SHA-256 اصلی: 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
    • گواهی SHA-256 «امضای برنامه Play» چرخش‌یافته: 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6

    و

    • نام بسته: 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

    درخواست‌های پیونددهی خانه هوشمند مستقیماً توسط Google Home app (GHA) آغاز می‌شود. اگر برنامه‌تان تماس‌گیرندگان را محدود می‌کند و قبلاً فقط به برنامه «جستجوی Google» اجازه می‌داد، باید com.google.android.apps.chromecast.app و گواهی‌های SHA-256 آن را به فهرست مجازتان اضافه کنید تا «هم‌پیوندی برنامه» همچنان موفقیت‌آمیز باشد.

    private fun verifyFingerprint(
    expectedPackage: String,
    expectedFingerprints: List<String>
): Boolean {
    val callingPackage = callingActivity?.packageName ?: return false
    if (callingPackage != expectedPackage) return false
    return expectedFingerprints.any { hex ->
        val sha256Bytes =
            hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
        packageManager.hasSigningCertificate(
            callingPackage,
            sha256Bytes,
            PackageManager.CERT_INPUT_SHA256
        )
    }
}

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

    private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
// Original lineage certificate (3D:7A...) and active rotated
// Play App Signing certificate (5A:AD...)
private val EXPECTED_FINGERPRINTS = listOf(
    "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
    "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
)
...

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val clientId = intent.getStringExtra("CLIENT_ID")

    if (clientId == EXPECTED_CLIENT &&
        verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {

        // ...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): نشانی وب تغییرمسیر.

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

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

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

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

وقتی 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 برگردانید تا مطمئن شوید که بازگشت مناسب راه‌اندازی شده است.

App Flip را در دستگاهتان آزمایش کنید

اکنون که ادغام «ابر به ابر» را ایجاد کرده‌اید و «هم‌پیوندی برنامه» را در کنسول و در برنامه‌تان پیکربندی کرده‌اید، می‌توانید «هم‌پیوندی برنامه» را در دستگاه همراهتان آزمایش کنید. می‌توانید از برنامه Google Home برای آزمایش «هم‌پیوندی برنامه» استفاده کنید.

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

  1. به کنسول توسعه‌دهنده بروید و پروژه خود را انتخاب کنید.
  2. به Cloud-to-cloud > آزمایش بروید.
  3. جریان پیوند دادن حساب را از برنامه Home راه‌اندازی کنید:
    1. Google Home app (GHA) را باز کنید.
    2. روی دکمه + کلیک کنید.
    3. روی راه‌اندازی دستگاه کلیک کنید.
    4. روی قبلاً چیزی راه‌اندازی کرده‌اید؟ کلیک کنید.
    5. ادغام «ابر به ابر» خود را از فهرست ارائه‌دهندگان انتخاب کنید. در فهرست، پیشوند «[test]» به آن اضافه خواهد شد. وقتی ادغام [آزمایشی] خود را از فهرست انتخاب می‌کنید، باید برنامه‌تان را باز کند.
    6. بررسی کنید که برنامه‌تان راه‌اندازی شده باشد و آزمایش جریان مجوزدهی را شروع کنید.
قبلی
ایجاد یکپارچه‌سازی «ابر به ابر»
بعدی
iOS