Kurzbefehle verwalten

Nachdem Sie Verknüpfungen erstellt haben, müssen Sie diese möglicherweise über die gesamte Lebensdauer Ihrer Anwendung hinweg verwalten. Beispielsweise können Sie Ihre Anwendung optimieren, indem Sie festlegen, wie oft Nutzer bestimmte Aktionen mit den Verknüpfungen ausführen. In einem anderen Fall könnten Sie eine angepinnte Verknüpfung deaktivieren, um zu verhindern, dass Ihre Anwendung veraltete oder fehlende Aktionen ausführt. Bei Tastenkombinationen, auf die in Unterhaltungen verwiesen wird, kann es sinnvoll sein, die Nutzung zu verfolgen, um Signale zur Verbesserung der Rangfolge von Verknüpfungen zu erhalten.

Auf dieser Seite werden diese und einige weitere gängige Methoden zum Verwalten von Tastenkombinationen beschrieben.

Verhalten von Kurzbefehlen

Die folgenden Abschnitte enthalten allgemeine Informationen zum Verhalten von Verknüpfungen, einschließlich Sichtbarkeit, Anzeigereihenfolge und Ränge.

Sichtbarkeit von Kurzbefehlen

Statische und dynamische Tastenkombinationen werden in einem unterstützten Launcher oder Assistenten angezeigt, wenn der Nutzer eine bestimmte Touch-Geste oder einen bestimmten Sprachbefehl ausführt. Auf unterstützten Launchern erfolgt die Bewegung durch Berühren und Halten des Launcher-Symbols. In anderen Launcher-Apps kann sie jedoch anders aussehen. Mit Google Assistant können Tastenkombinationen in Assistant angezeigt oder über einen Nutzerbefehl gestartet werden.

Die Klasse LauncherApps stellt APIs bereit, mit denen Launcher-Apps auf Tastenkombinationen zugreifen können.

Da angepinnte Verknüpfungen im Launcher selbst angezeigt werden, sind sie immer sichtbar. Eine angepinnte Verknüpfung wird nur in den folgenden Situationen aus der Übersicht entfernt:

  • Der Nutzer entfernt sie.
  • Die mit der Verknüpfung verknüpfte App wird deinstalliert.
  • Der Nutzer löscht die Daten einer App, indem er zu Einstellungen > Apps & Benachrichtigungen wechselt, die App auswählt und auf Speicher > Speicherinhalt löschen tippt.

Ziele sind eine Teilmenge der dynamischen Verknüpfungen, die in der Zeile für die direkte Freigabe im Android-Share-Sheet angezeigt werden.

Screenshot des Android-Sharesheet
Abbildung 1: Das Android-Sharesheet Die Ziele für den direkten Anteil werden in der ersten Zeile angezeigt, gefolgt von den Apps mit dem entsprechenden Rang und den App-Listen.

Anzeigereihenfolge von Verknüpfungen

Die Verknüpfungen einer App müssen im Launcher in der folgenden Reihenfolge angezeigt werden:

  1. Statische Verknüpfungen: Verknüpfungen, deren Methode isDeclaredInManifest() true zurückgibt.
  2. Dynamische Verknüpfungen: Verknüpfungen, deren Methode ShortcutInfo.isDynamic() true zurückgibt.

Innerhalb jedes Verknüpfungstyps – statisch oder dynamisch – werden Verknüpfungen in der Reihenfolge ihres ansteigenden Rangs nach ShortcutInfo.getRank sortiert. Google Assistant berücksichtigt auch den Shortcut-Rang, wenn er kontextbezogene Tastenkombinationen bestimmt, die Nutzern angezeigt werden.

Ränge sind nicht negative, sequenzielle Ganzzahlen. Statische Tastenkombinationen werden in der Reihenfolge ihres Erscheinens in der Datei shortcuts.xml absteigend sortiert. Bei dynamischen Tastenkombinationen können Sie die Rangfolge vorhandener Tastenkombinationen aktualisieren, wenn Sie updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat) oder setDynamicShortcuts(Context, List) aufrufen.

Die Reihenfolge der Freigabeziele basiert auf verschiedenen Faktoren wie dem bisherigen Nutzerverlauf, der Aktualität, der Häufigkeit, Ranghinweisen, der App-Nutzung und der Priorität, die für die Unterhaltung festgelegt wurde, die mit einer Freigabeverknüpfung verknüpft ist. Freigabeziele, die mit der Sharing Shortcuts API erstellt wurden, haben Vorrang vor den Freigabezielen, die von der in Android 11 eingestellten ChooserTargetService erstellt wurden. Ab Android 12 werden Freigabeziele, die vom eingestellten ChooserTargetService generiert wurden, nicht mehr im Tabellenblatt angezeigt.

In den meisten Launchern werden maximal vier Tastenkombinationen angezeigt. Für eine beliebige Kombination aus statischen und dynamischen Tastenkombinationen, die definiert sind, werden im Launcher maximal zwei statische und zwei dynamische Tastenkombinationen angezeigt. Wenn Sie beispielsweise vier statische Tastenkombinationen definieren und programmatisch drei dynamische Tastenkombinationen erstellen, werden im Launcher die ersten beiden statischen Tastenkombinationen und die beiden am höchsten bewerteten dynamischen Tastenkombinationen angezeigt.

Mehrere Intents und Aktivitäten verwalten

Wenn Ihre Anwendung mehrere Vorgänge ausführen soll, wenn ein Nutzer eine Verknüpfung aktiviert, können Sie sie so konfigurieren, dass aufeinanderfolgende Aktivitäten ausgelöst werden. Dazu können Sie je nach Typ der Verknüpfung mehrere Intents zuweisen, eine Aktivität in einer anderen starten oder Intent-Flags festlegen.

Mehrere Intents zuweisen

Wenn Sie eine Verknüpfung mit ShortcutInfoCompat.Builder erstellen, können Sie setIntents() anstelle von setIntent() verwenden. Wenn Sie setIntents() aufrufen, können Sie mehrere Aktivitäten in Ihrer App starten, wenn der Nutzer eine Verknüpfung auswählt. Alle Aktivitäten bis auf die letzte werden in der Liste auf dem Back-Stack platziert. Wenn der Nutzer dann auf die Schaltfläche „Zurück“ des Geräts tippt, sieht er eine andere Aktivität in deiner App, anstatt zum Launcher des Geräts zurückzukehren.

Eine Aktivität aus einer anderen starten

Statische Verknüpfungen dürfen keine benutzerdefinierten Intent-Flags haben. Der erste Intent einer statischen Verknüpfung hat immer Intent.FLAG_ACTIVITY_NEW_TASK und Intent.FLAG_ACTIVITY_CLEAR_TASK set. Das bedeutet, dass beim Ausführen Ihrer Anwendung alle vorhandenen Aktivitäten in der Anwendung gelöscht werden, wenn eine statische Verknüpfung gestartet wird. Wenn Sie das nicht möchten, können Sie eine Trampolin-Aktivität – eine unsichtbare Aktivität, die eine andere Aktivität startet – für Activity.onCreate(Bundle) die Activity.finish()

  1. Fügen Sie in der Datei AndroidManifest.xml die Attributzuweisung „android:taskAffinity=“ für die Trampolinaktivität hinzu.
  2. Verweisen Sie in der Shortcuts-Ressourcendatei auf die Trampolinaktivität im Intent innerhalb der statischen Verknüpfung.

Weitere Informationen zu Trampolinaktivitäten findest du unter Aktivität von einer anderen starten.

Intent-Flags festlegen

Dynamische Tastenkombinationen lassen sich mit beliebigen Intent-Flags veröffentlichen. Geben Sie vorzugsweise Intent.FLAG_ACTIVITY_CLEAR_TASK zusammen mit Ihren anderen Flags an. Andernfalls wird die Zielaktivität möglicherweise nicht angezeigt, wenn Sie versuchen, eine andere Aufgabe zu starten, während Ihre Anwendung ausgeführt wird.

Weitere Informationen zu Aufgaben und Intent-Flags finden Sie unter Aufgaben und den Back-Stack.

Tastenkombinationen aktualisieren

Das Launcher-Symbol jeder App kann höchstens eine Reihe statischer und dynamischer Verknüpfungen enthalten, die dem von getMaxShortcutCountPerActivity zurückgegebenen Wert entsprechen. Die Anzahl der angepinnten Verknüpfungen, die eine App erstellen kann, ist nicht begrenzt.

Wenn eine dynamische Verknüpfung angepinnt ist, bleibt die angepinnte Verknüpfung sichtbar und ausführbar, auch wenn der Publisher sie als dynamische Verknüpfung entfernt. Eine App kann dann mehr als getMaxShortcutCountPerActivity() Verknüpfungen haben.

Im folgenden Beispiel wird davon ausgegangen, dass der von getMaxShortcutCountPerActivity() zurückgegebene Wert 4 ist:

  1. Eine Chat-App veröffentlicht vier dynamische Tastenkombinationen, die die vier letzten Unterhaltungen darstellen: c1, c2, c3 und c4.
  2. Der Nutzer pinnen alle vier Tastenkombinationen an.
  3. Später startet der Nutzer drei weitere Unterhaltungen: c5, c6 und c7. Die dynamischen Verknüpfungen werden von der Publisher-App neu veröffentlicht. Die neue Liste der dynamischen Tastenkombinationen lautet: c4, c5, c6 und c7.

Die Anwendung muss c1, c2 und c3 entfernen, da sie nicht mehr als vier dynamische Tastenkombinationen anzeigen kann. c1, c2 und c3 sind jedoch weiterhin angepinnte Verknüpfungen, auf die der Nutzer zugreifen und die er starten kann.

Der Nutzer kann dann auf insgesamt sieben Verknüpfungen zugreifen, die mit Aktivitäten in der Publisher-App verknüpft sind. Das liegt daran, dass die Gesamtzahl die maximale Anzahl von Verknüpfungen und die drei angepinnten Verknüpfungen umfasst.

  1. Die Anwendung kann mit updateShortcuts(Context, List) beliebige der vorhandenen sieben Verknüpfungen aktualisieren. So können Sie z. B. diese Verknüpfungen aktualisieren, wenn sich die Symbole der anderen Teilnehmer ändern.
  2. Mit den Methoden addDynamicShortcuts(Context, List) und setDynamicShortcuts(Context, List) können Sie vorhandene Verknüpfungen mit denselben IDs aktualisieren. Sie können sie jedoch nicht zum Aktualisieren nicht dynamischer, angepinnter Tastenkombinationen verwenden, da mit diesen beiden Methoden versucht wird, die angegebenen Liste von Tastenkombinationen in dynamische Tastenkombinationen zu konvertieren.

Die Anzahl der Tastenkombinationen, die zur Anzeige in Assistant-Apps wie Google Assistant gesendet werden können, ist nicht begrenzt. Verwenden Sie die Methode pushDynamicShortcut() der ShortcutManagerCompat Jetpack-Bibliothek, um Verknüpfungen für Assistentenanwendungen zu erstellen und zu aktualisieren. Füge deiner App außerdem die Bibliothek „Google Shortcuts Integration“ hinzu, damit dynamische Links in Google Assistant angezeigt werden können.

Weitere Informationen zu den Richtlinien für App-Verknüpfungen, einschließlich der Aktualisierung von Verknüpfungen, finden Sie unter Best Practices für Tastenkombinationen.

Änderungen der Systemsprache verarbeiten

Apps müssen dynamische und angepinnte Verknüpfungen aktualisieren, wenn sie den Intent.ACTION_LOCALE_CHANGED-Broadcast empfangen, der eine Änderung der Systemsprache angibt.

Nutzung der Kurzbefehle im Blick behalten

Der Launcher untersucht den Aktivierungsverlauf von Tastenkombinationen, um die Situationen zu bestimmen, in denen statische und dynamische Tastenkombinationen angezeigt werden. Bei statischen Verknüpfungen können Sie verfolgen, wann Nutzer bestimmte Aktionen in Ihrer App ausführen. Dazu rufen Sie die Methode reportShortcutUsed() auf und übergeben ihr die ID einer Verknüpfung, wenn eines der folgenden Ereignisse eintritt:

  • Der Nutzer wählt die Verknüpfung mit der angegebenen ID aus.
  • In der App führt der Nutzer manuell die Aktion aus, die derselben Tastenkombination entspricht.

In deiner App wird die Nutzung dynamischer Verknüpfungen erfasst. Dazu wird die Methode pushDynamicShortcut() aufgerufen und die ID der Verknüpfung wird übergeben, wenn ein relevantes Ereignis eintritt. Wenn Sie mit dieser Methode die Nutzung dynamischer Verknüpfungen verbessern, können Assistant-Apps wie Google Assistant Nutzern relevante Verknüpfungen vorschlagen. Da die Methode pushDynamicShortcut() beim Aufrufen die Nutzung meldet, rufen Sie für dieselben Verknüpfungen nicht die Methode reportShortcutUsed() auf.

Bei Tastenkombinationen in Zusammenhang mit Unterhaltungen ist es wichtig, die Nutzung für ausgehende und eingehende Nachrichten im Blick zu behalten. Weitere Informationen finden Sie in den Best Practices für Personen und Unterhaltungen.

Tastenkombinationen deaktivieren

Da deine App und ihre Nutzer Verknüpfungen an den Launcher des Geräts anpinnen können, können diese angepinnten Verknüpfungen Nutzer zu Aktionen in deiner App weiterleiten, die veraltet oder nicht mehr existieren. Sie können die Tastenkombinationen, die Nutzer nicht auswählen sollen, deaktivieren, indem Sie disableShortcuts aufrufen. Dadurch werden die angegebenen Verknüpfungen aus der Liste der statischen und dynamischen Tastenkombinationen entfernt und angepinnte Kopien dieser Tastenkombinationen werden deaktiviert. Sie können auch eine überlastete Version dieser Methode verwenden, die ein CharSequence als benutzerdefinierte Fehlermeldung akzeptiert. Diese Fehlermeldung wird angezeigt, wenn Nutzer versuchen, eine deaktivierte Verknüpfung zu öffnen.

Ratenbegrenzung

Wenn Sie die Methoden setDynamicShortcuts(), addDynamicShortcuts() oder updateShortcuts() verwenden, können Sie diese Methoden möglicherweise nur eine bestimmte Anzahl von Malen in einer Hintergrund-App aufrufen, also in einer App ohne Aktivitäten oder Dienste im Vordergrund. Die maximale Häufigkeit, mit der diese Methoden aufgerufen werden können, wird als Ratenbegrenzung bezeichnet. Dieses Feature verhindert, dass ShortcutManagerCompat Geräteressourcen übermäßig nutzt.

Wenn die Ratenbegrenzung aktiv ist, gibt isRateLimitingActive() „true“ zurück. Die Ratenbegrenzung wird jedoch bei bestimmten Ereignissen zurückgesetzt, sodass selbst Hintergrund-Apps ShortcutManager-Methoden aufrufen können, bis die Ratenbegrenzung wieder erreicht ist. Zu diesen Ereignissen gehören:

  • Eine App wird in den Vordergrund gebracht.
  • Das Systemsprache ändert sich.
  • Der Nutzer führt die Inline-Antwort-Aktion für eine Benachrichtigung aus.

Wenn während der Entwicklung oder beim Testen eine Ratenbegrenzung auftritt, kannst du Entwickleroptionen > ShortcutManager-Ratenbegrenzung zurücksetzen in den Geräteeinstellungen auswählen oder den folgenden Befehl in adb eingeben:

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

Back-up und Wiederherstellung

Du kannst Nutzern erlauben, Sicherungs- und Wiederherstellungsvorgänge in deiner App durchzuführen, wenn sie das Gerät wechseln. Nimm dazu die Attributzuweisung android:allowBackup="true in die Manifestdatei deiner App auf. Wenn Sie Back-up und Wiederherstellung unterstützen, beachten Sie die folgenden Punkte zu App-Verknüpfungen:

  • Statische Verknüpfungen werden automatisch noch einmal veröffentlicht, aber erst, nachdem der Nutzer deine App auf einem neuen Gerät neu installiert hat.
  • Dynamische Verknüpfungen werden nicht gesichert. Füge daher eine Logik in deine App ein, um sie wieder zu veröffentlichen, wenn ein Nutzer deine App auf einem neuen Gerät öffnet.
  • Angepinnte Verknüpfungen werden automatisch im Launcher des Geräts wiederhergestellt, das System sichert jedoch keine Symbole, die mit angepinnten Verknüpfungen verbunden sind. Speichern Sie daher die Bilder der angepinnten Verknüpfungen in Ihrer App, damit Sie sie einfach auf einem neuen Gerät wiederherstellen können.

Das folgende Code-Snippet zeigt, wie Sie die dynamischen Verknüpfungen Ihrer Anwendung am besten wiederherstellen und prüfen, ob die angepinnten Verknüpfungen Ihrer Anwendung beibehalten wurden:

Kotlin

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}

Java

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}