Verknüpfungen erstellen

Verknüpfungen liefern bestimmte Arten von Inhalten für deine Nutzer, da sie schnell auf Teile deiner App zugreifen können.

Wie Sie Inhalte mit Verknüpfungen bereitstellen, hängt von Ihrem Anwendungsfall ab und davon, ob der Kontext der Verknüpfung app- oder nutzergesteuert ist. Obwohl sich der Kontext einer statischen Verknüpfung nicht ändert und der Kontext einer dynamischen Verknüpfung sich ständig ändert, steuert Ihre Anwendung in beiden Fällen den Kontext. Wenn ein Nutzer entscheidet, wie Ihre App Inhalte an ihn sendet, z. B. durch eine angepinnte Verknüpfung, wird der Kontext von den Nutzern definiert. In den folgenden Szenarien werden einige Anwendungsfälle für jeden Verknüpfungstyp beschrieben:

• Statische Tastenkombinationen eignen sich am besten für Apps, die über eine einheitliche Struktur mit Inhalten verknüpft sind, während die Nutzer mit der App interagieren. Da die meisten Launcher nur vier Tastenkombinationen auf einmal anzeigen, sind statische Verknüpfungen nützlich, um Routineaufgaben auf konsistente Weise auszuführen, z. B. wenn der Nutzer seinen Kalender oder seine E-Mails auf eine bestimmte Weise ansehen möchte.
• Dynamische Tastenkombinationen werden für kontextabhängige Aktionen in Anwendungen verwendet. Kontextsensitive Verknüpfungen sind auf die Aktionen zugeschnitten, die Nutzer in einer App ausführen. Wenn du beispielsweise ein Spiel erstellst, bei dem der Nutzer beim Start mit seinem aktuellen Level beginnen kann, musst du die Verknüpfung häufig aktualisieren. Wenn du eine dynamische Tastenkombination verwendest, kannst du die Tastenkombination jedes Mal aktualisieren, wenn der Nutzer eine Ebene löscht.
• Angepinnte Tastenkombinationen werden für bestimmte nutzergesteuerte Aktionen verwendet. Beispielsweise kann ein Nutzer eine bestimmte Website an den Launcher anpinnen. Dies ist vorteilhaft, da der Nutzer damit eine benutzerdefinierte Aktion ausführen kann, z. B. das Aufrufen der Website in einem Schritt schneller als über eine Standardinstanz eines Browsers.

Statische Verknüpfungen erstellen

Statische Verknüpfungen stellen Links zu allgemeinen Aktionen in Ihrer App zur Verfügung. Diese Aktionen müssen über die Lebensdauer der aktuellen Version Ihrer App hinweg konsistent bleiben. Gute Optionen für statische Verknüpfungen sind das Anzeigen gesendeter Nachrichten, das Einstellen eines Weckers und das Anzeigen der Trainingsaktivität eines Nutzers für den Tag.

So erstellen Sie eine statische Verknüpfung:

1. Suchen Sie in der Datei AndroidManifest.xml Ihrer Anwendung die Aktivität, deren Intent-Filter auf die Aktion android.intent.action.MAIN und die Kategorie android.intent.category.LAUNCHER festgelegt sind.

2. Fügen Sie dieser Aktivität ein <meta-data>-Element hinzu, das auf die Ressourcendatei verweist, in der die Verknüpfungen der Anwendung definiert sind:

     <manifest xmlns:android="http://schemas.android.com/apk/res/android"
               package="com.example.myapplication">
       <application ... >
         <activity android:name="Main">
           <intent-filter>
             <action android:name="android.intent.action.MAIN" />
             <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
           
           <meta-data android:name="android.app.shortcuts"
                      android:resource="@xml/shortcuts" /> 
         </activity>
       </application>
     </manifest>
     

3. Erstellen Sie eine neue Ressourcendatei mit dem Namen res/xml/shortcuts.xml.

4. Fügen Sie in die neue Ressourcendatei ein <shortcuts>-Stammelement hinzu, das eine Liste von <shortcut>-Elementen enthält. Fügen Sie in jedes <shortcut>-Element Informationen zu einer statischen Verknüpfung ein, einschließlich des Symbols, der Beschreibungslabels und der Intents, die in der App gestartet werden:

     <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
       <shortcut
         android:shortcutId="compose"
         android:enabled="true"
         android:icon="@drawable/compose_icon"
         android:shortcutShortLabel="@string/compose_shortcut_short_label1"
         android:shortcutLongLabel="@string/compose_shortcut_long_label1"
         android:shortcutDisabledMessage="@string/compose_disabled_message1">
         <intent
           android:action="android.intent.action.VIEW"
           android:targetPackage="com.example.myapplication"
           android:targetClass="com.example.myapplication.ComposeActivity" />
         <!-- If your shortcut is associated with multiple intents, include them
              here. The last intent in the list determines what the user sees when
              they launch this shortcut. -->
         <categories android:name="android.shortcut.conversation" />
         <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
       </shortcut>
       <!-- Specify more shortcuts here. -->
     </shortcuts>
     

Attributwerte anpassen

Die folgende Liste enthält Beschreibungen für die verschiedenen Attribute innerhalb einer statischen Verknüpfung. Geben Sie einen Wert für android:shortcutId und android:shortcutShortLabel an. Alle anderen Werte sind optional.

android:shortcutId

Ein Stringliteral, das die Verknüpfung darstellt, wenn ein ShortcutManager-Objekt Vorgänge darauf ausführt.

android:shortcutShortLabel

Eine kurze Formulierung, die den Zweck der Verknüpfung beschreibt. Beschränken Sie diese Kurzbeschreibung möglichst auf 10 Zeichen.

Weitere Informationen finden Sie unter setShortLabel().

android:shortcutLongLabel

Eine erweiterte Formulierung, die den Zweck der Verknüpfung beschreibt. Wenn ausreichend Speicherplatz vorhanden ist, wird im Launcher dieser Wert anstelle von android:shortcutShortLabel angezeigt. Beschränken Sie diese lange Beschreibung nach Möglichkeit auf 25 Zeichen.

Weitere Informationen finden Sie unter setLongLabel().

android:shortcutDisabledMessage

Die Meldung, die in einem unterstützten Launcher angezeigt wird, wenn der Nutzer versucht, eine deaktivierte Verknüpfung zu starten. In der Nachricht muss dem Nutzer erklärt werden, warum die Verknüpfung deaktiviert ist. Der Wert dieses Attributs hat keine Auswirkungen, wenn android:enabled true ist.

android:enabled

Legt fest, ob der Nutzer mit der Verknüpfung in einem unterstützten Launcher interagieren kann. Der Standardwert von android:enabled ist true. Wenn Sie false festlegen, legen Sie einen android:shortcutDisabledMessage fest, der erklärt, warum Sie die Verknüpfung deaktivieren. Wenn Sie der Meinung sind, dass Sie keine solche Nachricht zur Verfügung stellen müssen, entfernen Sie die Verknüpfung vollständig aus der XML-Datei.

android:icon

Die Bitmap oder das adaptive Symbol, das der Launcher verwendet, wenn die Verknüpfung für den Nutzer angezeigt wird. Dieser Wert kann der Pfad zu einem Image oder der Ressourcendatei sein, die das Image enthält. Verwenden Sie nach Möglichkeit adaptive Symbole, um Leistung und Konsistenz zu verbessern.

Elemente im Inneren konfigurieren

Die XML-Datei, in der die statischen Verknüpfungen einer Anwendung aufgeführt sind, unterstützt die folgenden Elemente in jedem <shortcut>-Element. Für jede statische Tastenkombination, die Sie definieren, müssen Sie ein inneres Element intent einfügen.

intent

Die Aktion, die das System startet, wenn der Nutzer die Verknüpfung auswählt. Dieser Intent muss einen Wert für das Attribut android:action bereitstellen.

Sie können mehrere Intents für eine einzelne Verknüpfung angeben. Weitere Informationen finden Sie unter Mehrere Intents und Aktivitäten verwalten, Intent festlegen und in der Klassenreferenz TaskStackBuilder.

categories

Bietet eine Gruppierung der Aktionen, die von den Verknüpfungen Ihrer Anwendung ausgeführt werden, z. B. das Erstellen neuer Chatnachrichten.

Eine Liste der unterstützten Verknüpfungskategorien finden Sie in der Referenz zur ShortcutInfo-Klasse.

capability-binding

Deklariert die Funktion, die mit der Verknüpfung verknüpft ist.

Im vorherigen Beispiel ist die Verknüpfung mit einer Funktion verknüpft, die für CREATE_MESSAGE deklariert wurde. Dies ist ein integrierter Intent für App Actions. Mit dieser Funktionsbindung können Nutzer gesprochene Befehle mit Google Assistant verwenden, um eine Verknüpfung aufzurufen.

Dynamische Tastenkombinationen erstellen

Dynamische Tastenkombinationen stellen Links zu bestimmten, kontextabhängigen Aktionen innerhalb Ihrer Anwendung bereit. Diese Aktionen können sich zwischen den Verwendungen Ihrer Anwendung und deren Ausführung ändern. Dynamische Tastenkombinationen eignen sich zum Beispiel, um eine bestimmte Person anzurufen, zu einem bestimmten Ort zu navigieren und ein Spiel vom letzten Speicherpunkt des Nutzers aus zu laden. Sie können auch dynamische Tastenkombinationen verwenden, um eine Unterhaltung zu öffnen.

Die ShortcutManagerCompat Jetpack-Bibliothek ist ein Hilfsprogramm für die ShortcutManager API, mit der Sie dynamische Verknüpfungen in Ihrer App verwalten können. Durch die Verwendung der ShortcutManagerCompat-Bibliothek wird der Boilerplate-Code reduziert und dafür gesorgt, dass Ihre Verknüpfungen auf allen Android-Versionen einheitlich funktionieren. Diese Bibliothek ist auch erforderlich, um dynamische Tastenkombinationen zu senden, damit sie auf Google-Oberflächen wie Assistant mit der Google Shortcuts Integration Library angezeigt werden können.

Mit der ShortcutManagerCompat API kann Ihre Anwendung die folgenden Vorgänge mit dynamischen Tastenkombinationen ausführen:

• Push und Update: Verwenden Sie pushDynamicShortcut(), um Ihre dynamischen Verknüpfungen zu veröffentlichen und zu aktualisieren. Wenn es bereits dynamische oder angepinnte Verknüpfungen mit derselben ID gibt, wird jede änderbare Verknüpfung aktualisiert.
• Entfernen:Mithilfe von removeDynamicShortcuts() können Sie eine Reihe dynamischer Tastenkombinationen entfernen. Entfernen Sie alle dynamischen Tastenkombinationen mit removeAllDynamicShortcuts().

Weitere Informationen zum Ausführen von Vorgängen für Tastenkombinationen finden Sie unter Verknüpfungen verwalten und in der Referenz zu ShortcutManagerCompat.

Hier sehen Sie ein Beispiel, wie Sie eine dynamische Verknüpfung erstellen und mit Ihrer Anwendung verknüpfen:

val shortcut = ShortcutInfoCompat.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

ShortcutInfoCompat shortcut = new ShortcutInfoCompat.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
    .setIntent(new Intent(Intent.ACTION_VIEW,
                   Uri.parse("https://www.mysite.example.com/")))
    .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

Integrationsbibliothek für Google-Verknüpfungen hinzufügen

Die Google Shortcuts Integration Library ist eine optionale Jetpack-Bibliothek. Sie können damit dynamische Tastenkombinationen verwenden, die auf Android-Oberflächen wie dem Launcher und auf Google-Oberflächen wie Assistant angezeigt werden können. Mithilfe dieser Bibliothek können Nutzer Verknüpfungen erkennen, mit denen sie schnell auf bestimmte Inhalte zugreifen oder Aktionen in Ihrer App noch einmal wiedergeben können.

Beispielsweise kann eine Messaging-App eine dynamische Verknüpfung für einen Kontakt mit dem Namen „Alex“ senden, nachdem ein Nutzer eine Nachricht an diese Person gesendet hat. Wenn der Nutzer nach dem Senden der dynamischen Tastenkombination Assistant „Hey Google, sende eine Nachricht an Alex in der Beispiel-App“ sagt, kann Assistant die Beispiel-App starten und automatisch so konfigurieren, dass eine Nachricht an Alex gesendet wird.

Dynamische Tastenkombinationen, die mit dieser Bibliothek bereitgestellt werden, unterliegen nicht den Limits für Verknüpfungen, die pro Gerät gelten. So kann Ihre App jedes Mal eine Verknüpfung senden, wenn ein Nutzer eine zugehörige Aktion in Ihrer App ausführt. Wenn Sie häufige Tastenkombinationen auf diese Weise verwenden, kann Google die Nutzungsmuster Ihrer Nutzer nachvollziehen und ihnen kontextbezogene Verknüpfungen vorschlagen.

Beispielsweise kann Assistant aus den von Ihrer Fitness-Tracking-App gesendeten Verknüpfungen lernen, die ein Nutzer normalerweise jeden Morgen ausführt, und proaktiv eine Verknüpfung zum Starten eines Laufs vorschlagen, wenn der Nutzer morgens sein Smartphone zur Hand nimmt.

Die Google Shortcuts Integration Library selbst bietet keine anpassbaren Funktionen. Wenn du diese Bibliothek deiner App hinzufügst, können Google-Oberflächen die Verknüpfungen übernehmen, die deine App mit ShortcutManagerCompat sendet.

So verwenden Sie diese Bibliothek in Ihrer App:

1. Aktualisieren Sie die Datei gradle.properties, damit sie AndroidX-Bibliotheken unterstützt:

         
         android.useAndroidX=true
         # Automatically convert third-party libraries to use AndroidX
         android.enableJetifier=true
         
         

2. Fügen Sie in app/build.gradle Abhängigkeiten für die Google Shortcuts Integration Library und ShortcutManagerCompat hinzu:

         
         dependencies {
           implementation "androidx.core:core:1.6.0"
           implementation 'androidx.core:core-google-shortcuts:1.0.0'
           ...
         }
         
         

Nachdem die Bibliotheksabhängigkeiten deinem Android-Projekt hinzugefügt wurden, kann deine App die Methode pushDynamicShortcut() von ShortcutManagerCompat verwenden, um dynamische Verknüpfungen zu senden, die im Launcher und auf teilnehmenden Google-Plattformen angezeigt werden können.

Angepinnte Verknüpfungen erstellen

Unter Android 8.0 (API-Level 26) und höher können Sie angepinnte Verknüpfungen erstellen. Im Gegensatz zu statischen und dynamischen Tastenkombinationen werden angepinnte Verknüpfungen in unterstützten Launchern als separate Symbole angezeigt. In Abbildung 1 sehen Sie den Unterschied zwischen diesen beiden Arten von Tastenkombinationen.

Führe die folgenden Schritte aus, um mit deiner App eine Verknüpfung zu einem unterstützten Launcher anzupinnen:

1. Verwende isRequestPinShortcutSupported(), um zu prüfen, ob der Standard-Launcher des Geräts das In-App-Anpinnen von Verknüpfungen unterstützt.

2. Sie haben zwei Möglichkeiten, ein ShortcutInfo-Objekt zu erstellen, je nachdem, ob die Verknüpfung vorhanden ist:

   1. Wenn die Verknüpfung vorhanden ist, erstellen Sie ein ShortcutInfo-Objekt, das nur die ID der vorhandenen Verknüpfung enthält. Alle anderen Informationen zur Verknüpfung werden automatisch gefunden und angepinnt.
   2. Wenn Sie eine neue Verknüpfung anpinnen, erstellen Sie ein ShortcutInfo-Objekt, das eine ID, einen Intent und ein kurzes Label für die neue Verknüpfung enthält.

3. Du kannst die Verknüpfung durch Aufrufen von requestPinShortcut() an den Launcher des Geräts anpinnen. Bei diesem Vorgang kannst du ein PendingIntent-Objekt übergeben, das deine App nur dann benachrichtigt, wenn die Verknüpfung erfolgreich angepinnt wurde.

   Nachdem eine Verknüpfung angepinnt ist, kann die App ihre Inhalte mithilfe der Methode updateShortcuts() aktualisieren. Weitere Informationen finden Sie unter Tastenkombinationen aktualisieren.

Im folgenden Code-Snippet sehen Sie, wie Sie eine angepinnte Verknüpfung erstellen.

val shortcutManager = getSystemService(ShortcutManager::class.java)

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Enable the existing shortcut with the ID "my-shortcut".
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    PendingIntent successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0);

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

Aktivität für benutzerdefinierte Kurzbefehle erstellen

Sie können auch eine spezielle Aktivität erstellen, mit der Nutzer Verknüpfungen mit benutzerdefinierten Optionen und einer Bestätigungsschaltfläche erstellen können. Abbildung 2 zeigt ein Beispiel für diese Art von Aktivität in der Gmail App.

Fügen Sie in der Manifestdatei Ihrer App ACTION_CREATE_SHORTCUT zum Element <intent-filter> der Aktivität hinzu. Diese Deklaration führt zu folgendem Verhalten, wenn der Nutzer versucht, eine Verknüpfung zu erstellen:

1. Das System startet die spezialisierte Aktivität Ihrer App.
2. Der Nutzer legt Optionen für die Verknüpfung fest.
3. Der Nutzer wählt die Bestätigungsschaltfläche aus.
4. Ihre App erstellt die Verknüpfung mit der Methode createShortcutResultIntent(). Diese Methode gibt ein Intent zurück, das Ihre Anwendung mithilfe von setResult() an die zuvor ausgeführte Aktivität zurückgibt.
5. Ihre App ruft finish() für die Aktivität auf, die zum Erstellen der benutzerdefinierten Verknüpfung verwendet wurde.

Ebenso kann Ihre App Nutzer nach der Installation oder beim ersten Start der App auffordern, angepinnte Verknüpfungen zum Startbildschirm hinzuzufügen. Diese Methode ist effektiv, da sie Ihren Nutzern dabei hilft, eine Verknüpfung im Rahmen ihres normalen Workflows zu erstellen.

Tastenkombinationen testen

Wenn du die Verknüpfungen deiner App testen möchtest, installiere die App auf einem Gerät mit einem Launcher, der Verknüpfungen unterstützt. Führen Sie dann die folgenden Aktionen aus:

• Halte das Launcher-Symbol deiner App gedrückt, um die Verknüpfungen anzuzeigen, die du für deine App festgelegt hast.
• Ziehe eine Verknüpfung in die Übersicht des Geräts, um sie anzupinnen.