Verknüpfungen verwalten

Nachdem Sie Verknüpfungen erstellt haben, müssen Sie sie möglicherweise während der Lebensdauer Ihrer App verwalten. Sie können Ihre App beispielsweise optimieren, indem Sie ermitteln, wie oft Ihre Nutzer bestimmte Aktionen mit Ihren Verknüpfungen ausführen. In einem anderen Fall können Sie eine angepinnte Verknüpfung deaktivieren, um zu verhindern, dass Ihre App veraltete oder fehlende Aktionen ausführt. Bei Tastenkombinationen, auf die in Unterhaltungen verwiesen wird, können Sie die Nutzung erfassen, um Signale zu erhalten, mit denen sich das Ranking der Tastenkombinationen verbessern lässt.

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

Verhalten von Verknüpfungen

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

Sichtbarkeit von Verknüpfungen

Statische und dynamische Verknüpfungen werden in einem unterstützten Launcher oder Assistenten angezeigt, wenn der Nutzer eine bestimmte Geste oder einen bestimmten Sprachbefehl ausführt. Bei unterstützten Launchern wird die Geste durch Berühren und Halten des Launcher-Symbols der App ausgeführt. Bei anderen Launcher-Apps kann die Geste jedoch anders sein. Mit Google Assistant können Kurzbefehle in Assistant angezeigt oder per Sprachbefehl gestartet werden.

Die Klasse LauncherApps bietet APIs für Launcher-Apps, um auf Verknüpfungen zuzugreifen.

Angepinnte Verknüpfungen werden im Launcher selbst angezeigt und sind daher immer sichtbar. Eine angepinnte Verknüpfung wird nur in den folgenden Fällen aus dem Launcher entfernt:

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

Freigabeziele sind eine Teilmenge dynamischer Verknüpfungen, die in der Zeile für die direkte Freigabe des Android-Sharesheets angezeigt werden.

Anzeigereihenfolge der Kurzbefehle

Wenn der Launcher die Verknüpfungen einer App anzeigt, müssen sie in der folgenden Reihenfolge erscheinen:

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

Innerhalb der einzelnen Verknüpfungstypen (statisch und dynamisch) werden Verknüpfungen nach ShortcutInfo.getRank in aufsteigender Reihenfolge des Rangs sortiert. Google Assistant berücksichtigt auch den Shortcut-Rang, wenn er kontextbezogene Shortcuts ermittelt, die Nutzern angezeigt werden sollen.

Ränge sind nicht negative, sequenzielle Ganzzahlen. Statische Verknüpfungen werden in der Reihenfolge, in der sie in der Datei shortcuts.xml angezeigt werden, von der ersten bis zur letzten Verknüpfung eingestuft. Bei dynamischen Verknüpfungen können Sie die Ränge vorhandener Verknüpfungen 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, darunter der bisherige Nutzerverlauf, die Aktualität, die Häufigkeit, der Ranghinweis, die App-Nutzung und die 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, werden gegenüber den Freigabezielen priorisiert, die von der ChooserTargetService erstellt wurden, die in Android 11 eingestellt wurde. In Android 12 und höher werden Freigabeziele, die vom verworfenen ChooserTargetService generiert wurden, nicht mehr im Freigabeblatt angezeigt.

Die meisten Launcher zeigen maximal vier Verknüpfungen an. Bei jeder Kombination aus definierten statischen und dynamischen Verknüpfungen zeigt der Launcher maximal zwei statische und zwei dynamische Verknüpfungen an. Wenn du beispielsweise vier statische Verknüpfungen definierst und drei dynamische Verknüpfungen programmatisch erstellst, werden im Launcher die ersten beiden statischen Verknüpfungen und die beiden am höchsten eingestuften dynamischen Verknüpfungen angezeigt.

Mehrere Intents und Aktivitäten verwalten

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

Eine Aktivität aus einer anderen starten

Statische Verknüpfungen können keine benutzerdefinierten Intent-Flags haben. Für den ersten Intent einer statischen Verknüpfung sind immer Intent.FLAG_ACTIVITY_NEW_TASK und Intent.FLAG_ACTIVITY_CLEAR_TASK festgelegt. Das bedeutet, dass alle vorhandenen Aktivitäten in der App zerstört werden, wenn eine statische Verknüpfung gestartet wird, während die App ausgeführt wird. Wenn du dieses Verhalten nicht möchtest, kannst du eine Trampolin-Aktivität verwenden – eine unsichtbare Aktivität, die eine andere Aktivität startet –, indem du „finish“ in einem Startblock oder onCreate aufrufst, bevor der Compose-Inhalt festgelegt wird:

1. Fügen Sie in der AndroidManifest.xml file die Attributzuweisung android:taskAffinity="" in die Trampolin-Aktivität ein.

2. Verweise in der Ressourcendatei für Verknüpfungen auf die Trampolin-Aktivität im Intent innerhalb der statischen Verknüpfung.

Weitere Informationen zu Trampolin-Aktivitäten findest du unter Eine Aktivität von einer anderen aus starten.

Intent-Flags festlegen

Sie können dynamische Verknüpfungen mit einer beliebigen Kombination von Intent-Flags veröffentlichen. Am besten geben Sie die Kombination aus Intent.FLAG_ACTIVITY_SINGLE_TOP und Intent.FLAG_ACTIVITY_CLEAR_TOP im Intent des Kurzbefehls an. Dadurch wird sichergestellt, dass die ComponentActivity, wenn sie bereits aktiv ist, in den Vordergrund gebracht und wiederverwendet wird, ohne dass sie zerstört wird. So kann die Architektur mit einer einzelnen Aktivität das Verknüpfungsereignis über onNewIntent() ordnungsgemäß verarbeiten.

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

Verknüpfungen aktualisieren

Das Launcher-Symbol jeder App kann maximal eine Anzahl von statischen und dynamischen Verknüpfungen enthalten, die dem von getMaxShortcutCountPerActivity zurückgegebenen Wert entspricht. Die Anzahl der angepinnten Verknüpfungen, die eine App erstellen kann, ist nicht begrenzt.

Wenn eine dynamische Verknüpfung angepinnt ist, bleibt sie auch dann sichtbar und startbar, wenn der Publisher sie als dynamische Verknüpfung entfernt. Dadurch kann eine App mehr als getMaxShortcutCountPerActivity Verknüpfungen haben.

Sehen wir uns das folgende Beispiel an, bei dem davon ausgegangen wird, dass der von getMaxShortcutCountPerActivity zurückgegebene Wert 4 ist:

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

Die App muss c1, c2 und c3 entfernen, da sie nicht mehr als vier dynamische Verknüpfungen 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 App kann updateShortcuts(Context, List) verwenden, um eine der vorhandenen sieben Verknüpfungen zu aktualisieren. Sie können diese Tastenkombinationen beispielsweise aktualisieren, wenn sich die Symbole der Chatpartner ä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 von nicht dynamischen, angepinnten Verknüpfungen verwenden, da diese beiden Methoden versuchen, die angegebenen Listen von Verknüpfungen in dynamische Verknüpfungen umzuwandeln.

Die Anzahl der Verknüpfungen, die zur Anzeige in Assistent-Apps wie Google Assistant übertragen werden können, ist nicht begrenzt. Verwenden Sie die Methode pushDynamicShortcut der Jetpack-Bibliothek ShortcutManagerCompat, um Verknüpfungen für die Verwendung in Assistent-Apps 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, findest du unter Best Practices für Verknüpfungen.

Änderungen der Systemsprache verarbeiten

Apps müssen dynamische und angepinnte Verknüpfungen aktualisieren, wenn sie die Übertragung Intent.ACTION_LOCALE_CHANGED erhalten, die auf eine Änderung der Systemsprache hinweist.

Nutzung von Tastenkombinationen verfolgen

Um zu ermitteln, in welchen Situationen statische und dynamische Verknüpfungen angezeigt werden, prüft der Launcher den Aktivierungsverlauf von Verknüpfungen. Bei statischen Verknüpfungen kannst du nachverfolgen, wann Nutzer bestimmte Aktionen in deiner App ausführen. Rufe dazu die Methode reportShortcutUsed auf und übergib 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 die Aktion, die der Verknüpfung entspricht, manuell aus.

Ihre App erfasst die Nutzung dynamischer Verknüpfungen, indem sie die Methode pushDynamicShortcut aufruft und die ID der Verknüpfung übergibt, wenn ein relevantes Ereignis auftritt. Wenn du die Nutzung dynamischer Verknüpfungen mit dieser Methode förderst, können Assistent-Apps wie Google Assistant Nutzern relevante Verknüpfungen vorschlagen. Da die Methode pushDynamicShortcut die Nutzung meldet, wenn sie aufgerufen wird, rufen Sie die Methode reportShortcutUsed nicht für dieselben Verknüpfungen auf.

Bei konversationsbezogenen Kurzbefehlen ist es wichtig, die Nutzung für ausgehende und eingehende Nachrichten zu erfassen. Weitere Informationen finden Sie in den Best Practices für Personen und Unterhaltungen.

Verknüpfungen deaktivieren

Da deine App und ihre Nutzer Verknüpfungen im Launcher des Geräts anpinnen können, ist es möglich, dass diese angepinnten Verknüpfungen Nutzer zu Aktionen in deiner App weiterleiten, die veraltet sind oder nicht mehr existieren. In diesem Fall kannst du die Verknüpfungen, die Nutzer nicht auswählen sollen, deaktivieren. Rufe dazu disableShortcuts auf. Dadurch werden die angegebenen Verknüpfungen aus der Liste der statischen und dynamischen Verknüpfungen entfernt und angepinnte Kopien dieser Verknüpfungen deaktiviert. Sie können auch eine überladene Version dieser Methode verwenden, die einen CharSequence als benutzerdefinierte Fehlermeldung akzeptiert. Diese Fehlermeldung wird dann angezeigt, wenn Nutzer versuchen, eine deaktivierte Verknüpfung zu starten.

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 einer App ohne Aktivitäten oder Dienste im Vordergrund. Die Begrenzung der Häufigkeit, mit der Sie diese Methoden aufrufen können, wird als Ratenbegrenzung bezeichnet. Diese Funktion verhindert, dass ShortcutManagerCompat zu viele Geräteressourcen verbraucht.

Wenn die Ratenbegrenzung aktiv ist, gibt isRateLimitingActive „true“ zurück. Die Ratenbegrenzung wird jedoch bei bestimmten Ereignissen zurückgesetzt, sodass auch 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.
• Die Sprache des Systems ändert sich.
• Der Nutzer führt die Aktion Inline-Antwort für eine Benachrichtigung aus.

Wenn während der Entwicklung oder des Tests eine Ratenbegrenzung auftritt, können Sie in den Geräteeinstellungen die Option Entwickleroptionen > ShortcutManager-Ratenbegrenzung zurücksetzen auswählen oder den folgenden Befehl in adb eingeben:

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

Sichern und wiederherstellen

Du kannst Nutzern erlauben, beim Gerätewechsel Sicherungs- und Wiederherstellungsvorgänge für deine App auszuführen, indem du das Attribut android:allowBackup="true" in der Manifestdatei deiner App zuweist. Wenn du die Sicherung und Wiederherstellung unterstützt, beachte die folgenden Punkte zu App-Verknüpfungen:

• Statische Verknüpfungen werden automatisch neu veröffentlicht, aber erst, nachdem der Nutzer deine App auf einem neuen Gerät neu installiert hat.
• Dynamische Verknüpfungen werden nicht gesichert. Sie sollten daher Logik in Ihre App einbinden, damit sie neu veröffentlicht werden, wenn ein Nutzer Ihre App auf einem neuen Gerät öffnet.
• Angepinnte Verknüpfungen werden automatisch im Launcher des Geräts wiederhergestellt. Die mit angepinnten Verknüpfungen verknüpften Symbole werden jedoch nicht vom System gesichert. Speichere daher die Bilder deiner angepinnten Verknüpfungen in deiner App, damit sie auf einem neuen Gerät schnell wiederhergestellt werden können.

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

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getShortcuts(this, ShortcutManagerCompat.FLAG_MATCH_PINNED).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}
ShortcutsSnippets.kt