Benutzerdefinierte Schnelleinstellungen-Kacheln für Ihre App erstellen

Schnelleinstellungen sind Kacheln, die im Bereich „Schnelleinstellungen“ angezeigt werden, die Aktionen darstellen, die Nutzer antippen können, um wiederkehrende Aufgaben schnell zu erledigen. Ihre App kann Nutzern über die TileService Klasse eine benutzerdefinierte Kachel zur Verfügung stellen und den Status der Kachel mit einem Tile-Objekt verfolgen. Sie können beispielsweise eine Kachel erstellen, mit der Nutzer ein von Ihrer App bereitgestelltes VPN aktivieren oder deaktivieren können.

Schnelleinstellungen mit aktivierter und deaktivierter VPN-Kachel
Abbildung 1. Bereich „Schnelleinstellungen“ mit aktivierter und deaktivierter VPN-Kachel.

Zeitpunkt für das Erstellen einer Kachel festlegen

Wir empfehlen, Kacheln für bestimmte Funktionen zu erstellen, auf die Nutzer voraussichtlich häufig oder schnell zugreifen müssen (oder beides). Die effektivsten Kacheln erfüllen beide Anforderungen und ermöglichen einen schnellen Zugriff auf häufig ausgeführte Aktionen.

Sie könnten beispielsweise eine Kachel für eine Fitness-App erstellen, mit der Nutzer schnell eine Trainingseinheit starten können. Wir würden jedoch nicht empfehlen, eine Kachel für dieselbe App zu erstellen, mit der Nutzer ihren gesamten Trainingsverlauf einsehen können.

Anwendungsfälle für Fitness-App-Kacheln
Abbildung 2 Beispiele für empfohlene und nicht empfohlene Kacheln für eine Fitness-App.

Um die Sichtbarkeit und Benutzerfreundlichkeit Ihrer Kachel zu verbessern, empfehlen wir, bestimmte Praktiken zu vermeiden:

  • Verwenden Sie keine Kacheln, um eine App zu starten. Verwenden Sie stattdessen eine App-Verknüpfung oder einen Standard Launcher.

  • Verwenden Sie keine Kacheln für einmalige Nutzeraktionen. Verwenden Sie stattdessen eine App-Verknüpfung oder eine Benachrichtigung.

  • Erstellen Sie nicht zu viele Kacheln. Wir empfehlen maximal zwei pro App. Verwenden Sie stattdessen eine App-Verknüpfung.

  • Verwenden Sie keine Kacheln, die Informationen anzeigen, aber für Nutzer nicht interaktiv sind. Verwenden Sie stattdessen eine Benachrichtigung oder ein Widget.

Kachel erstellen

Um eine Kachel zu erstellen, müssen Sie zuerst ein geeignetes Kachelsymbol erstellen und dann TileService in der Manifestdatei Ihrer App erstellen und deklarieren.

Im Beispiel für Schnelleinstellungen wird gezeigt, wie Sie eine Kachel erstellen und verwalten.

Benutzerdefiniertes Symbol erstellen

Sie müssen ein benutzerdefiniertes Symbol bereitstellen, das auf der Kachel im Bereich „Schnelleinstellungen“ angezeigt wird. (Sie fügen dieses Symbol hinzu, wenn Sie TileService deklarieren, wie im nächsten Abschnitt beschrieben.) Das Symbol muss einfarbig weiß mit transparentem Hintergrund sein, 24 × 24 dp groß sein und als VectorDrawable vorliegen.

Beispiel für ein Vektor-Drawable
Abbildung 3. Beispiel für ein Vektordrawable.

Erstellen Sie ein Symbol, das visuell auf den Zweck Ihrer Kachel hinweist. So können Nutzer leicht erkennen, ob Ihre Kachel ihren Anforderungen entspricht. Sie könnten beispielsweise ein Stoppuhrsymbol für eine Kachel für eine Fitness-App erstellen, mit der Nutzer eine Trainingseinheit starten können.

TileService erstellen und deklarieren

Erstellen Sie einen Dienst für Ihre Kachel, der die Klasse TileService erweitert.

Kotlin

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()
  }
}

Java

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();
  }
}

Deklarieren Sie TileService in der Manifestdatei Ihrer App. Fügen Sie den Namen und das Label von TileService, das benutzerdefinierte Symbol, das Sie im vorherigen Abschnitt erstellt haben, und die entsprechende Berechtigung hinzu.

 <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 verwalten

Nachdem Sie TileService in Ihrem App-Manifest erstellt und deklariert haben, müssen Sie den Status verwalten.

TileService ist ein gebundener Dienst. TileService wird gebunden, wenn er von Ihrer App angefordert wird oder wenn das System mit ihm kommunizieren muss. Ein typischer Lebenszyklus eines gebundenen Dienstes enthält die folgenden vier Callback-Methoden: onCreate(), onBind(), onUnbind() und onDestroy(). Diese Methoden werden vom System jedes Mal aufgerufen, wenn der Dienst in eine neue Lebenszyklusphase eintritt.

Übersicht über den Lebenszyklus von TileService

Zusätzlich zu den Callbacks, die den Lebenszyklus des gebundenen Dienstes steuern, müssen Sie andere Methoden implementieren, die spezifisch für den Lebenszyklus von TileService sind. Diese Methoden können außerhalb von onCreate() und onDestroy() aufgerufen werden, da die Service Lebenszyklusmethoden und die TileService Lebenszyklusmethoden in zwei separaten asynchronen Threads aufgerufen werden.

Der Lebenszyklus von TileService enthält die folgenden Methoden, die vom System jedes Mal aufgerufen werden, wenn TileService in eine neue Lebenszyklusphase eintritt:

  • onTileAdded(): Diese Methode wird nur aufgerufen, wenn der Nutzer Ihre Kachel zum ersten Mal hinzufügt und wenn der Nutzer Ihre Kachel entfernt und wieder hinzufügt. Dies ist der beste Zeitpunkt für eine einmalige Initialisierung. Dies reicht jedoch möglicherweise nicht für die gesamte erforderliche Initialisierung aus.

  • onStartListening() und onStopListening(): Diese Methoden werden immer aufgerufen, wenn Ihre App die Kachel aktualisiert, und werden häufig aufgerufen. TileService bleibt zwischen onStartListening() und onStopListening() gebunden, sodass Ihre App die Kachel ändern und Updates senden kann.

  • onTileRemoved(): Diese Methode wird nur aufgerufen, wenn der Nutzer Ihre Kachel entfernt.

Abhörmodus auswählen

TileService hört im Aktivmodus oder Nicht-Aktivmodus. Wir empfehlen, den Aktivmodus zu verwenden, den Sie im App-Manifest deklarieren müssen. Andernfalls ist TileService der Standardmodus und muss nicht deklariert werden.

Gehen Sie nicht davon aus, dass TileService außerhalb des Methodenpaars onStartListening() und onStopListening() ausgeführt wird.

Verwenden Sie den Aktivmodus für ein TileService, das seinen Status in einem eigenen Prozess abhört und überwacht. Ein TileService im Aktivmodus ist für onTileAdded(), onTileRemoved(), Tippereignisse und auf Anfrage des App-Prozesses gebunden.

Wir empfehlen den Aktivmodus, wenn TileService benachrichtigt wird, wenn der Status der Kachel durch einen eigenen Prozess aktualisiert werden soll. Aktive Kacheln entlasten das System, da sie nicht jedes Mal gebunden werden müssen, wenn der Bereich „Schnelleinstellungen“ für den Nutzer sichtbar wird.

Die statische TileService.requestListeningState() Methode kann aufgerufen werden, um den Start des Abhörstatus anzufordern und einen Callback an onStartListening() zu erhalten.

Sie können den Aktivmodus deklarieren, indem Sie den META_DATA_ACTIVE_TILE zu Ihrer Manifestdatei Ihrer App hinzufügen.

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

Nicht-Aktivmodus

Der Nicht-Aktivmodus ist der Standardmodus. Ein TileService befindet sich im Nicht-Aktivmodus, wenn er gebunden ist, sobald Ihre Kachel für den Nutzer sichtbar ist. Das bedeutet, dass TileService möglicherweise zu Zeiten erstellt und gebunden wird, die außerhalb seiner Kontrolle liegen. Er kann auch entbunden und zerstört werden, wenn der Nutzer die Kachel nicht sieht.

Ihre App erhält einen Callback an onStartListening(), nachdem der Nutzer den Bereich „Schnelleinstellungen“ geöffnet hat. Sie können Ihr Tile-Objekt beliebig oft zwischen onStartListening() und onStopListening() aktualisieren.

Sie müssen den Nicht-Aktivmodus nicht deklarieren. Fügen Sie einfach META_DATA_ACTIVE_TILE nicht in der Manifestdatei Ihrer App hinzu.

Übersicht über die Kachelstatus

Nachdem ein Nutzer Ihre Kachel hinzugefügt hat, befindet sie sich immer in einem der folgenden Status.

  • STATE_ACTIVE: Gibt einen aktivierten oder eingeschalteten Status an. Der Nutzer kann in diesem Status mit Ihrer Kachel interagieren.

    Für eine Kachel einer Fitness-App, mit der Nutzer eine zeitgesteuerte Trainingseinheit starten können, würde STATE_ACTIVE beispielsweise bedeuten, dass der Nutzer eine Trainingseinheit gestartet hat und der Timer läuft.

  • STATE_INACTIVE: Gibt einen deaktivierten oder pausierten Status an. Der Nutzer kann in diesem Status mit Ihrer Kachel interagieren.

    Um das Beispiel der Fitness-App-Kachel noch einmal zu verwenden: Eine Kachel in STATE_INACTIVE bedeutet, dass der Nutzer keine Trainingseinheit gestartet hat, dies aber tun könnte.

  • STATE_UNAVAILABLE: Gibt einen vorübergehend nicht verfügbaren Status an. Der Nutzer kann in diesem Status nicht mit Ihrer Kachel interagieren.

    Eine Kachel in STATE_UNAVAILABLE bedeutet beispielsweise, dass die Kachel aus irgendeinem Grund derzeit nicht für den Nutzer verfügbar ist.

Das System legt nur den Anfangsstatus Ihres Tile-Objekts fest. Sie legen den Status des Tile-Objekts für den Rest des Lebenszyklus fest.

Das System kann das Kachelsymbol und den Hintergrund einfärben, um den Status Ihres Tile-Objekts widerzuspiegeln. Tile -Objekte, die auf STATE_ACTIVE gesetzt sind, sind am dunkelsten, während STATE_INACTIVE und STATE_UNAVAILABLE immer heller werden. Der genaue Farbton ist je nach Hersteller und Version unterschiedlich.

VPN-Kachel mit Farbton, der den Objektstatus widerspiegelt
Abbildung 4 : Beispiele für eine Kachel, die eingefärbt ist, um den Kachelstatus widerzuspiegeln (aktiver, inaktiver und nicht verfügbarer Status).

Kachel aktualisieren

Sie können Ihre Kachel aktualisieren, sobald Sie einen Callback an onStartListening() erhalten. Je nach Modus der Kachel kann sie mindestens einmal aktualisiert werden, bis Sie einen Callback an onStopListening() erhalten.

Im Aktivmodus können Sie Ihre Kachel genau einmal aktualisieren, bevor Sie einen Callback an onStopListening() erhalten. Im Nicht-Aktivmodus können Sie Ihre Kachel beliebig oft zwischen onStartListening() und onStopListening() aktualisieren.

Sie können Ihr Tile Objekt mit getQsTile() abrufen. Rufen Sie die folgenden Methoden auf, um bestimmte Felder Ihres Tile-Objekts zu aktualisieren:

Sie müssen updateTile() aufrufen, um Ihre Kachel zu aktualisieren, sobald Sie die Felder des Tile Objekts auf die richtigen Werte gesetzt haben. Dadurch werden die aktualisierten Kacheldaten vom System geparst und die Benutzeroberfläche aktualisiert.

Kotlin

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()
}

Java

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();
}

Tippen verarbeiten

Nutzer können auf Ihre Kachel tippen, um eine Aktion auszulösen, wenn sich Ihre Kachel in STATE_ACTIVE oder STATE_INACTIVE befindet. Das System ruft dann den onClick()-Callback Ihrer App auf.

Sobald Ihre App einen Callback an onClick() erhält, kann sie ein Dialogfeld oder eine Aktivität starten, Hintergrundaufgaben auslösen oder den Status Ihrer Kachel ändern.

Kotlin

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()
}

Java

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();
}

Dialogfeld starten

showDialog() minimiert den Bereich „Schnelleinstellungen“ und zeigt ein Dialogfeld an. Verwenden Sie ein Dialogfeld, um Ihrer Aktion Kontext hinzuzufügen, wenn zusätzliche Eingaben oder die Nutzereinwilligung erforderlich sind.

Aktivität starten

startActivityAndCollapse() startet eine Aktivität und minimiert gleichzeitig den Bereich. Aktivitäten sind nützlich, wenn detailliertere Informationen als in einem Dialogfeld angezeigt werden sollen oder wenn Ihre Aktion sehr interaktiv ist.

Wenn Ihre App eine erhebliche Nutzerinteraktion erfordert, sollte die App nur als letztes Mittel eine Aktivität starten. Verwenden Sie stattdessen ein Dialogfeld oder eine Umschaltfläche.

Wenn Sie lange auf eine Kachel tippen, wird der Bildschirm App-Info für den Nutzer angezeigt. Wenn Sie dieses Verhalten überschreiben und stattdessen eine Aktivität zum Festlegen von Einstellungen starten möchten, fügen Sie einer Ihrer Aktivitäten mit ACTION_QS_TILE_PREFERENCES einen <intent-filter> hinzu.

Ab Android API 28 muss PendingIntent das Flag Intent.FLAG_ACTIVITY_NEW_TASK haben:

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

Alternativ können Sie das Flag im Abschnitt Activity in AndroidManifest.xml hinzufügen.

Kachel als umschaltbar markieren

Wir empfehlen, Ihre Kachel als umschaltbar zu markieren, wenn sie hauptsächlich als Zwei-Zustands-Schalter fungiert (was das häufigste Verhalten von Kacheln ist). So können Sie dem Betriebssystem Informationen zum Verhalten der Kachel zur Verfügung stellen und die allgemeine Barrierefreiheit verbessern.

Setzen Sie die Metadaten TOGGLEABLE_TILE auf true, um Ihre Kachel als umschaltbar zu markieren.

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

Nur sichere Aktionen auf sicher gesperrten Geräten ausführen

Ihre Kachel wird möglicherweise auf gesperrten Geräten über dem Sperrbildschirm angezeigt. Wenn die Kachel vertrauliche Informationen enthält, prüfen Sie den Wert von isSecure(), um festzustellen, ob sich das Gerät in einem sicheren Zustand befindet. TileService sollte sein Verhalten entsprechend ändern.

Wenn die Kachelaktion sicher ausgeführt werden kann, während das Gerät gesperrt ist, verwenden Sie startActivity() um eine Aktivität über dem Sperrbildschirm zu starten.

Wenn die Kachelaktion nicht sicher ist, verwenden Sie unlockAndRun(), um den Nutzer aufzufordern, sein Gerät zu entsperren. Bei Erfolg führt das System das Runnable-Objekt aus, das Sie an diese Methode übergeben.

Kachel kategorisieren

Um die Nutzerfreundlichkeit in den Schnelleinstellungen zu verbessern, können Sie Ihre Kachel kategorisieren. Das System organisiert Kacheln in Kategorien wie „Verbindung“, „Anzeige“ und „Datenschutz“. Das System verwendet diese Kategorien, um Kacheln im Bearbeitungsmodus der Schnelleinstellungen zu sortieren und zu gruppieren. So können Nutzer sie leichter finden und verwalten.

Implementierung

Wenn Sie eine Kategorie für TileService angeben möchten, fügen Sie der Dienstdeklaration in der Datei AndroidManifest.xml ein Metadatenfeld hinzu:

  • Fügen Sie in AndroidManifest.xml im Element <service> für TileService ein Element <meta-data> hinzu.
  • android:name: Setzen Sie diesen Wert auf android.service.quicksettings.TILE_CATEGORY.
  • android:value: Weisen Sie eine der vordefinierten Kategorienkonstanten zu, z. B. android.service.quicksettings.CATEGORY_CONNECTIVITY oder android.service.quicksettings.CATEGORY_DISPLAY.

Wie im folgenden Beispiel gezeigt:

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

Die API bietet eine Reihe vordefinierter Kategorien zur Auswahl. Diese Kategorien sind als Stringkonstanten in der Klasse TileService definiert.

Wenn keine Kategorie angegeben ist, weist das System automatisch eine Standardkategorie zu:

  • Von System-Apps:Für Kacheln, die Teil einer Systemanwendung sind.
  • Von Apps, die du installiert hast:Für Kacheln aus vom Nutzer installierten Anwendungen.

Obwohl auf Google Pixel-Geräten Kategorien in den Schnelleinstellungen verwendet werden, können OEMs diese Kategorieinformationen in ihren jeweiligen System-UIs verwenden oder ignorieren.

Nutzer auffordern, Ihre Kachel hinzuzufügen

Wenn Nutzer Ihre Kachel manuell hinzufügen möchten, müssen sie mehrere Schritte ausführen:

  1. Wischen Sie nach unten, um den Bereich „Schnelleinstellungen“ zu öffnen.
  2. Tippen Sie auf die Schaltfläche „Bearbeiten“.
  3. Scrollen Sie durch alle Kacheln auf dem Gerät, bis sie Ihre Kachel finden.
  4. Halten Sie Ihre Kachel gedrückt und ziehen Sie sie in die Liste der aktiven Kacheln.

Der Nutzer kann Ihre Kachel auch jederzeit verschieben oder entfernen.

Ab Android 13 können Sie mit der requestAddTileService() Methode Nutzern das Hinzufügen Ihrer Kachel zu einem Gerät erheblich erleichtern. Mit dieser Methode werden Nutzer aufgefordert, Ihre Kachel schnell direkt zum Bereich „Schnelleinstellungen“ hinzuzufügen. Die Aufforderung enthält den Anwendungsnamen, das angegebene Label und das Symbol.

Eingabeaufforderung für die Schnelleinstellungen Placement API
Abbildung 5 Aufforderung der Quick Settings Placement API.
public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

Der Callback enthält Informationen dazu, ob die Kachel hinzugefügt wurde oder nicht, ob sie bereits vorhanden war oder ob ein Fehler aufgetreten ist.

Entscheiden Sie nach eigenem Ermessen, wann und wie oft Sie Nutzer auffordern. Wir empfehlen, requestAddTileService() nur im Kontext aufzurufen, z. B. wenn der Nutzer zum ersten Mal mit einer Funktion interagiert, die durch Ihre Kachel ermöglicht wird.

Das System kann die Verarbeitung von Anfragen für eine bestimmte ComponentName beenden, wenn sie vom Nutzer zuvor oft genug abgelehnt wurde. Der Nutzer wird aus dem Context ermittelt, der zum Abrufen dieses Dienstes verwendet wird. Er muss mit dem aktuellen Nutzer übereinstimmen.