فعال و سفارشی‌سازی کردن انتقال بین‌دستگاهی

«ادامه دادن در» روش‌ها و کلاس‌های جدیدی را برای شما معرفی می‌کند تا پشتیبانی از این ویژگی را نشان دهید و داده‌های لازم را که منتقل می‌شود ارائه دهید. این کار به شما امکان می‌دهد تجربه کاربری را به‌درستی در دستگاه گیرنده ازسر بگیرید.

فعال کردن پشتیبانی

پشتیبانی از «ادامه دادن در» (به‌طور پیش‌فرض خاموش است) باید به‌ازای هر فعالیت پیاده‌سازی شود. برای فعال کردن این ویژگی، setHandoffEnabled را فراخوانی کنید تا نشان دهید فعالیت کنونی برای انتقال آماده است. وقتی setHandoffEnabled(true, null) فراخوانی می‌شود، انتقال می‌تواند در هر نقطه‌ای از فعالیت اتفاق بیفتد، بنابراین فقط زمانی آن را فراخوانی کنید که فعالیت آماده انتقال باشد.

می‌توانید بررسی کنید که آیا فعالیت «ادامه دادن در» را با isHandoffEnabled فعال کرده است یا نه. اگر فعالیتی انتقال را فعال کرده باشد، باید onHandoffActivityDataRequested را نیز پیاده‌سازی کند تا مطمئن شود که HandoffActivityData غیرتهی برمی‌گرداند، زیرا هیچ رفتار پیش‌فرضی پیاده‌سازی نشده است.

class MyHandoffActivity : Activity() {

    ...

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Do stuff
    ...
    // Enable handoff
    setHandoffEnabled(true, null)
  }

  // Override and implement onHandoffActivityDataRequested
  override fun onHandoffActivityDataRequested(handoffRequestInfo: HandoffActivityDataRequestInfo) : HandoffActivityData {
    // Create and return handoff data
  }
}

شیء HandoffActivityData را با هرگونه موارد اضافی مربوط و یک URI بازگشتی پیکربندی می‌کنید تا به «ادامه دادن در» اطلاع دهید که چگونه انتقال به دستگاه گیرنده را انجام دهد.

در دو موقعیت سیستم به این داده‌ها نیاز دارد:

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

بررسی وضعیت

کلاس HandoffActivityDataRequestInfo اطلاعاتی درباره درخواست فعلی برای واگذاری فعالیت ارائه می‌دهد. از isActiveRequest برای تعیین اینکه آیا درخواست درحال‌حاضر فعال است یا نه استفاده کنید. اگر روش برگرداند

• true، فعالیت فعلی در پیش‌زمینه است و کاربر درخواست کرده است که در دستگاه دیگری ادامه دهد، اما اگر
• false، فعالیت متوقف شده است و در پس‌زمینه است، اما کاربر ممکن است در آینده درخواست انتقال کند.

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

// Override and implement onHandoffActivityDataRequested
override fun onHandoffActivityDataRequested(handoffRequestInfo: HandoffActivityDataRequestInfo) : HandoffActivityData {

  // Check whether the handoff request is active
  if (handoffRequestInfo.isActiveRequest()) {
    // Asynchronously show UI to let users know a handoff is in progress
  }

  // Create and return handoff data
}

ایجاد داده‌های واگذاری

برای اطمینان از اینکه همه داده‌های مرتبط و ضروری درطول انتقال با ویژگی «ادامه دادن در» منتقل می‌شود، باید داده‌ها را در شیء HandoffActivityData اضافه کنید.

کلاس HandoffActivityData نشان‌دهنده داده‌های واگذاری مرتبط با یک فعالیت است. HandoffActivityData به «ادامه دادن در» اطلاع می‌دهد که چگونه فعالیتی را در دستگاه گیرنده مدیریت و بازآفرینی کند. داده‌های انتقال شامل موارد زیر است:

• نام مؤلفه (الزامی): ComponentName مربوط به فعالیتی که باید در دستگاه گیرنده راه‌اندازی شود تا سفر کاربر پس‌از انتقال ازسر گرفته شود. در اکثر موارد و برای تکرار دقیق فعالیت، این نام مؤلفه برای همان فعالیتی خواهد بود که HandoffActivityData را ایجاد می‌کند.
• موارد اضافی (اختیاری): می‌توانید موارد اضافی را که در شروع Intent فعالیت گنجانده خواهد شد مشخص کنید. این یک PersistableBundle است که می‌توان از آن برای ارائه اطلاعات بیشتر به مؤلفه استفاده کرد. اندازه موارد اضافی باید کمتر از ۵۰ کیلوبایت باشد.

برای ایجاد کردن اشیای HandoffActivityData، از کلاس سازنده، HandoffActivityData.Builder استفاده کنید. سازنده جدیدی را با ارسال ComponentName فعالیتی که باید واگذاری را دریافت کند (برای مثال، this.getComponentName برای Activity فعلی، یا یک ComponentName(this, TargetActivity::class.java) صریح) بسازید. سپس از روش setExtras برای مشخص کردن موارد اضافی اختیاری استفاده کنید. درنهایت، build را فراخوانی کنید تا شیء HandoffActivityData ایجاد شود.

// Override and implement onHandoffActivityDataRequested
override fun onHandoffActivityDataRequested(handoffRequestInfo: HandoffActivityDataRequestInfo) : HandoffActivityData {

  // Check whether the handoff request is active
  if (handoffRequestInfo.isActiveRequest()) {
    // Asynchronously show UI to let users know a handoff is in progress
  }

  val extras: PersistableBundle = PersistableBundle()
  // Put relevant and necessary values into extras (e.g. scroll position)
  extras.putString("data_id", getDataId())
  extras.putInt("scroll_position", getScrollPosition())

  // Create and return handoff data
  return HandoffActivityData.Builder(getComponentName()) // Designate handoff to the same activity
    .setExtras(extras)
    .build()
}

تنظیم گزینه بازگشت وب

درصورتی‌که فعالیت مشخص‌شده در دستگاه گیرنده شروع نشود، می‌توانید از setFallbackUri نیز استفاده کنید تا به‌طور اختیاری نشانی وب جایگزینی تنظیم کنید که در مرورگر پیش‌فرض کاربر در دستگاه باز شود.

برای اینکه پیشنهاد «ادامه دادن در» در دستگاه‌های گیرنده‌ای که برنامه‌تان در آن‌ها نصب نشده است نشان داده شود، هنگام فراخوانی setHandoffEnabled، نمونه HandoffActivityParams را با setAllowHandoffWithoutPackageInstalled تنظیم‌شده روی true ارسال کنید:

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

سپس نشانی وب بازگشتی را در HandoffActivityData خود اضافه کنید:

val fallbackWebLink: Uri = Uri.parse("https://myapp.com/fallback?query=" + paramVal)

val handoffData: HandoffActivityData = HandoffActivityData.Builder(getComponentName())
  .setExtras(extras)
  .setFallbackUri(fallbackWebLink)
  .build()

پیاده‌سازی مستقیم در وب

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

val webHandoffLink: Uri = Uri.parse("https://myapp.com/handoff?query=" + paramVal)

val handoffData: HandoffActivityData = HandoffActivityData.createWebHandoff(webHandoffLink)

دریافت و مدیریت قصد انتقال

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

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

class MyHandoffActivity : Activity() {

    ...

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

    // Get the launch intent and retrieve extras
    val intent: Intent = getIntent()
    if (intent != null && intent.hasExtra("data_id")) {
      val dataID: String = intent.getStringExtra("data_id")
      // Retrieve the data that corresponds to the data ID
      ...
      // Populate activity UI with relevant data
      ...

      if (intent.hasExtra("scroll_position")) {
        val scrollPosition: Int = intent.getIntExtra("scroll_position", 0)
        // Move the page to the scroll position
        ...
      }
    }
  }
}