Verknüpfungen verwalten

Nachdem Sie Verknüpfungen erstellt haben, müssen Sie sie möglicherweise während des gesamten Lebenszyklus 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 entscheiden Sie sich möglicherweise, eine angepinnte Verknüpfung zu deaktivieren, um zu verhindern, dass Ihre App veraltete oder fehlende Aktionen ausführt. Bei Verknüpfungen, auf die in Unterhaltungen verwiesen wird, sollten Sie die Nutzung erfassen, um Signale zu liefern, die das Ranking von Verknüpfungen verbessern.

Auf dieser Seite werden diese und einige andere gängige Möglichkeiten zum Verwalten Ihrer Tastenkombinationen beschrieben.

Verhalten von Verknüpfungen

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

Sichtbarkeit von Tastenkombinationen

Wichtig :Alle Informationen zu Verknüpfungen werden in einem mit Anmeldedaten verschlüsselten Speicher gespeichert. Ihre App kann erst auf die Verknüpfungen eines Nutzers zugreifen, nachdem dieser das Gerät entsperrt hat.

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 App-Launchersymbols ausgelöst. Bei anderen Launcher-Apps kann die Geste jedoch anders sein. Mit Google Assistant können Verknüpfungen in Assistant angezeigt oder über einen Sprachbefehl des Nutzers gestartet werden.

Die Klasse LauncherApps bietet APIs für Launcher-Apps für den Zugriff auf Verknüpfungen.

Da angepinnte Verknüpfungen im Launcher selbst angezeigt werden, sind sie immer sichtbar. Eine angepinnte Verknüpfung wird nur in den folgenden Situationen 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 > Speicher leeren tippt.

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

Abbildung 1. Das Android-Sharesheet „Direct Share“-Ziele werden in der ersten Zeile angezeigt, gefolgt von Apps mit Rang und dann den App-Listen.

Anzeigereihenfolge von Verknüpfungen

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 Methode ShortcutInfo.isDynamic() true zurückgibt.

Innerhalb der einzelnen Arten von Verknüpfungen (statisch und dynamisch) werden Verknüpfungen nach Rang gemäß ShortcutInfo.getRank sortiert. Google Assistant berücksichtigt auch den Rang von Verknüpfungen, wenn kontextbezogene Verknüpfungen für Nutzer angezeigt werden.

Ränge sind nicht negative, fortlaufende Ganzzahlen. Statische Verknüpfungen werden in der Reihenfolge, in der sie in der Datei shortcuts.xml aufgeführt sind, vom ersten bis zum letzten Element 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 dem bisherigen Nutzerverlauf, der Aktualität, der Häufigkeit, dem Rank-Hinweis, der App-Nutzung und der Priorität, die für die Unterhaltung festgelegt wurde, die mit einer Verknüpfung zum Teilen verknüpft ist. Freigabeziele, die mit der Sharing Shortcuts API erstellt wurden, haben Vorrang vor den Freigabezielen, die von ChooserTargetService generiert wurden. Diese API wurde in Android 11 eingestellt. In Android 12 und höher werden von der eingestellten ChooserTargetService generierte Freigabeziele nicht mehr im Freigabeblatt angezeigt.

Die meisten Launcher zeigen maximal vier Verknüpfungen an. Für jede Kombination aus statischen und dynamischen Verknüpfungen, die definiert sind, zeigt der Launcher maximal zwei statische und zwei dynamische Verknüpfungen an. Wenn Sie beispielsweise vier statische Verknüpfungen definieren und programmatisch drei dynamische Verknüpfungen erstellen, werden im Launcher die ersten beiden statischen Verknüpfungen und die beiden dynamischen Verknüpfungen mit dem höchsten Rang angezeigt.

Hinweis :Die Ränge werden automatisch angepasst, sodass sie für jede Art von Shortcut (statisch oder dynamisch) eindeutig sind. Wenn es beispielsweise drei dynamische Verknüpfungen mit den Rängen 0, 1 und 2 gibt und Sie eine weitere dynamische Verknüpfung mit dem Rang 1 hinzufügen, wird diese Verknüpfung an der zweiten Position platziert. Daraufhin ändern sich die Ränge der Verknüpfungen, die zuvor auf Platz 1 und 2 waren, in 2 bzw. 3.

Mehrere Intents und Aktivitäten verwalten

Wenn Ihre App mehrere Vorgänge ausführen soll, wenn ein Nutzer einen Shortcut aktiviert, können Sie sie so konfigurieren, dass sie aufeinanderfolgende Aktivitäten auslöst. Je nach Art der Verknüpfung können Sie dies erreichen, indem Sie mehrere Intents zuweisen, eine Aktivität von einer anderen aus starten oder Intent-Flags festlegen.

Eine Aktivität über eine andere starten

Statische Verknüpfungen dürfen keine benutzerdefinierten Intent-Flags haben. Für die erste Intention 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 beendet werden, wenn ein statischer Shortcut gestartet wird. Wenn Sie dieses Verhalten nicht möchten, können Sie eine Trampolin-Aktivität verwenden. Das ist eine unsichtbare Aktivität, die eine andere Aktivität startet. Rufen Sie dazu „finish“ in einem Launch-Block oder onCreate auf, bevor Compose-Inhalte festgelegt werden:

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

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

Weitere Informationen zu Trampolin-Aktivitäten finden Sie unter Eine Aktivität über eine andere starten.

Intent-Flags festlegen

Sie können dynamische Verknüpfungen mit beliebigen Intent-Flags veröffentlichen. Geben Sie die Kombination aus Intent.FLAG_ACTIVITY_SINGLE_TOP und Intent.FLAG_ACTIVITY_CLEAR_TOP vorzugsweise im Intent der Verknüpfung an. So wird sichergestellt, dass Ihre ComponentActivity in den Vordergrund gerückt und wiederverwendet wird, ohne zerstört zu werden, wenn sie bereits aktiv ist. Dadurch kann Ihre Single-Activity-Architektur das Shortcut-Ereignis über onNewIntent() verarbeiten.

Weitere Informationen zu Aufgaben und Intent-Flags finden Sie unter Aufgaben und Backstack.

Verknüpfungen aktualisieren

Das Launcher-Symbol jeder App kann höchstens 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 sichtbar und kann gestartet werden, auch wenn der Publisher sie als dynamische Verknüpfung entfernt. So kann eine App 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 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 noch einmal. Die neue Liste dynamischer Verknüpfungen lautet: c4, c5, c6 und c7.

Die App muss c1, c2 und c3 entfernen, da nicht mehr als vier dynamische Verknüpfungen angezeigt werden können. 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 zu Aktivitäten in der Publisher-App führen. Das liegt daran, dass die Gesamtzahl die maximale Anzahl an Verknüpfungen und die drei angepinnten Verknüpfungen umfasst.

1. Die App kann updateShortcuts(Context, List) verwenden, um alle sieben vorhandenen Verknüpfungen zu aktualisieren. Sie können diese Gruppe von Tastenkombinationen beispielsweise aktualisieren, wenn sich die Symbole der Chat-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 von nicht dynamischen, angepinnten Verknüpfungen verwenden, da bei diesen beiden Methoden versucht wird, die angegebenen Listen von Verknüpfungen in dynamische Verknüpfungen zu konvertieren.

Es gibt kein Limit für die Anzahl der Verknüpfungen, die für die Anzeige in Assistant-Apps wie Google Assistant bereitgestellt werden können. Verwenden Sie die Methode pushDynamicShortcut der Jetpack-Bibliothek ShortcutManagerCompat, um Verknüpfungen für die Verwendung in Assistenten-Apps zu erstellen und zu aktualisieren. Fügen Sie Ihrer App außerdem die Bibliothek „Google Shortcuts Integration“ hinzu, damit dynamische Links in Google Assistant angezeigt werden können.

Weitere Informationen zu Richtlinien für App-Verknüpfungen, einschließlich des Aktualisierens von Verknüpfungen, finden Sie unter Best Practices für Verknüpfungen.

Umgang mit Änderungen der Systemsprache

Apps müssen dynamische und angepinnte Verknüpfungen aktualisieren, wenn sie den Broadcast Intent.ACTION_LOCALE_CHANGED erhalten, der eine Änderung des Systemgebietsschemas angibt.

Verwendung von Tastenkombinationen erfassen

Um zu ermitteln, in welchen Situationen statische und dynamische Verknüpfungen angezeigt werden, wird der Aktivierungsverlauf von Verknüpfungen untersucht. Bei statischen Verknüpfungen können Sie nachverfolgen, wann Nutzer bestimmte Aktionen in Ihrer App ausführen, indem Sie die Methode reportShortcutUsed aufrufen und ihr die ID einer Verknüpfung übergeben, wenn eines der folgenden Ereignisse eintritt:

• Der Nutzer wählt den Kurzbefehl mit der angegebenen ID aus.
• Der Nutzer führt die Aktion, die dem Shortcut entspricht, manuell in der App aus.

Ihre App erfasst die Nutzung dynamischer Verknüpfungen, indem sie die Methode pushDynamicShortcut aufruft und ihr die ID der Verknüpfung übergibt, wenn ein relevantes Ereignis eintritt. Wenn Sie die Verwendung dynamischer Verknüpfungen mit dieser Methode erzwingen, können Assistant-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 Tastenkombinationen 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.

Hinweis :Die Google Shortcuts Integration Library ist erforderlich, damit die dynamischen Links, die Ihre App sendet, auf Google-Plattformen wie Google Assistant angezeigt werden können. Wenn Sie diese Bibliothek in Ihre App einbinden, kann Assistant Ihre dynamischen Links berücksichtigen und Nutzern in der Assistant App vorschlagen.

Tastenkombinationen deaktivieren

Da Ihre App und ihre Nutzer Verknüpfungen an den Launcher des Geräts anpinnen können, ist es möglich, dass diese angepinnten Verknüpfungen Nutzer zu Aktionen in Ihrer App weiterleiten, die veraltet sind oder nicht mehr vorhanden sind. Um diese Situation zu vermeiden, können Sie die Verknüpfungen deaktivieren, die Nutzer nicht auswählen sollen. Rufen Sie 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 werden deaktiviert. Sie können auch eine überladene Version dieser Methode verwenden, die CharSequence als benutzerdefinierte Fehlermeldung akzeptiert. Diese Fehlermeldung wird dann angezeigt, wenn Nutzer versuchen, ein deaktiviertes Tastenkürzel zu starten.

Hinweis :Wenn Sie beim Aktualisieren Ihrer App einige der statischen Verknüpfungen entfernen, werden diese vom System automatisch deaktiviert.

Ratenbegrenzung

Wenn Sie die Methoden setDynamicShortcuts, addDynamicShortcuts oder updateShortcuts verwenden, können Sie diese Methoden in einer Hintergrund-App (einer App ohne Aktivitäten oder Dienste im Vordergrund) möglicherweise nur eine bestimmte Anzahl von Malen aufrufen. Die Beschränkung der Anzahl der Aufrufe dieser Methoden 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. Dazu gehören:

• Eine App wird im Vordergrund angezeigt.
• Die Systemsprache ändert sich.
• Der Nutzer führt die Aktion Inline-Antwort für eine Benachrichtigung aus.

Wenn während der Entwicklung oder des Tests Ratenbegrenzungen auftreten, können Sie in den Geräteeinstellungen 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

Sie können Nutzern ermöglichen, beim Wechseln von Geräten Sicherungs- und Wiederherstellungsvorgänge für Ihre App auszuführen, indem Sie die Zuweisung des Attributs android:allowBackup="true" in die Manifestdatei Ihrer App aufnehmen. Wenn Sie Sicherung und Wiederherstellung unterstützen, beachten Sie die folgenden Punkte zu App-Verknüpfungen:

• Statische Verknüpfungen werden automatisch neu veröffentlicht, aber erst, nachdem der Nutzer Ihre App auf einem neuen Gerät neu installiert hat.
• Dynamische Verknüpfungen werden nicht gesichert. Sie müssen daher in Ihre App eine Logik einbauen, mit der 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, aber das System sichert keine Symbole, die mit angepinnten Verknüpfungen verknüpft sind. Speichern Sie die Bilder Ihrer angepinnten Verknüpfungen daher in Ihrer 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 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.getPinnedShortcuts(this).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}