Verknüpfungen erstellen

Mit Verknüpfungen kannst du deinen Nutzern bestimmte Arten von Inhalten bereitstellen, indem du ihnen den schnellen Zugriff auf Teile deiner App ermöglichst.

Wie Sie Inhalte mit Verknüpfungen bereitstellen, hängt von Ihrem Anwendungsfall ab und davon, ob der Kontext der Verknüpfung von der App oder vom Nutzer gesteuert wird. Der Kontext einer statischen Verknüpfung ändert sich zwar nicht, der einer dynamischen Verknüpfung jedoch ständig. In beiden Fällen wird der Kontext aber von der App gesteuert. Wenn ein Nutzer festlegt, wie deine App Inhalte bereitstellt, z. B. mit einer angepinnten Verknüpfung, wird der Kontext vom Nutzer definiert. In den folgenden Szenarien werden einige Anwendungsfälle für die einzelnen Tastenkombinationstypen beschrieben:

• Statische Verknüpfungen eignen sich am besten für Apps, die während der gesamten Interaktion des Nutzers mit der App über eine einheitliche Struktur mit Inhalten verknüpft sind. Da die meisten Launcher nur vier Verknüpfungen gleichzeitig anzeigen, sind statische Verknüpfungen nützlich, um eine Routineaufgabe auf einheitliche Weise auszuführen, z. B. wenn der Nutzer seinen Kalender oder seine E‑Mails auf eine bestimmte Weise ansehen möchte.
• Dynamische Verknüpfungen werden für kontextabhängige Aktionen in Apps verwendet. Kontextsensitive Verknüpfungen sind auf die Aktionen zugeschnitten, die Nutzer in einer App ausführen. Wenn Sie beispielsweise ein Spiel entwickeln, bei dem der Nutzer beim Start auf dem aktuellen Level beginnen kann, müssen Sie die Verknüpfung häufig aktualisieren. Mit einer dynamischen Verknüpfung kannst du die Verknüpfung jedes Mal aktualisieren, wenn der Nutzer ein Level abschließt.
• Angepinnte Verknüpfungen werden für bestimmte nutzergesteuerte Aktionen verwendet. Beispielsweise möchte ein Nutzer eine bestimmte Website an den Launcher anpinnen. Das ist von Vorteil, weil der Nutzer so eine benutzerdefinierte Aktion ausführen kann, z. B. in einem Schritt zur Website wechseln, und zwar schneller als mit einer Standardinstanz eines Browsers.

Statische Verknüpfungen erstellen

Statische Verknüpfungen enthalten Links zu allgemeinen Aktionen in Ihrer App. Diese Aktionen müssen während der gesamten Lebensdauer der aktuellen Version Ihrer App gleich bleiben. Gute Optionen für statische Verknüpfungen sind das Anzeigen gesendeter Nachrichten, das Einstellen eines Alarms 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 App nach der 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 App 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 der neuen 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 Beschreibungs-Labels 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.Main" />
       <!-- 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>
   shortcuts.xml

Attributwerte anpassen

Die folgende Liste enthält Beschreibungen der verschiedenen Attribute in 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 dafür ausführt.

android:shortcutShortLabel

Eine kurze Beschreibung des Zwecks der Verknüpfung. Beschränken Sie diese Kurzbeschreibung nach Möglichkeit auf 10 Zeichen.

Weitere Informationen finden Sie unter setShortLabel().

android:shortcutLongLabel

Eine erweiterte Wortgruppe, die den Zweck der Verknüpfung beschreibt. Wenn genügend Platz vorhanden ist, wird dieser Wert anstelle von android:shortcutShortLabel im Launcher 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 den Wert true hat.

android:enabled

Bestimmt, ob der Nutzer über einen unterstützten Launcher mit der Verknüpfung interagieren kann. Der Standardwert von android:enabled ist true. Wenn Sie den Wert auf false setzen, legen Sie einen android:shortcutDisabledMessage fest, der erklärt, warum Sie die Verknüpfung deaktivieren. Wenn Sie der Meinung sind, dass Sie eine solche Nachricht nicht bereitstellen 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 er dem Nutzer die Verknüpfung anzeigt. 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 die Leistung und Konsistenz zu verbessern.

Innere Elemente konfigurieren

Die XML-Datei, in der die statischen Verknüpfungen einer App aufgeführt sind, unterstützt die folgenden Elemente innerhalb jedes <shortcut>-Elements. Sie müssen für jede statische Verknüpfung, die Sie definieren, ein inneres intent-Element 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 angeben.

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

categories

Bietet eine Gruppierung für die Arten von Aktionen, die von den Verknüpfungen Ihrer App ausgeführt werden, z. B. das Erstellen neuer Chatnachrichten.

Eine Liste der unterstützten Shortcut-Kategorien findest du in der Klassenreferenz zu ShortcutInfo.

capability-binding

Deklariert die mit dem Kurzbefehl verknüpfte Funktion.

Im vorherigen Beispiel ist die Verknüpfung mit einer Funktion verknüpft, die für CREATE_MESSAGE deklariert ist. Dies ist ein integrierter Intent für App Actions. Mit dieser Funktionsbindung können Nutzer per Sprachbefehl mit Google Assistant eine Verknüpfung aufrufen.

Dynamische Verknüpfungen erstellen

Dynamische Verknüpfungen enthalten Links zu bestimmten, kontextabhängigen Aktionen in Ihrer App. Diese Aktionen können sich zwischen den einzelnen Nutzungen Ihrer App und während der Ausführung Ihrer App ändern. Gute Anwendungsfälle für dynamische Verknüpfungen sind das Anrufen einer bestimmten Person, das Navigieren zu einem bestimmten Ort und das Laden eines Spiels ab dem letzten Speicherpunkt des Nutzers. Sie können auch dynamische Verknüpfungen verwenden, um eine Unterhaltung zu öffnen.

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

Mit der ShortcutManagerCompat API kann Ihre App die folgenden Vorgänge mit dynamischen Verknüpfungen ausführen:

• Push und Update:Verwende pushDynamicShortcut(), um deine dynamischen Verknüpfungen zu veröffentlichen und zu aktualisieren. Wenn bereits dynamische oder angepinnte Verknüpfungen mit derselben ID vorhanden sind, werden alle änderbaren Verknüpfungen aktualisiert.
• Entfernen:Mit removeDynamicShortcuts() kannst du eine Reihe dynamischer Verknüpfungen entfernen. Entfernen Sie alle dynamischen Verknüpfungen mit removeAllDynamicShortcuts().

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

Hier ein Beispiel für das Erstellen einer dynamischen Verknüpfung und das Verknüpfen mit Ihrer App:

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)
ShortcutsSnippets.kt

Bibliothek „Google Shortcuts Integration“ hinzufügen

Die Google Shortcuts Integration Library ist eine optionale Jetpack-Bibliothek. Damit kannst du dynamische Verknüpfungen erstellen, die auf Android-Oberflächen wie dem Launcher und auf Google-Oberflächen angezeigt werden können. Mit dieser Bibliothek können Nutzer deine Verknüpfungen finden, um schnell auf bestimmte Inhalte zuzugreifen oder Aktionen in deiner App zu wiederholen.

Dynamische Verknüpfungen, die mit dieser Bibliothek übertragen werden, unterliegen nicht den Verknüpfungslimits, 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 auf diese Weise häufig Verknüpfungen senden, kann Google die Nutzungsmuster Ihrer Nutzer besser nachvollziehen und ihnen kontextrelevante Verknüpfungen vorschlagen.

Assistant kann beispielsweise aus Kurzbefehlen, die von deiner Fitness-Tracker-App gesendet werden, lernen, dass ein Nutzer normalerweise jeden Morgen läuft, und proaktiv einen Kurzbefehl zum Starten eines Laufs vorschlagen, wenn der Nutzer morgens sein Smartphone in die Hand nimmt.

Die Google Shortcuts Integration Library bietet selbst keine adressierbaren Funktionen. Wenn Sie diese Bibliothek Ihrer App hinzufügen, können Google-Oberflächen die Kurzbefehle übernehmen, die Ihre App mit ShortcutManagerCompat überträgt.

Wenn Sie diese Bibliothek in Ihrer App verwenden möchten, fügen Sie der Datei app/build.gradle oder app/build.gradle.kts 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")
}

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

Nachdem Sie die Bibliotheksabhängigkeiten Ihrem Android-Projekt hinzugefügt haben, kann Ihre App die Methode pushDynamicShortcut() aus ShortcutManagerCompat verwenden, um dynamische Verknüpfungen zu übertragen, die im Launcher und auf teilnehmenden Google-Oberflächen 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 Verknüpfungen werden angepinnte Verknüpfungen in unterstützten Launchern als separate Symbole angezeigt. Abbildung 1 zeigt den Unterschied zwischen diesen beiden Arten von Verknüpfungen.

So pinnen Sie eine Verknüpfung mit Ihrer App an einen unterstützten Launcher an:

1. Mit isRequestPinShortcutSupported() kannst du prüfen, ob der Standard-Launcher des Geräts das Anpinnen von Verknüpfungen in der App unterstützt.

2. Erstelle ein ShortcutInfoCompat-Objekt, das eine ID, einen Intent und ein kurzes Label für die Verknüpfung enthält. Wenn die Verknüpfung vorhanden ist, verwenden Sie die ID der vorhandenen Verknüpfung. Das System findet und pinnt automatisch alle anderen Informationen, die mit dem Shortcut zusammenhängen.

3. Pinne die Verknüpfung an den Launcher des Geräts an, indem du requestPinShortcut() aufrufst. Während dieses Vorgangs können Sie ein PendingIntent-Objekt übergeben, das Ihre App nur dann benachrichtigt, wenn die Verknüpfung erfolgreich angepinnt wurde.

   Nachdem eine Verknüpfung angepinnt wurde, kann deine App ihre Inhalte mit der Methode updateShortcuts() aktualisieren. Weitere Informationen finden Sie unter Verknüpfungen aktualisieren.

Das folgende Code-Snippet zeigt, wie Sie eine angepinnte Verknüpfung erstellen:

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .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 =
        ShortcutManagerCompat.createShortcutResultIntent(context, 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 */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}
ShortcutsSnippets.kt

Benutzerdefinierte Aktivität für Verknüpfung erstellen

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

Fügen Sie in der Manifestdatei Ihrer App dem <intent-filter>-Element der Aktivität ACTION_CREATE_SHORTCUT hinzu. Diese Deklaration legt das folgende Verhalten fest, wenn der Nutzer versucht, eine Verknüpfung zu erstellen:

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

Ebenso kann deine App Nutzer nach der Installation oder beim ersten Start der App auffordern, angepinnte Verknüpfungen zum Startbildschirm hinzuzufügen. Diese Methode ist effektiv, weil sie Nutzern hilft, eine Verknüpfung als Teil ihres normalen Workflows zu erstellen.

Tastenkombinationen testen

Wenn du die Verknüpfungen deiner App testen möchtest, installiere sie 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 aufzurufen, die du für deine App definiert hast.
• Ziehen Sie eine Verknüpfung, um sie an den Launcher des Geräts anzupinnen.