تفعيل ميزة "النقل بين الأجهزة" وتخصيصها

توفّر ميزة "المتابعة على" طرقًا وفئات جديدة تتيح لك الإشارة إلى توافق تطبيقك مع الميزة وتقديم البيانات اللازمة التي يتم نقلها. يتيح لك ذلك استئناف تجربة المستخدم بشكل صحيح على الجهاز المستلِم.

إتاحة واجهة برمجة التطبيقات

يجب تنفيذ ميزة "المتابعة على" (غير مفعّلة تلقائيًا) لكل نشاط على حدة. لتفعيل الميزة، يمكنك استدعاء 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 لتحديد ما إذا كان الطلب نشطًا حاليًا. إذا عرضت الطريقة

• صحيح، النشاط الحالي في المقدّمة وقد طلب المستخدم المتابعة على جهاز آخر، ولكن إذا
• ‫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 الذي يمكن استخدامه لتقديم معلومات إضافية للمكوّن. يجب أن يكون حجم الإضافات أقل من 50 كيلوبايت.

لإنشاء عناصر 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 لضبط عنوان URL احتياطي يتم فتحه على الجهاز في المتصفّح التلقائي للمستخدم.

للسماح بظهور اقتراح "المتابعة على" على الأجهزة المستلِمة التي لم يتم تثبيت تطبيقك عليها، عليك تمرير مثيل HandoffActivityParams مع ضبط setAllowHandoffWithoutPackageInstalled على true عند استدعاء setHandoffEnabled:

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

بعد ذلك، أدرِج عنوان URL الاحتياطي في 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، عليك معالجة الغرض واسترداد الإضافات التي تحتوي على معلومات حول كيفية إعادة إنشاء النشاط بشكل مناسب.

إذا كنت تحدّد التسليم للنشاط نفسه، يمكنك تلقّي الـ intent في طريقة 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
        ...
      }
    }
  }
}