Benutzerdefinierte Schnelleinstellungen-Kacheln für Ihre App erstellen

Schnelleinstellungen sind Kacheln im Schnelleinstellungsbereich, die Aktionen darstellen, auf die Nutzer tippen können, um wiederkehrende Aufgaben schnell zu erledigen. Deine App kann Nutzern über die Klasse TileService eine benutzerdefinierte Kachel zur Verfügung stellen und den Status der Kachel mit einem Tile-Objekt verfolgen. Du kannst beispielsweise eine Kachel erstellen, mit der Nutzer ein von deiner App bereitgestelltes VPN aktivieren oder deaktivieren können.

Schnelleinstellungen mit aktivierter und deaktivierter VPN-Kachel
Abbildung 1. Schnelleinstellungen mit aktivierter und deaktivierter VPN-Kachel.

Entscheiden, wann eine Kachel erstellt werden soll

Wir empfehlen, Kacheln für bestimmte Funktionen zu erstellen, auf die Nutzer entweder häufig oder schnell zugreifen müssen (oder beides). Die effektivsten Kacheln sind diejenigen, die beide Eigenschaften erfüllen und schnellen Zugriff auf häufig ausgeführte Aktionen bieten.

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

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

Damit deine Kachel leichter gefunden und verwendet werden kann, empfehlen wir, bestimmte Praktiken zu vermeiden:

  • Vermeide es, Apps über Kacheln zu starten. Verwende stattdessen eine App-Verknüpfung oder einen Standard-Launcher.

  • Verwende 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. Verwende stattdessen eine App-Verknüpfung.

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

Tile erstellen

Wenn du eine Tile erstellen möchtest, musst du zuerst ein passendes Tile-Symbol erstellen und dann deine TileService in der Manifestdatei deiner App erstellen und deklarieren.

Das Beispiel für Schnelleinstellungen zeigt, wie Sie eine Kachel erstellen und verwalten.

Benutzerdefiniertes Symbol erstellen

Du musst ein benutzerdefiniertes Symbol angeben, das auf der Kachel in den Schnelleinstellungen angezeigt wird. (Sie fügen dieses Symbol hinzu, wenn Sie die TileService deklarieren, wie im nächsten Abschnitt beschrieben.) Das Symbol muss einfarbig weiß mit transparentem Hintergrund sein, eine Größe von 24 × 24 dp haben und im Format VectorDrawable vorliegen.

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

Erstelle ein Symbol, das den Zweck deiner Kachel visuell andeutet. So können Nutzer feststellen, ob Ihre Kachel ihren Anforderungen entspricht. Du kannst beispielsweise ein Stoppuhr-Symbol für eine Kachel einer Fitness-App erstellen, mit der Nutzer eine Trainingseinheit starten können.

TileService erstellen und deklarieren

Erstelle einen Dienst für deine Tile, der die Klasse TileService erweitert.

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

Deklarieren Sie die TileService in der Manifestdatei Ihrer App. Fügen Sie den Namen und das Label Ihres TileService (bis zu 18 Zeichen für android:label), das benutzerdefinierte Symbol, das Sie im vorherigen Abschnitt erstellt haben, und die entsprechende Berechtigung hinzu.

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     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 die TileService im App-Manifest erstellt und deklariert haben, müssen Sie ihren Status verwalten.

TileService ist ein gebundener Dienst. Der 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 TileService-Lebenszyklus

Zusätzlich zu den Callbacks, die den Lebenszyklus des gebundenen Dienstes steuern, musst du weitere Methoden implementieren, die für den Lebenszyklus von TileService spezifisch 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 umfasst 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 deine Tile zum ersten Mal hinzufügt und wenn er sie 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 dann aufgerufen, wenn die App die Kachel aktualisiert. Sie werden häufig aufgerufen. Die TileService bleibt zwischen onStartListening() und onStopListening() gebunden, sodass deine App die Kachel ändern und Updates senden kann.

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

Wiedergabemodus auswählen

Dein TileService hört im aktiven oder nicht aktiven Modus zu. Wir empfehlen, den aktiven Modus 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 Ihr TileService außerhalb des Methodenpaars onStartListening() und onStopListening() existiert.

Verwenden Sie den aktiven Modus für einen TileService, der in seinem eigenen Prozess auf seinen Status wartet und ihn überwacht. Ein TileService im Aktivmodus ist an onTileAdded(), onTileRemoved(), Tippereignisse und an die Anforderung durch den App-Prozess gebunden.

Wir empfehlen den aktiven Modus, wenn deine TileService benachrichtigt wird, wenn der Kachelstatus durch einen eigenen Prozess aktualisiert werden soll. Aktive Kacheln belasten das System weniger, da sie nicht jedes Mal gebunden werden müssen, wenn das Schnelleinstellungsfeld für den Nutzer sichtbar wird.

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

Sie können den aktiven Modus deklarieren, indem Sie der Manifestdatei Ihrer App META_DATA_ACTIVE_TILE hinzufügen.

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

Inaktiver Modus

Der Standardmodus ist der inaktive Modus. Ein TileService befindet sich im inaktiven Modus, wenn er gebunden ist, während die Kachel für den Nutzer sichtbar ist. Das bedeutet, dass Ihr TileService möglicherweise zu Zeiten erstellt und gebunden wird, die außerhalb Ihrer Kontrolle liegen. Sie kann auch ungebunden und zerstört werden, wenn der Nutzer die Tile nicht ansieht.

Deine App erhält einen Callback an onStartListening(), nachdem der Nutzer die Schnelleinstellungen geöffnet hat. Du kannst das Tile-Objekt zwischen onStartListening() und onStopListening() beliebig oft aktualisieren.

Du musst den inaktiven Modus nicht deklarieren. Füge die META_DATA_ACTIVE_TILE nicht zur Manifestdatei deiner App hinzu.

Übersicht über die Kachelstatus

Nachdem ein Nutzer deine Tile hinzugefügt hat, befindet sie sich immer in einem der folgenden Zustände.

  • STATE_ACTIVE: Gibt an, dass die Funktion aktiviert ist. Der Nutzer kann in diesem Zustand mit der Tile interagieren.

    Bei einer Fitness-App-Kachel, mit der Nutzer eine zeitlich begrenzte 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 an, dass die Funktion deaktiviert oder pausiert ist. Der Nutzer kann in diesem Zustand mit der Tile interagieren.

    Um noch einmal das Beispiel der Fitness-App-Kachel zu verwenden: Eine Kachel im Status STATE_INACTIVE würde bedeuten, dass der Nutzer keine Trainingseinheit gestartet hat, dies aber tun könnte, wenn er möchte.

  • STATE_UNAVAILABLE: Gibt an, dass der Status vorübergehend nicht verfügbar ist. Der Nutzer kann in diesem Status nicht mit der Tile interagieren.

    Eine Kachel in STATE_UNAVAILABLE bedeutet beispielsweise, dass die Kachel dem Nutzer aus irgendeinem Grund derzeit nicht zur Verfügung steht.

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

Das System kann das Symbol und den Hintergrund der Kachel einfärben, um den Status des Tile-Objekts widerzuspiegeln. Tile-Objekte, die auf STATE_ACTIVE festgelegt sind, sind am dunkelsten, während STATE_INACTIVE und STATE_UNAVAILABLE zunehmend heller sind. Der genaue Farbton hängt vom Hersteller und der Version ab.

VPN-Kachel eingefärbt, um Objektstatus widerzuspiegeln
Abbildung 4: Beispiele für eine Kachel, die je nach Status (aktiv, inaktiv oder nicht verfügbar) eingefärbt ist.

Kachel aktualisieren

Du kannst deine Kachel aktualisieren, sobald du einen Rückruf unter onStartListening() erhältst. Je nach Modus der Tile kann sie mindestens einmal aktualisiert werden, bis ein Callback an onStopListening() gesendet wird.

Im aktiven Modus können Sie Ihre Tile genau einmal aktualisieren, bevor Sie einen Callback an onStopListening() erhalten. Im inaktiven Modus können Sie Ihre Kachel zwischen onStartListening() und onStopListening() beliebig oft aktualisieren.

Sie können das Tile-Objekt abrufen, indem Sie getQsTile() aufrufen. Wenn Sie bestimmte Felder des Tile-Objekts aktualisieren möchten, rufen Sie die folgenden Methoden auf:

Du musst updateTile() aufrufen, um deine Tile zu aktualisieren, nachdem du die Felder des Tile-Objekts auf die richtigen Werte gesetzt hast. Dadurch werden die aktualisierten Tile-Daten vom System geparst und die Benutzeroberfläche wird aktualisiert.

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 = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}

Tippen verarbeiten

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

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

var counter = 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()
}

Dialogfeld öffnen

showDialog() minimiert die 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 den Bereich. Aktivitäten sind nützlich, wenn mehr Informationen angezeigt werden sollen, als in einem Dialogfeld möglich ist, oder wenn die Aktion sehr interaktiv ist.

Wenn für Ihre App eine erhebliche Nutzerinteraktion erforderlich ist, sollte die App eine Aktivität nur als letzten Ausweg starten. Verwenden Sie stattdessen ein Dialogfeld oder einen Schalter.

Wenn der Nutzer lange auf eine Kachel tippt, wird der Bildschirm App-Info angezeigt. Wenn du dieses Verhalten überschreiben und stattdessen eine Aktivität zum Festlegen von Einstellungen starten möchtest, füge einer deiner Aktivitäten einen <intent-filter> mit ACTION_QS_TILE_PREFERENCES hinzu.

Ab Android API 28 muss die PendingIntent die 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 in der AndroidManifest.xml im entsprechenden Activity-Abschnitt hinzufügen.

Kachel als umschaltbar markieren

Wir empfehlen, die Kachel als umschaltbar zu kennzeichnen, wenn sie hauptsächlich als Schalter mit zwei Zuständen fungiert (das ist das häufigste Verhalten von Kacheln). So erhält das Betriebssystem Informationen zum Verhalten der Tile und die allgemeine Barrierefreiheit wird verbessert.

Setze die Metadaten TOGGLEABLE_TILE auf true, um deine Kachel als umschaltbar zu kennzeichnen.

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

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

Deine Tile kann auf gesperrten Geräten über dem Sperrbildschirm angezeigt werden. Wenn die Kachel vertrauliche Informationen enthält, prüfe den Wert von isSecure(), um festzustellen, ob sich das Gerät in einem sicheren Zustand befindet. Deine TileService sollte ihr Verhalten entsprechend ändern.

Wenn die Kachelaktion im gesperrten Zustand sicher ausgeführt werden kann, verwende startActivity(), um eine Aktivität über dem Sperrbildschirm zu starten.

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

Kachel kategorisieren

Um die Nutzerfreundlichkeit in den Schnelleinstellungen zu verbessern, kannst du deine Kachel kategorisieren. Das System organisiert Kacheln in Kategorien wie „Konnektivität“, „Display“ und „Datenschutz“. Das System verwendet diese Kategorien, um Kacheln im Bearbeitungsmodus der Schnelleinstellungen zu sortieren und zu gruppieren, damit Nutzer sie leichter finden und verwalten können.

Implementierung

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

  • Fügen Sie in der Datei AndroidManifest.xml im Element <service> für die 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 Kategoriekonstanten zu, z. B. android.service.quicksettings.CATEGORY_CONNECTIVITY oder android.service.quicksettings.CATEGORY_DISPLAY.

Siehe folgendes Beispiel:

<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, aus denen Sie auswählen können. 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 System-App sind.
  • Von Apps, die du installiert hast: Für Kacheln von Apps, die vom Nutzer installiert wurden.

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

Nutzer auffordern, deine Tile hinzuzufügen

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

  1. Wische nach unten, um die Schnelleinstellungen zu öffnen.
  2. Tippe auf den Button „Bearbeiten“.
  3. Sie scrollen durch alle Kacheln auf ihrem Gerät, bis sie deine Kachel finden.
  4. Halte die Kachel gedrückt und ziehe sie in die Liste der aktiven Kacheln.

Der Nutzer kann deine Kachel auch jederzeit verschieben oder entfernen.

Ab Android 13 kannst du die Methode requestAddTileService() verwenden, um Nutzern das Hinzufügen deiner Kachel zu einem Gerät zu erleichtern. Bei dieser Methode werden Nutzer aufgefordert, Ihre Kachel direkt dem Bereich „Schnelleinstellungen“ hinzuzufügen. Die Aufforderung enthält den Namen der Anwendung, das angegebene Label und das Symbol.

Aufforderung zur Platzierung der Schnelleinstellungen-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 darüber, ob die Kachel hinzugefügt wurde, nicht hinzugefügt wurde, 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 über deine Kachel bereitgestellt wird.

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