Benutzerdefinierte Schnelleinstellungen-Kacheln für Ihre App erstellen

Schnelleinstellungen sind Kacheln, die im Steuerfeld für Schnelleinstellungen angezeigt werden und Aktionen darstellen, auf die Nutzer tippen können, um wiederkehrende Aufgaben schnell auszuführen. Ihre App kann Nutzern über die Klasse TileService 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.

Festlegen, wann eine Kachel erstellt werden soll

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

Sie können beispielsweise eine Kachel für eine Fitness-App erstellen, mit der Nutzer schnell ein Training starten können. Wir raten jedoch davon ab, für dieselbe App eine Kachel zu erstellen, über die Nutzer ihren gesamten Trainingsverlauf ansehen können.

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

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

• Verwenden Sie keine Kacheln für einmalige Nutzeraktionen. Verwenden Sie stattdessen einen App- oder Benachrichtigungs-Shortcut.

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

• Verwenden Sie keine Ansichten, die Informationen enthalten, aber nicht interaktiv sind. Verwenden Sie stattdessen eine Benachrichtigung oder ein Widget.

Kachel erstellen

Wenn Sie eine Kachel erstellen möchten, müssen Sie zuerst ein geeignetes Kachelsymbol erstellen und dann die TileService in der Manifestdatei Ihrer App erstellen und deklarieren.

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

Benutzerdefiniertes Symbol erstellen

Sie müssen ein benutzerdefiniertes Symbol angeben, das auf der Kachel im Bereich „Schnelleinstellungen“ angezeigt wird. Dieses Symbol fügen Sie beim Deklarieren des TileService hinzu, wie im nächsten Abschnitt beschrieben. Das Symbol muss einfarbig weiß mit einem transparenten Hintergrund sein, eine Größe von 24 × 24 dp haben und die Form eines VectorDrawable haben.

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önnen beispielsweise ein Stoppuhrensymbol für eine Kachel in einer Fitness-App erstellen, mit der Nutzer ein Training starten können.

TileService erstellen und deklarieren

Erstellen Sie einen Dienst für Ihre Kachel, 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()
  }
}

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 Ihre TileService in der Manifestdatei Ihrer App. Fügen Sie den Namen und das Label Ihrer TileService, das im vorherigen Abschnitt erstellte benutzerdefinierte Symbol 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 Ihre TileService in Ihrem App-Manifest erstellt und deklariert haben, müssen Sie ihren Status verwalten.

TileService ist ein gebundener Dienst. Ihre TileService wird gebunden, wenn sie von Ihrer App angefordert wird oder das System mit ihr kommunizieren muss. Ein typischer Lebenszyklus eines gebundenen Dienstes umfasst die folgenden vier Rückrufmethoden: onCreate(), onBind(), onUnbind() und onDestroy(). Diese Methoden werden vom System jedes Mal aufgerufen, wenn der Dienst in eine neue Lebenszyklusphase eintritt.

Lebenszyklus von TileService

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

Der TileService-Lebenszyklus umfasst die folgenden Methoden, die vom System jedes Mal aufgerufen werden, wenn Ihr TileService in eine neue Lebenszyklusphase eintritt:

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

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

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

Wiedergabemodus auswählen

Ihr TileService ist im aktiven oder inaktiven Modus. Wir empfehlen den aktiven Modus, den Sie im App-Manifest deklarieren müssen. Andernfalls ist TileService der Standardmodus und muss nicht deklariert werden.

Angenommen, Ihr TileService wird außerhalb der Methoden onStartListening() und onStopListening() verwendet.

Aktivmodus (empfohlen)

Verwenden Sie den Aktivmodus für eine TileService, die in ihrem eigenen Prozess auf ihren Status achtet und ihn überwacht. Ein TileService im Aktivmodus ist für onTileAdded(), onTileRemoved(), Tippen-Ereignisse und auf Anfrage des App-Prozesses gebunden.

Wir empfehlen den aktiven Modus, wenn Ihre TileService benachrichtigt werden soll, wenn der Kachelnstatus durch einen eigenen Prozess aktualisiert werden soll. Aktive Kacheln begrenzen die Belastung des Systems, da sie nicht jedes Mal gebunden werden müssen, wenn das Steuerfeld für die Schnelleinstellungen für den Nutzer sichtbar wird.

Die statische Methode TileService.requestListeningState() kann aufgerufen werden, um den Start des Hörstatus 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>

Inaktivmodus

Der Inaktive Modus ist der Standardmodus. Ein TileService befindet sich im Inaktivmodus, wenn es immer dann gebunden ist, wenn Ihre Kachel für den Nutzer sichtbar ist. Das bedeutet, dass Ihre TileService möglicherweise außerhalb des Einflussbereichs von Google erstellt und wieder gebunden wird. Sie kann auch gelöst und zerstört werden, wenn sich der Nutzer die Kachel nicht ansieht.

Ihre App erhält einen Rückruf an onStartListening(), nachdem der Nutzer das Steuerfeld für die Schnelleinstellungen geöffnet hat. Sie können Ihr Tile-Objekt zwischen onStartListening() und onStopListening() beliebig oft aktualisieren.

Sie müssen den inaktiven Modus nicht deklarieren. Fügen Sie der Manifestdatei Ihrer App einfach nicht die META_DATA_ACTIVE_TILE hinzu.

Kachelstatus – Übersicht

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

• STATE_ACTIVE: Gibt an, dass die Funktion aktiviert ist. In diesem Status kann der Nutzer mit Ihrer Kachel interagieren.

  Bei einer Kachel für eine Fitness-App, mit der Nutzer ein zeitgesteuertes Training starten können, würde STATE_ACTIVE beispielsweise bedeuten, dass der Nutzer ein Training gestartet hat und der Timer läuft.

• STATE_INACTIVE: Gibt den Status „Aus“ oder „Pausiert“ an. In diesem Status kann der Nutzer mit Ihrer Kachel interagieren.

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

• STATE_UNAVAILABLE: Gibt an, dass der Dienst vorübergehend nicht verfügbar ist. In diesem Status kann der Nutzer 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 anfänglichen Status des Tile-Objekts fest. Sie legen den Status des Tile-Objekts für den Rest des Lebenszyklus fest.

Das System kann das Kachelnsymbol und den Hintergrund einfärben, um den Status Ihres Tile-Objekts widerzuspiegeln. Tile-Objekte, die auf STATE_ACTIVE eingestellt sind, sind am dunkelsten. STATE_INACTIVE und STATE_UNAVAILABLE sind immer heller. Die genaue Farbe ist vom Hersteller und der Version abhängig.

Kachel aktualisieren

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

Im Aktivmodus können Sie Ihre Kachel genau einmal aktualisieren, bevor Sie einen Rückruf an onStopListening() erhalten. Im inaktiven Modus können Sie Ihre Kachel zwischen onStartListening() und onStopListening() beliebig oft aktualisieren.

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

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

Rufen Sie updateTile() auf, um die Kachel zu aktualisieren, sobald Sie die Felder des Tile-Objekts auf die richtigen Werte festgelegt haben. Dadurch werden die aktualisierten Kacheln vom System geparst und die Benutzeroberfläche 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 = 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();
}

Armaturen bedienen

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 Rückruf an onClick() erhält, kann sie ein Dialogfeld oder eine Aktivität starten, Hintergrundarbeiten auslösen oder den Status Ihrer Kachel ändern.

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

Dialogfeld öffnen

showDialog(): Der Bereich „Schnelleinstellungen“ wird minimiert und ein Dialogfeld wird angezeigt. Verwenden Sie einen Dialog, um Ihrer Aktion Kontext hinzuzufügen, wenn zusätzliche Eingaben oder die Einwilligung des Nutzers erforderlich sind.

Aktivität starten

Mit startActivityAndCollapse() wird eine Aktivität gestartet, während das Steuerfeld minimiert wird. Aktivitäten sind nützlich, wenn mehr Details angezeigt werden sollen als in einem Dialogfeld oder wenn Ihre Aktion sehr interaktiv ist.

Wenn Ihre App eine erhebliche Nutzerinteraktion erfordert, sollte die App eine Aktivität nur als letzten Ausweg starten. Verwenden Sie stattdessen einen Dialog oder einen Schalter.

Wenn Sie lange auf eine Kachel tippen, wird der Bildschirm App-Informationen 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 ein <intent-filter> hinzu.

Ab Android API 28 muss die PendingIntent folgende 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 unter AndroidManifest.xml hinzufügen.

Kachel als umschaltbar markieren

Wir empfehlen, Ihre Kachel als umschaltbar zu kennzeichnen, wenn sie hauptsächlich als Ein-/Aus-Schalter dient (was das häufigste Verhalten von Kacheln ist). So können dem Betriebssystem Informationen zum Verhalten der Kachel zur Verfügung gestellt und die allgemeine Barrierefreiheit verbessert werden.

Legen Sie die TOGGLEABLE_TILE-Metadaten auf true fest, um die 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

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

Wenn die Aktion der Kachel bei gesperrtem Display sicher ausgeführt werden kann, verwenden Sie startActivity(), um eine Aktivität über dem Sperrbildschirm zu starten.

Wenn die Aktion der Kachel 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 in diese Methode übergeben.

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 die Schnelleinstellungen zu öffnen.
2. Tippen Sie auf die Schaltfläche „Bearbeiten“.
3. Scrollen Sie auf dem Gerät durch alle Kacheln, bis Sie Ihre Kachel finden.
4. Halten Sie die Kachel gedrückt und ziehen Sie sie in die Liste der aktiven Kacheln.

Der Nutzer kann Ihre Kachel jederzeit verschieben oder entfernen.

Ab Android 13 können Sie die Methode requestAddTileService() verwenden, um es Nutzern viel einfacher zu machen, Ihre Kachel auf einem Gerät hinzuzufügen. Bei dieser Methode werden Nutzer aufgefordert, Ihre Kachel direkt in den Bereich „Schnelleinstellungen“ aufzunehmen. Die Aufforderung enthält den Namen der Anwendung, das bereitgestellte Label und das Symbol.

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

Der Rückruf 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 um eine Antwort bitten. Wir empfehlen, requestAddTileService() nur im Kontext aufzurufen, z. B. wenn der Nutzer zum ersten Mal mit einer Funktion interagiert, die von Ihrer Kachel unterstützt wird.

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