Benutzerdefinierte Schnelleinstellungen-Kacheln für Ihre App erstellen

Schnelleinstellungen sind Kacheln, die im Bereich für Schnelleinstellungen angezeigt werden und Aktionen darstellen, auf die Nutzer tippen können, um wiederkehrende Aufgaben schnell auszuführen. Deine App kann Nutzern über die Klasse TileService eine benutzerdefinierte Kachel zur Verfügung stellen und ein Tile-Objekt verwenden, um den Status der Kachel zu verfolgen. Sie können beispielsweise eine Kachel erstellen, über die Nutzer ein von Ihrer App bereitgestelltes VPN aktivieren oder deaktivieren können.

Entscheiden, wann eine Kachel erstellt werden soll

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

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

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

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

• Verwenden Sie Kacheln nicht 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, musst du zuerst ein entsprechendes Kachelsymbol erstellen und dann dein TileService in der Manifestdatei deiner App erstellen und deklarieren.

Das Beispiel für die Schnelleinstellungen enthält ein Beispiel für das Erstellen und Verwalten einer Kachel.

Benutzerdefiniertes Symbol erstellen

Sie müssen ein benutzerdefiniertes Symbol angeben, das auf der Kachel im Bereich „Schnelleinstellungen“ angezeigt wird. Dieses Symbol wird bei der Deklaration des TileService hinzugefügt, wie im nächsten Abschnitt beschrieben. Das Symbol muss durchgehend weiß mit transparentem Hintergrund und 24 x 24 dp groß sein und in Form eines VectorDrawable-Elements vorliegen.

Erstellen Sie ein Symbol, das optisch auf den Zweck Ihrer Kachel verweist. So können Nutzende auf einfache Weise feststellen, ob Ihre Kachel ihren Anforderungen entspricht. Sie können beispielsweise das Symbol einer Stoppuhr für eine Kachel für eine Fitness-App erstellen, mit der Nutzer eine Trainingseinheit starten können.

TileService erstellen und deklarieren

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

Deklariere TileService in der Manifestdatei deiner App. Fügen Sie den Namen und das Label Ihres 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 du dein TileService in deinem App-Manifest erstellt und deklariert hast, musst du dessen Status verwalten.

TileService ist ein gebundener Dienst. Die TileService wird gebunden, wenn sie von der Anwendung angefordert wird oder wenn das System mit ihr kommunizieren muss. Ein typischer Lebenszyklus eines gebundenen Dienstes umfasst die folgenden vier Callback-Methoden: onCreate(), onBind(), onUnbind() und onDestroy(). Diese Methoden werden vom System jedes Mal aufgerufen, wenn der Dienst eine neue Lebenszyklusphase erreicht.

TileService-Lebenszyklus – Übersicht

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

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

• onTileAdded(): Diese Methode wird nur aufgerufen, wenn der Nutzer deine Kachel zum ersten Mal hinzufügt oder wenn er sie entfernt und noch einmal hinzufügt. Dies ist der beste Zeitpunkt für eine einmalige Initialisierung. Dies erfüllt jedoch möglicherweise nicht alle erforderlichen Initialisierungen.

• onStartListening() und onStopListening(): Diese Methoden werden oft aufgerufen, wenn deine App die Kachel aktualisiert. 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 die Kachel entfernt.

Zuhörmodus auswählen

TileService hört im Aktivmodus oder im Nicht-Aktiv-Modus zu. Wir empfehlen, den Aktivmodus zu verwenden. Diesen musst du im App-Manifest deklarieren. Andernfalls ist TileService der Standardmodus und muss nicht deklariert werden.

Gehen Sie nicht davon aus, dass sich Ihr TileService außerhalb der Methodenpaare onStartListening() und onStopListening() befindet.

Aktivmodus (empfohlen)

Verwenden Sie den Aktivmodus für eine TileService, die ihren Status in einem eigenen Prozess überwacht und überwacht. Eine TileService im Aktivmodus wird an onTileAdded(), onTileRemoved(), Tippereignisse und auf Anforderung durch den App-Prozess gebunden.

Wir empfehlen den Aktivmodus, wenn TileService benachrichtigt wird, wenn der Kachelstatus von einem eigenen Prozess aktualisiert werden sollte. Aktive Kacheln begrenzen die Belastung des Systems, da sie nicht jedes Mal gebunden werden müssen, wenn der Bereich „Schnelleinstellungen“ für den Nutzer sichtbar wird.

Die statische Methode TileService.requestListeningState() kann aufgerufen werden, um den Start des Überwachungsstatus anzufordern und einen Callback von onStartListening() zu erhalten.

Wenn du den Aktivmodus deklarieren möchtest, füge der Manifestdatei deiner App META_DATA_ACTIVE_TILE hinzu.

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

Nicht-Aktiv-Modus

Der nicht aktive Modus ist der Standardmodus. Eine TileService befindet sich im inaktiven Modus, wenn sie immer gebunden ist, wenn deine Kachel für den Nutzer sichtbar ist. Dies bedeutet, dass Ihre TileService zu Zeiten außerhalb ihrer Kontrolle erstellt und neu gebunden werden kann. Sie kann auch aufgelöst und gelöscht werden, wenn der Nutzer die Kachel nicht ansieht.

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

Der inaktive Modus muss nicht deklariert werden. Füge der Manifestdatei deiner App nur META_DATA_ACTIVE_TILE nicht hinzu.

Übersicht über Kachelzustände

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

• STATE_ACTIVE: Gibt an, dass es sich um einen An- oder Aktivierungsstatus handelt. Der Nutzer kann in diesem Zustand mit Ihrer Kachel interagieren.

  Bei einer Fitness-App-Kachel, mit der Nutzer eine zeitgebundene Trainingseinheit starten können, bedeutet STATE_ACTIVE, dass der Nutzer eine Trainingseinheit gestartet hat und der Timer läuft.

• STATE_INACTIVE: steht für „Aus“ oder „Pausiert“. Der Nutzer kann in diesem Zustand mit Ihrer Kachel interagieren.

  Wenn du das Beispiel für die Kachel der Fitness-App noch einmal verwenden möchtest, würde eine Kachel in STATE_INACTIVE bedeuten, dass der Nutzer keine Trainingseinheit gestartet hat, dies aber bei Bedarf tun könnte.

• STATE_UNAVAILABLE: zeigt an, dass der Status vorübergehend nicht verfügbar ist. Der Nutzer kann in diesem Zustand nicht mit Ihrer Kachel interagieren.

  Beispielsweise bedeutet eine Kachel in STATE_UNAVAILABLE, dass sie dem Nutzer derzeit aus irgendeinem Grund nicht zur Verfügung steht.

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

Das Kachelsymbol und der Hintergrund werden möglicherweise vom System färben, damit sie den Status des Tile-Objekts widerspiegeln. Tile-Objekte, die auf STATE_ACTIVE gesetzt sind, sind am dunkelsten, wobei STATE_INACTIVE und STATE_UNAVAILABLE zunehmend heller sind. Der genaue Farbton richtet sich nach dem Hersteller und der Version.

Kachel aktualisieren

Du kannst deine Kachel aktualisieren, sobald du einen Rückruf von onStartListening() erhältst. Je nach Kachelmodus kann die Kachel mindestens einmal aktualisiert werden, bis ein Callback von onStopListening() eingeht.

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

Sie können das Tile-Objekt durch Aufrufen von getQsTile() abrufen. Mit den folgenden Methoden können Sie bestimmte Felder des Tile-Objekts aktualisieren:

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

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

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

Fingertipps

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

Sobald deine App einen Callback von onClick() empfängt, kann sie ein Dialogfeld oder eine Aktivität starten, Hintergrundarbeiten auslösen oder den Status der 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() minimiert den Bereich mit den Schnelleinstellungen und zeigt ein Dialogfeld an. Fügen Sie Ihrer Aktion über ein Dialogfeld Kontext hinzu, wenn eine zusätzliche Eingabe oder die Einwilligung des Nutzers erforderlich ist.

Aktivität starten

startActivityAndCollapse() startet beim Minimieren des Bereichs eine Aktivität. Aktivitäten sind nützlich, wenn Sie detailliertere Informationen als in einem Dialogfeld anzeigen möchten oder wenn Ihre Aktion sehr interaktiv ist.

Wenn Ihre Anwendung eine erhebliche Nutzerinteraktion erfordert, sollte sie nur als letzte Option eine Aktivität starten. Verwenden Sie stattdessen ein Dialogfeld oder eine Ein/Aus-Schaltfläche.

Durch langes Tippen auf eine Kachel wird der Bildschirm App-Info 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 eine <intent-filter> hinzu.

Ab Android API 28 muss 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 im AndroidManifest.xml im jeweiligen Activity-Abschnitt hinzufügen.

Kachel als ein-/ausschaltbar markieren

Wir empfehlen, Ihre Kachel als ein-/ausschaltbar zu kennzeichnen, wenn sie primär als Zwei-Status-Schalter dient (dies ist das gängigste Verhalten von Kacheln). Dadurch erhält das Betriebssystem Informationen zum Verhalten der Kachel und verbessert die allgemeine Zugänglichkeit.

Setze die TOGGLEABLE_TILE-Metadaten auf true, um deine Kachel als ein-/ausschaltbar 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

Ihre Kachel wird auf gesperrten Geräten möglicherweise oben auf dem Sperrbildschirm angezeigt. 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. TileService sollte dann ihr Verhalten entsprechend ändern.

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

Wenn die Kachelaktion nicht sicher ist, verwende unlockAndRun(), um den Nutzer zum Entsperren seines Geräts aufzufordern. Bei Erfolg führt das System das Objekt Runnable aus, das Sie an diese Methode übergeben.

Nutzer auffordern, Ihre Kachel hinzuzufügen

Um Ihre Kachel manuell hinzuzufügen, müssen Nutzende mehrere Schritte ausführen:

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

Der Nutzer kann Ihre Kachel auch jederzeit verschieben oder entfernen.

Ab Android 13 können Sie die Methode requestAddTileService() verwenden, um Nutzern das Hinzufügen Ihrer Kachel zu einem Gerät zu erleichtern. Bei dieser Methode werden Nutzer aufgefordert, Ihre Kachel schnell direkt zu ihrem Schnelleinstellungen-Bereich hinzuzufügen. Der Prompt enthält den Namen der Anwendung, das angegebene Label und das Symbol.

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 oder nicht hinzugefügt wurde, ob sie bereits vorhanden war oder ob ein Fehler aufgetreten ist.

Entscheiden Sie selbst, 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 deine Kachel unterstützt.

Das System kann die Verarbeitung von Anfragen für ein bestimmtes ComponentName beenden, wenn es zuvor vom Nutzer häufig genug abgelehnt wurde. Der Nutzer wird aus dem Context bestimmt, mit dem dieser Dienst abgerufen wurde. Er muss mit dem aktuellen Nutzer übereinstimmen.