איך מפעילים ומתאימים אישית את התכונה "העברה בין מכשירים"

התכונה "המשך במכשיר אחר" כוללת שיטות ומחלקות חדשות שמאפשרות לכם לציין תמיכה בתכונה ולספק את הנתונים הנדרשים שמועברים. כך אפשר להמשיך את חוויית המשתמש במכשיר המקבל.

הפעלת התמיכה

צריך להטמיע את התמיכה בתכונה "המשך במכשיר אחר" (מושבתת כברירת מחדל) בכל פעילות בנפרד. כדי להפעיל את התכונה, צריך להפעיל את setHandoffEnabled כדי לציין שהפעילות הנוכחית מוכנה להעברה. אחרי שקוראים ל-setHandoffEnabled(true, null), אפשר להעביר את הפעילות בכל שלב, אז צריך לקרוא לה רק כשהפעילות מוכנה להעברה.

כדי לבדוק אם הפעילות הפעילה את "המשך ב-", אפשר להשתמש ב-isHandoffEnabled. אם הפעילות מאפשרת העברה, צריך גם להטמיע את onHandoffActivityDataRequested כדי לוודא שהיא מחזירה ערך HandoffActivityData שאינו null, כי לא מוטמעת פעולת ברירת מחדל.

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 שאפשר להשתמש בו כדי לספק מידע נוסף לרכיב. גודל הקובץ של התוספות צריך להיות קטן מ-50KB.

כדי ליצור אובייקטים מסוג HandoffActivityData, משתמשים במחלקת ה-builder,‏ 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, ומשתמשים ב-method‏ HandoffActivityData.createWebHandoff כדי ליצור את HandoffActivityData:

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

val handoffData: HandoffActivityData = HandoffActivityData.createWebHandoff(webHandoffLink)

קבלת כוונת העברה וטיפול בה

במכשיר המקבל, האפליקציה צריכה לטפל בהעברה ולשחזר את חוויית המשתמש מהמכשיר השולח. באופן ספציפי, בפעילות שציינתם ב-HandoffActivityData שמוחזר על ידי onHandoffActivityDataRequested, אתם צריכים לטפל ב-intent ולאחזר את הנתונים הנוספים שמכילים מידע על האופן שבו אפשר ליצור מחדש את הפעילות בצורה מתאימה.

אם אתם מציינים את ההעברה לאותה פעילות, אתם יכולים לקבל את ה-Intent ב-method‏ 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
        ...
      }
    }
  }
}