פעילות מתמשכת

ב-Wear OS, מתבצעת התאמה בין פעילות מתמשכת לבין התראה מתמשכת מוסיף את ההתראה לפלטפורמות נוספות בממשק המשתמש של Wear OS. כך המשתמשים יכולים להיות מעורבים יותר בפעילויות ממושכות.

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

לדוגמה, משתמש ב-Wear OS עשוי להשתמש באפליקציה לאימון כושר כדי להקליט ריצה פעילות, ואז לצאת מהאפליקציה כדי להתחיל משימה אחרת. כשהמשתמש מנווט אל מחוץ לאפליקציית האימון, האפליקציה מועבר להודעה מתמשכת שקשורה לעבודה ברקע כדי לעדכן את המשתמשים לגבי ההרצה שלהם. ההתראה מספקת למשתמשים עדכונים וגם דרך קלה לגשת אל אפליקציה.

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

באמצעות ממשק ה-API של הפעילות המתמשכת, התראה מתמשכת של אפליקציה עלולה לחשוף מידע למספר פלטפורמות חדשות ונוחות ב-Wear OS כדי לשמור על להיות מעורבים.

הערה: החל מ-Wear OS 4, ההתראות המתמשכות מושפעות מ זמן ריצה של התראה הרשאה.

לדוגמה, באפליקציית האימון הזו, המידע יכול להופיע בשעון של המשתמש פרצוף כמו סמל ריצה שאפשר להקיש עליו:

איור 1. אינדיקטור של פעילות.

בקטע תוצאות אחרונות במרכז האפליקציות הגלובלי מפורטות גם אפליקציות פעילות פעילויות:

איור 2. מרכז אפליקציות גלובלי.

הערה: כשמשתמשים בפעילות מתמשכת, פרטי האפליקציה מופיעים בפלטפורמות חדשות, אבל ההתראה המקורית לא מופיעה יותר במגש ההתראות.

המצבים הבאים מתאימים לשימוש בהודעה מתמשכת שקשורה אל פעילות מתמשכת:

איור 3. טיימר: סופרת באופן פעיל את הזמן ומסתיימת כשהטיימר הושהו או הופסקו.

איור 4. כדי לעבור ניווט לפי פנייה: הכרזה על מסלול הגעה ליעד. מסתיים כשהמשתמש מגיע ליעד או מפסיק את הניווט.

איור 5. מדיה: משמיעה מוזיקה במהלך הפעלה מסוימת. מסתיים מיד אחרי המשתמש משהה את הסשן.

Wear יוצרת פעילויות מתמשכות באופן אוטומטי באפליקציות מדיה.

בCodelab של פעילות מתמשכת אפשר למצוא דוגמה מפורטת ליצירת פעילויות מתמשכות לסוגים אחרים של אפליקציות.

הגדרה

כדי להתחיל להשתמש ב-Ongoing Activity API באפליקציה, צריך להוסיף את הפרטים הבאים של יחסי התלות בקובץ build.gradle של האפליקציה:

dependencies {
  implementation "androidx.wear:wear-ongoing:1.0.0"
  // Includes LocusIdCompat and new Notification categories for Ongoing Activity.
  implementation "androidx.core:core:1.6.0"
}

הערה: כמה קטגוריות חדשות ב-NotificationCompat (אימון, שעון עצר ושיתוף מיקום) עוזרים להבטיח שכל האפליקציות שמשתמשות בפעילות המתמשכת ל-API יש קטגוריה תואמת.

התחלת פעילות מתמשכת

כדי להתחיל, צריך ליצור התראה מתמשכת ולאחר מכן פעילות מתמשכת.

יצירת התראה מתמשכת

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

עליכם להתאים פעילות מתמשכת להודעה מתמשכת. יש הרבה יתרונות בקישור של הפעילות המתמשכת להתראות, כולל:

• התראות הן החלופה במכשירים שאין בהם תמיכה מתמשכת פעילויות. ההתראה היא הפלטפורמה היחידה שהאפליקציה מציגה בזמן ריצה ברקע.
• ב-Android מגרסה 11 ואילך, ההתראה ב-Wear OS מוסתרת כשהאפליקציה גלויה כפעילות מתמשכת בפלטפורמות נוספות.
• בהטמעה הנוכחית נעשה שימוש ב-Notification עצמו בתור מנגנוני תקשורת.

יצירת התראה מתמשכת באמצעות Notification.Builder.setOngoing.

התחלת פעילות מתמשכת

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

Kotlin

var notificationBuilder = NotificationCompat.Builder(this, CHANNEL_ID)
      …
      .setSmallIcon(..)
      .setOngoing(true)

val ongoingActivityStatus = Status.Builder()
    // Sets the text used across various surfaces.
    .addTemplate(mainText)
    .build()

val ongoingActivity =
    OngoingActivity.Builder(
        applicationContext, NOTIFICATION_ID, notificationBuilder
    )
        // Sets the animated icon that will appear on the watch face in
        // active mode.
        // If it isn't set, the watch face will use the static icon in
        // active mode.
        .setAnimatedIcon(R.drawable.ic_walk)
        // Sets the icon that will appear on the watch face in ambient mode.
        // Falls back to Notification's smallIcon if not set.
        // If neither is set, an Exception is thrown.
        .setStaticIcon(R.drawable.ic_walk)
        // Sets the tap/touch event so users can re-enter your app from the
        // other surfaces.
        // Falls back to Notification's contentIntent if not set.
        // If neither is set, an Exception is thrown.
        .setTouchIntent(activityPendingIntent)
        // Here, sets the text used for the Ongoing Activity (more
        // options are available for timers and stopwatches).
        .setStatus(ongoingActivityStatus)
        .build()

ongoingActivity.apply(applicationContext)

notificationManager.notify(NOTIFICATION_ID, builder.build())

Java

NotificationCompat.Builder notificationBuilder = NotificationCompat.Builder(this, CHANNEL_ID)
      …
      .setSmallIcon(..)
      .setOngoing(true);

OngoingActivityStatus ongoingActivityStatus = OngoingActivityStatus.Builder()
    // Sets the text used across various surfaces.
    .addTemplate(mainText)
    .build();

OngoingActivity ongoingActivity =
    OngoingActivity.Builder(
        applicationContext, NOTIFICATION_ID, notificationBuilder
    )
        // Sets the animated icon that will appear on the watch face in
        // active mode.
        // If it isn't set, the watch face will use the static icon in
        // active mode.
        .setAnimatedIcon(R.drawable.ic_walk)
        // Sets the icon that will appear on the watch face in ambient mode.
        // Falls back to Notification's smallIcon if not set.
        // If neither is set, an Exception is thrown.
        .setStaticIcon(R.drawable.ic_walk)
        // Sets the tap/touch event so users can re-enter your app from the
        // other surfaces.
        // Falls back to Notification's contentIntent if not set.
        // If neither is set, an Exception is thrown.
        .setTouchIntent(activityPendingIntent)
        // Here, sets the text used for the Ongoing Activity (more
        // options are available for timers and stopwatches).
        .setStatus(ongoingActivityStatus)
        .build();

ongoingActivity.apply(applicationContext);

notificationManager.notify(NOTIFICATION_ID, builder.build());

השלבים הבאים מציינים את החלק החשוב ביותר בדוגמה הקודמת:

1. התקשרות אל .setOngoing(true) בטלפון NotificationCompat.Builder והגדרת יעדים אופציונליים .

2. ליצור OngoingActivityStatus או אפשרות סטטוס אחרת, שמתוארות בקטע הבא – לייצוג הטקסט.

3. יוצרים OngoingActivity ומגדירים מזהה התראה.

4. התקשרות אל apply() בטלפון OngoingActivity עם ההקשר.

5. קוראים למספר notificationManager.notify() ומעבירים את אותה התראה מזהה שמוגדר בפעילות המתמשכת כדי לקשר ביניהם.

הערה: ההתראה על הפעילות המתמשכת שקשורה לפעילות חייבת להיות מקושרת לערוץ. תעודה מזהה.

סטטוס

אתם משתמשים בStatus לחשוף את הסטטוס הנוכחי בשידור חי של OngoingActivity למשתמש בפלטפורמות חדשות, כמו הפלטפורמות האחרונות במרכז האפליקציות. כדי להשתמש בתכונה, צריך להשתמש תת-מחלקה Status.Builder.

ברוב המקרים, צריך רק הוספת תבנית שמייצג את הטקסט שרוצים שיופיע בקטע תוצאות אחרונות במרכז האפליקציות.

לאחר מכן אפשר להתאים אישית את מראה הטקסט עם span באמצעות השיטה addTemplate(), לציון חלקים דינמיים של הטקסט Status.Part.

הדוגמה הבאה מראה איך להפוך את המילה 'זמן' למילה 'זמן' מופיעות באדום. לדוגמה משתמשת Status.StopwatchPart כדי לייצג שעון עצר בקטע אחרונים במרכז האפליקציות.

Kotlin

val htmlStatus =
        "<p>The <font color=\"red\">time</font> on your current #type# is #time#.</p>"

val statusTemplate =
        Html.fromHtml(
                htmlStatus,
                Html.FROM_HTML_MODE_COMPACT
        )

// Creates a 5 minute timer.
// Note the use of SystemClock.elapsedRealtime(), not System.currentTimeMillis().
val runStartTime = SystemClock.elapsedRealtime() + TimeUnit.MINUTES.toMillis(5)

val status = new Status.Builder()
   .addTemplate(statusTemplate)
   .addPart("type", Status.TextPart("run"))
   .addPart("time", Status.StopwatchPart(runStartTime)
   .build()

Java

String htmlStatus =
        "<p>The <font color=\"red\">time</font> on your current #type# is #time#.</p>";

Spanned statusTemplate =
        Html.fromHtml(
                htmlStatus,
                Html.FROM_HTML_MODE_COMPACT
        );

// Creates a 5 minute timer.
// Note the use of SystemClock.elapsedRealtime(), not System.currentTimeMillis().
Long runStartTime = SystemClock.elapsedRealtime() + TimeUnit.MINUTES.toMillis(5);

Status status = new Status.Builder()
   .addTemplate(statusTemplate)
   .addPart("type", new Status.TextPart("run"))
   .addPart("time", new Status.StopwatchPart(runStartTime)
   .build();

כדי להפנות לחלק מהתבנית, משתמשים בשם שמוקף ב-#. כדי ליצור # בפלט, צריך להשתמש בפונקציה ## בתבנית.

בדוגמה הקודמת השתמשנו HTMLCompat ליצור CharSequence שיועבר לתבנית, וזה קל יותר להגדיר באופן ידני אובייקט Spannable.

התאמות אישיות נוספות

אחרי Status, אפשר להתאים אישית את הפעילות המתמשכת או בדרכים הבאות. עם זאת, ייתכן שההתאמות האישיות האלו לא בהתאם ליישום של ה-OEM.

התראה מתמשכת

• קבוצת הקטגוריות קובעת את העדיפות של הפעילות המתמשכת.
  • CATEGORY_CALL: שיחה קולית או שיחת וידאו נכנסת או בקשה דומה לתקשורת סנכרונית
  • CATEGORY_NAVIGATION: מפה או מסלול מפורט
  • CATEGORY_TRANSPORT: בקרת העברת מדיה להפעלה
  • CATEGORY_ALARM: שעון מעורר או טיימר
  • CATEGORY_WORKOUT: אימון (קטגוריה חדשה)
  • CATEGORY_LOCATION_SHARING: שיתוף מיקום זמני (קטגוריה חדשה)
  • CATEGORY_STOPWATCH: שעון עצר (קטגוריה חדשה)

פעילות מתמשכת

• סמל מונפש: וקטור בשחור-לבן, עדיף עם שקיפות רקע. מוצגת בתצוגת השעון במצב פעיל. אם הסמל המונפש לא צוין, יוצג סמל ברירת המחדל של ההודעה. (סמל ברירת המחדל של ההודעות הוא שונה לכל אפליקציה).

• סמל סטטי: סמל של וקטור עם רקע שקוף. מוצגת ב תצוגת השעון במצב רגישות לסביבה. אם הסמל המונפש לא מוגדר, הסמל הסטטי משמש בתצוגת השעון במצב פעיל. אם לא תספקו את הפרטים האלה, מוצג סמל ההתראה. אם לא הוגדר אף אחד מהם, החריג שודר. (מרכז האפליקציות עדיין משתמש בסמל האפליקציה).

• OngoingActivityStatus: טקסט פשוט או Chronometer. מוצגות ב הקטע תוצאות אחרונות במרכז האפליקציות. אם לא תספקו אותו, ההתראה נעשה שימוש ב"טקסט הקשר".

• כוונת מגע: נעשה שימוש בPendingIntent כדי לחזור לאפליקציה אם המשתמש מקיש על סמל הפעילות המתמשכת. מוצגות בתצוגת השעון או פריט במרכז האפליקציות. היא יכולה להיות שונה מהכוונה המקורית ששימשה כדי להפעיל את האפליקציה. אם לא צוין תוכן, כוונת התוכן של ההודעה היא בשימוש. אם אף אחד מהם לא מוגדר, המערכת תפסול.

• LocusId: המזהה שמקצה את הערך קיצור הדרך של מרכז האפליקציות שאליו תואמת הפעילות המתמשכת. מוצגת ב מרכז האפליקציות בקטע תוצאות אחרונות בזמן שהפעילות מתבצעת. אחרת שסופק, מרכז האפליקציות מסתיר את כל פריטי האפליקציות בקטע פריטים אחרונים אותה חבילה ומציגה רק את הפעילות המתמשכת.

• מזהה פעילות מתמשכת: המזהה המשמש להבחנה בין שיחות אל fromExistingOngoingActivity() כשהאפליקציה פעילה יותר מפעם אחת פעילות.

עדכון פעילות מתמשכת

ברוב המקרים, המפתחים יוצרים התראה מתמשכת חדשה פעילות מתמשכת כשהם צריכים לעדכן את הנתונים במסך. אבל, Ongoing Activity API מציע גם שיטות עוזרות לעדכון OngoingActivity אם רוצים לשמור מופע במקום ליצור אותו מחדש.

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

כדי לעדכן את הפעילות המתמשכת ואת ההתראה שפורסמה, משתמשים באובייקט נוצר לפני מתקשרים אל update(), כמו בדוגמה הבאה:

Kotlin

ongoingActivity.update(context, newStatus)

Java

ongoingActivity.update(context, newStatus);

לנוחיותכם, יש שיטה סטטית ליצירת פעילות מתמשכת.

Kotlin

OngoingActivity.recoverOngoingActivity(context)
               .update(context, newStatus)

Java

OngoingActivity.recoverOngoingActivity(context)
               .update(context, newStatus);

הפסקת פעילות מתמשכת

כשהאפליקציה מסיימת לפעול כפעילות מתמשכת, היא צריכה לבטל רק בהתראה המתמשכת.

אפשר גם לבטל את ההתראה או את הפעילות המתמשכת. כשמדובר בקדמת הבמה, ואז צריך ליצור אותן מחדש כשחוזרים ברקע, אבל זה לא חובה.

השהיית פעילות מתמשכת

אם באפליקציה שלך יש פעולת עצירה מפורשת, עליך להמשיך את הפעילות המתמשכת אחרי ההשהיה בוטלה. עבור אפליקציה ללא פעולת עצירה מפורשת: לסיים את הפעילות כשהיא מושהית.

שיטות מומלצות

כשעובדים עם Ongoing Activity API, חשוב לזכור את הדברים הבאים:

• צריך להתקשר למספר ongoingActivity.apply(context) לפני השיחה notificationManager.notify(...).

• מגדירים סמל סטטי לפעילות המתמשכת שלכם, בצורה מפורשת או כחלופה דרך התראה. אם לא תעשו זאת, תקבלו IllegalArgumentException.

• שימוש בסמלים של וקטורים בשחור-לבן עם רקעים שקופים.

• להגדיר כוונת מגע עבור הפעילות המתמשכת שלכם, בצורה מפורשת או כחלופה באמצעות התראה. אם לא תעשו זאת, תקבלו IllegalArgumentException.

• בשביל NotificationCompat, צריך להשתמש בספריית Core AndroidX core:1.5.0-alpha05+, כולל LocusIdCompat והממשק החדש קטגוריות לאימון כושר, שעון העצר ושיתוף המיקום.

• אם באפליקציה שלך יש יותר מפעילות אחת של MAIN LAUNCHER שהוצהרה ב- מניפסט, פרסום דינמית מקש קיצור לשייך אותו לפעילות המתמשכת שלך באמצעות LocusId.

פרסום התראות על מדיה כשמפעילים מדיה במכשירי Wear OS

אם מופעל תוכן מדיה במכשיר Wear OS, לפרסם התראה במדיה. כך המערכת יכולה ליצור את הפעילות המתמשכת המתאימה.

הערה: אם תוכן מדיה מופעל במכשיר נייד ולא ב-Wear OS במכשיר, אסור לפרסם התראה על מדיה במכשיר Wear OS.

אם משתמשים ב-Media3, ההתראה תפורסם באופן אוטומטי. אם ליצור את ההתראה באופן ידני, הוא צריך להשתמש MediaStyleNotificationHelper.MediaStyle וה-MediaSession התואם צריך להיות פעילות בסשנים מאוכלס.