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

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

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

מתי כדאי ליצור משבצת

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

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

כדי לשפר את החשיפה של המשבצת ואת נוחות השימוש בה, מומלץ להימנע מהשיטות הבאות:

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

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

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

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

יצירת כרטיס מידע

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

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

יצירת סמל מותאם אישית

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

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

יצירה והצהרה על TileService

יוצרים שירות לכרטיס שמרחיב את הכיתה TileService.

class MyQSTileService: TileService() {

  // Called when the user adds your tile.
  override fun onTileAdded() {
    super.onTileAdded()
  }
  // Called when your app can update your tile.
  override fun onStartListening() {
    super.onStartListening()
  }

  // Called when your app can no longer update your tile.
  override fun onStopListening() {
    super.onStopListening()
  }

  // Called when the user taps on your tile in an active or inactive state.
  override fun onClick() {
    super.onClick()
  }
  // Called when the user removes your tile.
  override fun onTileRemoved() {
    super.onTileRemoved()
  }
}

public class MyQSTileService extends TileService {

  // Called when the user adds your tile.
  @Override
  public void onTileAdded() {
    super.onTileAdded();
  }

  // Called when your app can update your tile.
  @Override
  public void onStartListening() {
    super.onStartListening();
  }

  // Called when your app can no longer update your tile.
  @Override
  public void onStopListening() {
    super.onStopListening();
  }

  // Called when the user taps on your tile in an active or inactive state.
  @Override
  public void onClick() {
    super.onClick();
  }

  // Called when the user removes your tile.
  @Override
  public void onTileRemoved() {
    super.onTileRemoved();
  }
}

מגדירים את TileService בקובץ המניפסט של האפליקציה. מוסיפים את השם והתווית של TileService, את הסמל המותאם אישית שיצרתם בקטע הקודם ואת ההרשאה המתאימה.

 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"  // 18-character limit.
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

ניהול TileService

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

TileService הוא שירות מחויב. ה-TileService מחויב כשהאפליקציה מבקשת זאת, או אם המערכת צריכה לתקשר איתו. טיפוסית מחזור החיים של bound-service כולל את ארבע השיטות הבאות של קריאה חוזרת: onCreate(), onBind(), onUnbind() וגם onDestroy(). המערכת מפעילה את השיטות האלה בכל פעם שהשירות נכנס לשלב חדש במחזור החיים.

סקירה כללית של מחזור החיים של TileService

בנוסף לקריאות החזרה (callbacks) ששולטות במחזור החיים של השירות המקושר, צריך להטמיע שיטות אחרות שספציפיות למחזור החיים של TileService. אפשר להפעיל את השיטות האלה מחוץ ל-onCreate() ול-onDestroy() כי השיטות של מחזור החיים של Service והשיטות של מחזור החיים של TileService מופעלות בשני חוטים אסינכרונים נפרדים.

מחזור החיים של TileService כולל את השיטות הבאות שמופעלות על ידי המערכת בכל פעם שה-TileService נכנס לשלב חדש במחזור החיים:

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

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

• onTileRemoved(): ה-method הזה נקרא רק אם המשתמש מסיר את המשבצת שלכם.

בחירת מצב האזנה

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

אל תניחו ש-TileService יהיה מחוץ לשתי השיטות onStartListening() ו-onStopListening().

מצב פעיל (מומלץ)

משתמשים במצב פעיל ל-TileService שמקשיב למצב שלו ומעקב אחריו בתהליך משלו. ערך TileService במצב פעיל מוגבל ל-onTileAdded(), onTileRemoved(), מקישים על אירועים, וכשהתהליך של האפליקציה מבקש זאת.

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

אפשר לקרוא לשיטה הסטטית TileService.requestListeningState() לבקש את התחלת מצב ההאזנה ולקבל התקשרות חזרה אל onStartListening()

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

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
         android:value="true" />
    ...
</service>

מצב לא פעיל

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

האפליקציה מקבלת קריאה חוזרת אל onStartListening() אחרי שהמשתמש פותח את לוח ההגדרות המהירות. אפשר לעדכן את האובייקט Tile כמה פעמים שרוצים בין onStartListening() ל-onStopListening().

אין צורך להצהיר על מצב לא פעיל – פשוט לא להוסיף META_DATA_ACTIVE_TILE לקובץ המניפסט של האפליקציה.

סקירה כללית על מצבי האריחים

אחרי שמשתמש מוסיף את המשבצת שלכם, היא תמיד נמצאת באחד מהמצבים הבאים.

• STATE_ACTIVE: מציין מצב מופעל או מופעל. המשתמש יכול לבצע אינטראקציה עם המשבצת שלכם במצב הזה.

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

• STATE_INACTIVE: מציין מצב מושבת או מושהה. המשתמש יכול לבצע פעולות במשבצה שלכם במצב הזה.

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

• STATE_UNAVAILABLE: מציין מצב של זמינות זמנית. המשתמש לא יכול לבצע פעולות עם המשבצת שלכם במצב הזה.

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

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

המערכת עשויה לבצע גוון את סמל המשבצת ואת הרקע כך שישקפו את מצב אובייקט Tile. אובייקטים מסוג Tile שמוגדרים כ-STATE_ACTIVE הם הכי כהים, ואובייקטים מסוג STATE_INACTIVE ו-STATE_UNAVAILABLE הם בהירים יותר. הגוון המדויק הוא ספציפי ליצרן ולגרסה.

עדכון כרטיס המידע

אפשר יהיה לעדכן את משבצת השידור שלך כשתתבצע שיחה חוזרת אל onStartListening(). בהתאם למצב המשבצת, אפשר לעדכן את המשבצת לפחות פעם אחת עד מתקבלת שיחה חוזרת אל onStopListening().

במצב פעיל, אפשר לעדכן את כרטיס המידע פעם אחת בדיוק לפני שמקבלים קריאה חוזרת אל onStopListening(). במצב לא פעיל, אפשר לעדכן את כרטיס המידע בתור כמה פעמים שרוצים בין onStartListening() ל-onStopListening().

אפשר לאחזר את האובייקט Tile באמצעות קריאה ל-getQsTile(). כדי לעדכן שדות ספציפיים באובייקט Tile, צריך להפעיל את השיטות הבאות:

• setContentDescription()
• setIcon()
• setLabel()
• setState()
• setStateDescription()
• setSubtitle()

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

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
  super.onStartListening()
  val state = getStateFromService()
  qsTile.label = state.label
  qsTile.contentDescription = tile.label
  qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.icon = state.icon
  qsTile.updateTile()
}

public class StateModel {
  final boolean enabled;
  final String label;
  final Icon icon;

  public StateModel(boolean e, String l, Icon i) {
    enabled = e;
    label = l;
    icon = i;
  }
}

@Override
public void onStartListening() {
  super.onStartListening();
  StateModel state = getStateFromService();
  Tile tile = getQsTile();
  tile.setLabel(state.label);
  tile.setContentDescription(state.label);
  tile.setState(state.enabled ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setIcon(state.icon);
  tile.updateTile();
}

ידית ברזים

אם המשבצת שלכם תופיע ב-STATE_ACTIVE או ב-STATE_INACTIVE, המשתמשים יוכלו להקיש עליה כדי להפעיל פעולה. לאחר מכן המערכת מפעילה את פונקציית ה-callback‏ onClick() של האפליקציה.

אחרי שהאפליקציה מקבלת קריאה חוזרת ל-onClick(), היא יכולה להפעיל תיבת דו-שיח או פעילות, להפעיל עבודה ברקע או לשנות את המצב של המשבצת.

var clicks = 0
override fun onClick() {
  super.onClick()
  counter++
  qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.label = "Clicked $counter times"
  qsTile.contentDescription = qsTile.label
  qsTile.updateTile()
}

int clicks = 0;

@Override
public void onClick() {
  super.onClick();
  counter++;
  Tile tile = getQsTile();
  tile.setState((counter % 2 == 0) ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setLabel("Clicked " + counter + " times");
  tile.setContentDescription(tile.getLabel());
  tile.updateTile();
}

הפעלה של תיבת דו-שיח

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

התחלת פעילות

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

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

הקשה ארוכה על משבצת מציגה עבור המשתמש את המסך פרטי האפליקציה. כדי לשנות מברירת המחדל התנהגות זו, ובמקום זאת להפעיל פעילות להגדרת העדפות, <intent-filter> לאחת מהפעילויות שלך עם ACTION_QS_TILE_PREFERENCES.

החל מ-Android API 28, חובה ב-PendingIntent כוללים את Intent.FLAG_ACTIVITY_NEW_TASK:

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}

אפשר גם להוסיף את הדגל ב-AndroidManifest.xml בקובץ ה- קטע Activity.

איך מסמנים משבצת שרוצים להחליף מצב

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

כדי לסמן שאפשר להחליף את המצב של כרטיס המידע, צריך להגדיר את המטא-נתונים של TOGGLEABLE_TILE לערך true.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

ביצוע פעולות בטוחות רק במכשירים שנעולים באופן מאובטח

יכול להיות שהמשבצת תוצג מעל מסך הנעילה במכשירים נעולים. אם האריח מכיל מידע רגיש, יש לבדוק את הערך של isSecure() כדי לקבוע אם המכשיר במצב מאובטח, וה-TileService לשנות את ההתנהגות בהתאם.

אם אפשר לבצע את הפעולה של המשבצת בבטחה בזמן שהמסך נעול, אפשר להשתמש ב-startActivity() כדי להפעיל פעילות מעל מסך הנעילה.

אם הפעולה בכרטיס המידע לא בטוחה, משתמשים ב-unlockAndRun() כדי לבקש מהמשתמש לבצע את הפעולות הבאות: לבטל את הנעילה של המכשיר. אם הפעולה תצליח, המערכת מריצה את האובייקט Runnable שמעבירים לשיטה הזו.

להציג בקשה למשתמש להוסיף את כרטיס המידע

כדי להוסיף את כרטיס המידע שלכם באופן ידני, המשתמשים צריכים לבצע מספר שלבים:

1. מחליקים למטה כדי לפתוח את חלונית ההגדרות המהירות.
2. מקישים על לחצן העריכה.
3. גוללים בין כל כרטיסי המידע במכשיר עד שמוצאים את כרטיס המידע שלכם.
4. לוחצים לחיצה ארוכה על המשבצת וגוררים אותה לרשימה של המשבצות הפעילות.

המשתמש יכול גם להזיז או להסיר את המשבצת שלכם בכל שלב.

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

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

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

חשוב להפעיל שיקול דעת כשמחליטים מתי ובאיזו תדירות להציג בקשות למשתמשים. מומלץ להפעיל את requestAddTileService() רק בהקשר – למשל, בפעם הראשונה שהמשתמש יוצר אינטראקציה עם תכונה שהכרטיסייה שלכם מאפשרת להשתמש בה.

המערכת יכולה להפסיק לעבד בקשות עבור ComponentName אם המשתמש דחה אותה מספיק פעמים בעבר. המשתמש נקבע לפי הערך של Context שמשמש לאחזור השירות הזה – הוא חייב להתאים למשתמש הנוכחי.