پشتیبانی از پیوستگی بین‌دستگاهی در Googlebook

کاربران اغلب کارها را در تلفن Android خود شروع می‌کنند—مثل مرور سند، دسته‌بندی پیام‌ها، یا مرور مجموعه‌ای از موارد—و سپس می‌خواهند به Googlebook با نمایشگر بزرگ‌تر، صفحه‌کلید فیزیکی، و فضای کاری چند پنجره‌ای بروند.

ویژگی ادامه دادن در در Android 17 (میانای برنامه کاربردی سطح ۳۷) و بالاتر به نوار وظیفه Googlebook امکان می‌دهد نماد برنامه‌ای (که پیشنهاد نامیده می‌شود) را برای فعالیتی که کاربر در تلفن نزدیکش اجرا می‌کند نمایش دهد. کاربران با یک کلیک می‌توانند فعالیتشان را در Googlebook ادامه دهند.

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

انتخاب جریان واگذاری

قبل‌از فعال کردن انتقال بین‌دستگاهی، تصمیم بگیرید هر فعالیت در برنامه تلفن شما وقتی کاربر پیشنهاد «ادامه در» را در Googlebook انتخاب می‌کند چگونه باز شود:

فعال کردن واگذاری برای فعالیت

«ادامه در» به‌طور پیش‌فرض غیرفعال است و برای هر فعالیت پیکربندی می‌شود. این مراحل را در هر فعالیت ارسال در تلفن دنبال کنید:

1. پس‌از بار شدن فعالیت، با setHandoffEnabled تماس بگیرید و true را ارسال کنید وضعیت موردنیاز برای واگذاری. پس‌از فعال شدن، سیستم می‌تواند داده‌های انتقال را درحالی‌که فعالیت در پیش‌زمینه است یا به پس‌زمینه منتقل می‌شود درخواست کند.
2. برای برگرداندن شیء غیرتهی، onHandoffActivityDataRequested را ملغی کنید HandoffActivityData. هرزمان بخواهید می‌توانید isHandoffEnabled را پویش کنید تا بررسی کنید آیا واگذاری برای فعالیت فعال است یا نه.

import android.app.Activity
import android.app.HandoffActivityData
import android.app.HandoffActivityDataRequestInfo
import android.os.Bundle
import android.os.PersistableBundle

class DocumentEditorActivity : Activity() {

    private var documentId: String = "doc_42"
    private var scrollOffsetPx: Int = 0

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

        // Enable handoff once the activity is ready to transfer state.
        setHandoffEnabled(true, null)
    }

    override fun onHandoffActivityDataRequested(
        handoffRequestInfo: HandoffActivityDataRequestInfo
    ): HandoffActivityData {
        val extras = PersistableBundle().apply {
            putString(EXTRA_DOCUMENT_ID, documentId)
            putInt(EXTRA_SCROLL_OFFSET, scrollOffsetPx)
        }

        return HandoffActivityData.Builder(getComponentName())
            .setExtras(extras)
            .build()
    }

    companion object {
        const val EXTRA_DOCUMENT_ID = "extra_document_id"
        const val EXTRA_SCROLL_OFFSET = "extra_scroll_offset"
    }
}

وضعیت فعالیت بسته برای واگذاری

سیستم در دو سناریو با onHandoffActivityDataRequested تماس می‌گیرد:

• انتقال پیش‌زمینه: فعالیت در پیش‌زمینه تلفن است و کاربر انتقال را از نوار وظیفه Googlebook آغاز می‌کند.
• ضبط وضعیت پس‌زمینه: فعالیت در تلفن به پس‌زمینه منتقل می‌شود و سیستم محموله واگذاری آن را ذخیره می‌کند تا درصورتی‌که کاربر بعداً پیشنهاد را در Googlebook انتخاب کند، از آن استفاده کند.

بررسی کنید آیا درخواست واگذاری فعال است یا نه

بااستفاده از isActiveRequest، HandoffActivityDataRequestInfo را بازرسی کنید تا بین واگذاری آغازشده توسط کاربر فعال و ذخیره پس‌زمینه‌ای تمایز قائل شوید:

• اگر isActiveRequest مقدار true را برگرداند، کاربر فعالانه درخواست کرده است که فعالیت در دستگاه دیگری ادامه یابد درحالی‌که فعالیت نمایان است.
• اگر isActiveRequest مقدار false را برگرداند، سیستم وضعیت را با توقف فعالیت ذخیره می‌کند.

اگر نشانگر دیداری در تلفن نمایش می‌دهید که تأیید می‌کند تکلیف به Googlebook منتقل می‌شود، به‌روزرسانی واسط کاربر را به‌صورت ناهمزمان زمان‌بندی کنید تا onHandoffActivityDataRequested بدون تأخیر برگردد.

اضافه‌های حالت و وب‌گردی جایگزین را پیوست کنید

بار HandoffActivityData حاوی اطلاعات زیر است:

• عنصر هدف (برای واگذاری برنامه به برنامه الزامی است): this.getComponentName() (ComponentName فعالیت) یا ComponentName(this, TargetActivity::class.java) صریح به HandoffActivityData.Builder را ارسال کنید تا مشخص شود کدام فعالیت در Googlebook راه‌اندازی می‌شود.
• موارد اضافی (اختیاری): PersistableBundle را به setExtras() حاوی شناسه‌ها و مختصات رابط کاربری (برای مثال، شناسه‌های سند باز، کلیدهای برگه فعال، یا موقعیت‌های پیمایش) ارسال کنید. حجم دسته‌بندی باید کمتر از ۵۰ کیلوبایت باشد.
• شناسه منبع یکنواخت برگشتی (اختیاری): وب Uri را به setFallbackUri منتقل کنید تا اگر برنامه Android شما نصب نشده باشد، Googlebook بتواند تکلیف را در مرورگر پیش‌فرض باز کند.

import android.app.Activity
import android.app.HandoffActivityData
import android.app.HandoffActivityDataRequestInfo
import android.app.HandoffActivityParams
import android.net.Uri
import android.os.Bundle
import android.os.PersistableBundle

class ArticleReaderActivity : Activity() {

    private var articleId: String = "android-desktop-windowing"
    private var readingProgressPercent: Int = 45

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

        setHandoffEnabled(
            true,
            HandoffActivityParams.Builder()
                .setAllowHandoffWithoutPackageInstalled(true)
                .build()
        )
    }

    override fun onHandoffActivityDataRequested(
        handoffRequestInfo: HandoffActivityDataRequestInfo
    ): HandoffActivityData {
        if (handoffRequestInfo.isActiveRequest()) {
            window.decorView.post {
                onHandoffStartedToSecondaryDevice()
            }
        }

        val extras = PersistableBundle().apply {
            putString(EXTRA_ARTICLE_ID, articleId)
            putInt(EXTRA_READING_PROGRESS, readingProgressPercent)
        }

        val fallbackWebUri = Uri.Builder()
            .scheme("https")
            .authority("example.com")
            .appendPath("articles")
            .appendPath(articleId)
            .appendQueryParameter("progress", readingProgressPercent.toString())
            .build()

        return HandoffActivityData.Builder(getComponentName())
            .setExtras(extras)
            .setFallbackUri(fallbackWebUri)
            .build()
    }

    private fun onHandoffStartedToSecondaryDevice() {
        // Save local drafts and update phone UI without blocking handoff.
    }

    companion object {
        const val EXTRA_ARTICLE_ID = "extra_article_id"
        const val EXTRA_READING_PROGRESS = "extra_reading_progress"
    }
}

پیکربندی انتقال مستقیم به وب

اگر تجربه اصلی رایانه شما در Googlebook برنامه وب است، HandoffActivityParams را با setAllowHandoffWithoutPackageInstalled(true) به setHandoffEnabled منتقل کنید، و به‌جای استفاده از HandoffActivityData.Builder، HandoffActivityData.createWebHandoff را فراخوانی کنید:

import android.app.Activity
import android.app.HandoffActivityData
import android.app.HandoffActivityDataRequestInfo
import android.app.HandoffActivityParams
import android.net.Uri
import android.os.Bundle

class WebDashboardActivity : Activity() {

    private var projectId: String = "proj_901"

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

        setHandoffEnabled(
            true,
            HandoffActivityParams.Builder()
                .setAllowHandoffWithoutPackageInstalled(true)
                .build()
        )
    }

    override fun onHandoffActivityDataRequested(
        handoffRequestInfo: HandoffActivityDataRequestInfo
    ): HandoffActivityData {
        val webUri = Uri.Builder()
            .scheme("https")
            .authority("app.example.com")
            .appendPath("projects")
            .appendPath(projectId)
            .build()

        return HandoffActivityData.createWebHandoff(webUri)
    }
}

دریافت و بازیابی وضعیت در Googlebook

وقتی کاربر پیشنهاد «ادامه دادن در» را در نوار وظیفه Googlebook انتخاب می‌کند، سیستم ComponentName هدف را در پنجره رایانه راه‌اندازی می‌کند و PersistableBundle موارد اضافی را به راه‌اندازی Intent پیوست می‌کند.

در Googlebook، انتقال ورودی را با درنظر گرفتن پردازش پنجره‌ای رایانه و چیدمان‌های چندپانلی مدیریت کنید:

1. استخراج موارد اضافی واگذاری: در هر دو روش onCreate و onNewIntent فعالیت دریافت‌کننده، موارد اضافی را از Intent ورودی بازیابی کنید. مدیریت onNewIntent تضمین می‌کند که اگر فعالیت شما از حالت راه‌اندازی singleTop استفاده کند یا به پنجره رایانه موجودی هدایت شود، پنجره به مورد واگذارشده به‌روزرسانی می‌شود.
2. تطبیق وضعیت با چیدمان‌های چند پانلی: وضعیتی که نمای جزئیات تمام‌صفحه را در تلفن اشغال می‌کرد اغلب به یک مورد انتخاب‌شده در چیدمان فهرست-جزئیات یا پانل پشتیبان در Googlebook نگاشت می‌شود. هم انتخاب فهرست اصلی و هم قاب جزئیات را تکمیل کنید تا پنجره رایانه زمینه‌ای کامل داشته باشد.
3. حفظ وضعیت بازیابی‌شده در تغییر اندازه پنجره: وضعیت واگذارشده را در ViewModel (SavedStateHandle) یا rememberSaveable در Jetpack Compose ذخیره کنید تا تغییر اندازه پنجره با فرم آزاد در Googlebook باعث بازنشانی جلسه بازیابی‌شده نشود.

import android.app.Activity
import android.content.Intent
import android.os.Bundle

class DocumentEditorReceiverActivity : Activity() {

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

        // Restore from the handoff intent only on initial launch so subsequent
        // desktop window configuration changes use saved instance state.
        if (savedInstanceState == null) {
            handleHandoffIntent(intent)
        }
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        handleHandoffIntent(intent)
    }

    private fun handleHandoffIntent(incomingIntent: Intent?) {
        val documentId = incomingIntent?.getStringExtra(EXTRA_DOCUMENT_ID)
            ?: return
        val scrollOffsetPx = incomingIntent.getIntExtra(EXTRA_SCROLL_OFFSET, 0)

        openDocumentInDesktopWorkspace(
            documentId = documentId,
            initialScrollOffsetPx = scrollOffsetPx
        )
    }

    private fun openDocumentInDesktopWorkspace(
        documentId: String,
        initialScrollOffsetPx: Int
    ) {
        // Load the document into the list-detail layout and restore scroll position.
    }

    companion object {
        const val EXTRA_DOCUMENT_ID = "extra_document_id"
        const val EXTRA_SCROLL_OFFSET = "extra_scroll_offset"
    }
}

آزمایش انتقال بین تلفن و Googlebook

برای درستی‌سنجی کردن پیاده‌سازی سرتاسری:

1. آماده کردن هر دو دستگاه
   • در تلفن Android (با Android 17 یا بالاتر) و Googlebook (یا دستگاه آزمایشی در حالت پنجره‌بندی رایانه) به سیستم «حساب Google» یکسانی وارد شوید.
   • بلوتوث را روشن کنید و هر دو دستگاه را به یک شبکه Wi-Fi متصل کنید.
   • در هر دو دستگاه، تنظیمات > دستگاه‌های متصل > اولویت‌های اتصال > خدمات بین‌دستگاهی > ادامه فعالیت را باز کنید، پیام‌واره‌های راه‌اندازی را دنبال کنید، و تکالیف را فعال کنید. برای پیش‌نیازهای کامل محیط، به راه‌اندازی و آزمایش مراجعه کنید.
2. نصب برنامه
   • برای انتقال از برنامه به برنامه، ساختار خود را هم در تلفن و هم در Googlebook نصب کنید.
   • برای وب جانشین یا انتقال مستقیم به وب، ساختار خود را در تلفن نصب کنید و برنامه را در Googlebook نصب نکنید تا بتوانید تأیید کنید که مرورگر نشانی وب موردانتظار را باز می‌کند.
3. راه‌اندازی واگذاری
   • در تلفن، برنامه را باز کنید و به فعالیتی که امکان واگذاری را فراهم می‌کند بروید (برای واگذاری برنامه به برنامه، setHandoffEnabled(true, null) تماس بگیرید، یا هنگام آزمایش با برنامه، HandoffActivityParams را با setAllowHandoffWithoutPackageInstalled(true) ارسال کنید (برنامه در Googlebook نصب نشده باشد)).
   • در Googlebook، سمت چپ نوار وظیفه را برای نماد برنامه با نشان «ادامه در» بررسی کنید و آن را انتخاب کنید.
4. درستی‌سنجی کردن بازیابی رایانه
   • تأیید کنید که برنامه شما در پنجره رایانه (یا برگه مرورگر) در همان مورد و موقعیت پیمایش تلفن باز می‌شود.
   • اندازه پنجره برنامه را در Googlebook تغییر دهید و تأیید کنید که محتوای بازیابی‌شده و انتخاب در انتقال بین کلاس‌های اندازه پنجره حفظ می‌شود.

منابع بیشتر

• ساختن برنامه‌های تطبیقی برای Googlebook
• درباره ویژگی «ادامه دادن در»
• فعال و سفارشی‌سازی کردن واگذاری بین‌دستگاهی
• ذخیره وضعیت‌های میانای کاربر