Nachdem Sie Verknüpfungen erstellt haben, müssen Sie sie möglicherweise während des 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 können Sie eine angepinnte Verknüpfung deaktivieren, um zu verhindern, dass Ihre App veraltete oder fehlende Aktionen ausführt. Bei Verknüpfungen, auf die in Unterhaltungen verwiesen wird, können Sie die Nutzung verfolgen, 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 von Verknüpfungen beschrieben.
Verknüpfungsverhalten
In den folgenden Abschnitten finden Sie allgemeine Informationen zum Verknüpfungsverhalten, einschließlich Sichtbarkeit, Anzeigereihenfolge und Rängen.
Sichtbarkeit von Verknüpfungen
Statische und dynamische Verknüpfungen werden in einem unterstützten Launcher oder Assistant angezeigt, wenn der Nutzer eine bestimmte Geste ausführt oder einen Sprachbefehl gibt. Bei unterstützten Launchern ist die Geste ein langes Tippen auf das Launcher-Symbol der App. 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 LauncherApps Klasse bietet APIs für Launcher-Apps, um auf
Verknüpfungen zuzugreifen.
Da angepinnte Verknüpfungen im Launcher selbst angezeigt werden, sind sie 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 wird deinstalliert.
- Der Nutzer löscht die Daten einer App. Dazu ruft er Einstellungen > Apps & Benachrichtigungen auf, wählt die App aus und tippt dann auf Speicher > Speicher löschen.
Freigabeziele sind eine Teilmenge dynamischer Verknüpfungen, die in der Zeile für die direkte Freigabe des Android-Sharesheets angezeigt werden.
Anzeigereihenfolge von Verknüpfungen
Wenn der Launcher die Verknüpfungen einer App anzeigt, müssen sie in der folgenden Reihenfolge erscheinen:
- Statische Verknüpfungen: Verknüpfungen, deren Methode
isDeclaredInManifest()gibttruezurück. - Dynamische Verknüpfungen: Verknüpfungen, deren
ShortcutInfo.isDynamic()Methodetruezurückgibt.
Innerhalb der einzelnen Verknüpfungstypen (statisch und dynamisch) werden Verknüpfungen nach
steigendem Rang gemäß ShortcutInfo.getRank sortiert. Google Assistant berücksichtigt auch den Rang von Verknüpfungen, wenn kontextbezogene Verknüpfungen für Nutzer bestimmt werden.
Ränge sind nicht negative, fortlaufende Ganzzahlen. Statische Verknüpfungen werden in der Reihenfolge von der ersten bis zur letzten Verknüpfung eingestuft, in der sie in der Datei shortcuts.xml erscheinen. 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 Verlauf des Nutzers, Aktualität, Häufigkeit, Ranghinweis, App-Nutzung und die 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 erstellt wurden. Dieser Dienst wurde in
Android 11 eingestellt. In Android 12 und höher werden Freigabeziele, die von ChooserTargetService generiert wurden, nicht mehr im Sharesheet angezeigt.
Die meisten Launcher zeigen maximal vier Verknüpfungen an. Bei jeder 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, zeigt der Launcher die ersten beiden statischen Verknüpfungen und die beiden dynamischen Verknüpfungen mit dem höchsten Rang an.
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 sie aufeinanderfolgende Aktivitäten auslöst. Je nach Verknüpfungstyp können Sie dazu mehrere Intents zuweisen, eine Aktivität aus einer anderen 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. Wenn Ihre App ausgeführt wird, werden also alle vorhandenen Aktivitäten in der App beendet, wenn eine statische Verknüpfung 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 Startblock oder onCreate auf, bevor Compose-Inhalte festgelegt werden:
Fügen Sie in der Datei
AndroidManifest.xml filedie Attributzuweisungandroid:taskAffinity=""in die Trampolinaktivität ein.Verweisen Sie in der Ressourcendatei für Verknüpfungen auf die Trampolinaktivität im Intent innerhalb der statischen Verknüpfung.
Weitere Informationen zu Trampolinaktivitäten finden Sie unter Eine Aktivität aus einer anderen starten.
Intent-Flags festlegen
Sie können dynamische Verknüpfungen mit beliebigen Intent-Flags veröffentlichen.
Geben Sie vorzugsweise die Kombination aus Intent.FLAG_ACTIVITY_SINGLE_TOP und Intent.FLAG_ACTIVITY_CLEAR_TOP im Intent der Verknüpfung an. Dadurch wird sichergestellt, dass Ihre ComponentActivity in den Vordergrund gerückt und wiederverwendet wird, wenn sie bereits aktiv ist, ohne dass sie beendet wird. So kann Ihre Architektur mit einer einzigen Aktivität das Verknüpfungsereignis über onNewIntent() verarbeiten.
Weitere Informationen zu Aufgaben und Intent-Flags finden Sie unter Aufgaben und der Back-Stack.
Verknüpfungen aktualisieren
Das Launcher-Symbol jeder App kann maximal so viele statische und dynamische
Verknüpfungen enthalten, wie der von
getMaxShortcutCountPerActivity zurückgegebene Wert. Die Anzahl der angepinnten Verknüpfungen, die eine App erstellen kann, ist nicht begrenzt.
Wenn eine dynamische Verknüpfung angepinnt ist, ist sie weiterhin sichtbar und kann gestartet werden, auch wenn der Herausgeber sie als dynamische Verknüpfung entfernt. So kann eine App mehr Verknüpfungen haben als die Anzahl, die von getMaxShortcutCountPerActivity zurückgegeben wird.
Im folgenden Beispiel wird davon ausgegangen, dass der von getMaxShortcutCountPerActivity zurückgegebene Wert 4 ist:
- Eine Chat-App veröffentlicht vier dynamische Verknüpfungen, die die vier letzten Unterhaltungen darstellen: c1, c2, c3 und c4.
- Der Nutzer pinnt alle vier Verknüpfungen an.
- Später startet der Nutzer drei weitere Unterhaltungen: c5, c6 und c7. Die Herausgeber-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 auf Aktivitäten in der Herausgeber-App verweisen. Das liegt daran, dass die Gesamtzahl die maximale Anzahl von Verknüpfungen und die drei angepinnten Verknüpfungen umfasst.
- Die App kann
updateShortcuts(Context, List)verwenden, um eine der sieben vorhandenen Verknüpfungen zu aktualisieren. Sie können diese Verknüpfungen beispielsweise aktualisieren, wenn sich die Symbole der Chatpartner ändern. - Mit den
addDynamicShortcuts(Context, List)undsetDynamicShortcuts(Context, List)Methoden können Sie vorhandene Verknüpfungen mit denselben IDs aktualisieren. Sie können sie jedoch nicht verwenden, um nicht dynamische, angepinnte Verknüpfungen zu aktualisieren, da diese beiden Methoden versuchen, die angegebenen Listen von Verknüpfungen in dynamische Verknüpfungen zu konvertieren.
Die Anzahl der Verknüpfungen, die zur Anzeige in Assistant-Apps wie Google Assistant gesendet werden können, ist nicht begrenzt. Verwenden Sie die pushDynamicShortcut
Methode der ShortcutManagerCompat Jetpack-Bibliothek, um Verknüpfungen für die Verwendung in Assistant-Apps zu erstellen und zu aktualisieren. Fügen Sie Ihrer App außerdem die Google Shortcuts Integration
Bibliothek 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.
Änderungen der Systemsprache verarbeiten
Apps müssen dynamische und angepinnte Verknüpfungen aktualisieren, wenn sie die
Intent.ACTION_LOCALE_CHANGED Broadcast-Nachricht erhalten, die eine Änderung der System
sprache angibt.
Verknüpfungsnutzung 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 können Sie nachvollziehen, wann Nutzer bestimmte Aktionen in Ihrer App ausführen. Rufen Sie dazu die reportShortcutUsed Methode auf und übergeben Sie die ID einer Verknüpfung, wenn eines der folgenden Ereignisse eintritt:
- Der Nutzer wählt die Verknüpfung mit der angegebenen ID aus.
- Der Nutzer führt die Aktion, die der Verknüpfung entspricht, manuell in der App aus.
Ihre App verfolgt die Nutzung dynamischer Verknüpfungen, indem sie die Methode pushDynamicShortcut aufruft und die ID der Verknüpfung übergibt, wenn ein relevantes Ereignis eintritt.
Wenn Sie die Nutzung dynamischer Verknüpfungen mit dieser Methode senden, 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 Verknüpfungen auf.
Bei Verknüpfungen im Zusammenhang mit Unterhaltungen ist es wichtig, die Nutzung für ausgehende und eingehende Nachrichten zu verfolgen. Weitere Informationen finden Sie unter den Best Practices für Personen und Unterhaltungen.
Verknüpfungen 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 deaktiviert. Sie
können auch eine überladene Version dieser Methode verwenden, die eine
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. Das ist eine App ohne Aktivitäten oder Dienste im Vordergrund.
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 das Limit wieder erreicht ist. Zu diesen Ereignissen gehören:
- Eine App wird in den Vordergrund gerückt.
- Die Systemsprache ändert sich.
- Der Nutzer führt die Inline-Antwort Aktion für eine Benachrichtigung aus.
$ adb shell cmd shortcut reset-throttling [ --user <var>your-user-id</var> ]
Sichern und wiederherstellen
Sie können Nutzern ermöglichen, Sicherungs- und Wiederherstellungsvorgänge für Ihre App auszuführen, wenn
sie das Gerät wechseln. Fügen Sie dazu die android:allowBackup="true" Attribut
zuweisung in die Manifestdatei Ihrer App ein. 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. Fügen Sie daher in Ihrer App eine Logik hinzu, um sie neu zu veröffentlichen, 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 daher die Bilder Ihrer angepinnten Verknüpfungen in Ihrer App, damit sie schnell auf einem neuen Gerät 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.
}
}
}
// ...
}