Creare scorciatoie

Le scorciatoie forniscono tipi specifici di contenuti agli utenti aiutandoli ad accedere rapidamente a parti della tua app.

Il modo in cui pubblichi contenuti con le scorciatoie dipende dal caso d'uso e dal fatto che il contesto della scorciatoia sia basato sull'app o sull'utente. Anche se il contesto di una scorciatoia statica non cambia e quello di una scorciatoia dinamica cambia costantemente, l'app determina il contesto in entrambi i casi. Nei casi in cui un utente sceglie il modo in cui la tua app pubblica i contenuti, ad esempio con una scorciatoia bloccata, il contesto viene definito dall'utente. I seguenti scenari descrivono alcuni casi d'uso per ogni tipo di scorciatoia:

• Le scorciatoie statiche sono ideali per le app che si collegano ai contenuti utilizzando una struttura coerente per tutta la durata dell'interazione di un utente con l'app. Poiché la maggior parte degli strumenti di avvio visualizza solo quattro scorciatoie contemporaneamente, le scorciatoie statiche sono utili per eseguire un'attività di routine in modo coerente, ad esempio se l'utente vuole visualizzare il calendario o le email in un modo specifico .
• Le scorciatoie dinamiche vengono utilizzate per le azioni nelle app sensibili al contesto. Le scorciatoie sensibili al contesto sono personalizzate in base alle azioni eseguite dagli utenti in un'app. Ad esempio, se crei un gioco che consente all'utente di iniziare dal suo livello attuale al momento del lancio, devi aggiornare di frequente la scorciatoia. L'utilizzo di una scorciatoia dinamica ti consente di aggiornarla ogni volta che l'utente cancella un livello.
• Le scorciatoie bloccate vengono utilizzate per azioni specifiche guidate dall'utente. Ad esempio, un utente potrebbe voler bloccare un sito web specifico in Avvio app. Ciò è vantaggioso perché consente all'utente di eseguire un'azione personalizzata, ad esempio visitare il sito web in un solo passaggio, più rapidamente rispetto all'utilizzo di un'istanza predefinita di un browser.

Crea scorciatoie statiche

Le scorciatoie statiche forniscono link ad azioni generiche all'interno della tua app e queste azioni devono rimanere coerenti per tutta la durata della versione corrente dell'app. Le scorciatoie statiche includono la visualizzazione dei messaggi inviati, l'impostazione di una sveglia e la visualizzazione dell'attività fisica di un utente per la giornata.

Per creare una scorciatoia statica:

1. Nel file AndroidManifest.xml dell'app, trova l'attività i cui filtri per intent sono impostati sull'azione android.intent.action.MAIN e sulla categoria android.intent.category.LAUNCHER.

2. Aggiungi un elemento <meta-data> a questa attività che faccia riferimento al file delle risorse in cui sono definite le scorciatoie dell'app:

     <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. Crea un nuovo file di risorse denominato res/xml/shortcuts.xml.

4. Nel nuovo file di risorse, aggiungi un elemento principale <shortcuts> che contenga un elenco di elementi <shortcut>. In ogni elemento <shortcut>, includi informazioni su una scorciatoia statica, tra cui la relativa icona, le etichette della descrizione e gli intent che avvia all'interno dell'app:

     <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>
     

Personalizzare i valori degli attributi

Il seguente elenco include le descrizioni dei diversi attributi in una scorciatoia statica. Specifica un valore per android:shortcutId e android:shortcutShortLabel. Tutti gli altri valori sono facoltativi.

android:shortcutId

Un valore letterale stringa che rappresenta la scorciatoia quando un oggetto ShortcutManager esegue operazioni sull'oggetto.

android:shortcutShortLabel

Una frase concisa che descrive lo scopo della scorciatoia. Se possibile, limita la descrizione breve a 10 caratteri.

Per maggiori informazioni, consulta setShortLabel().

android:shortcutLongLabel

Una frase estesa che descrive lo scopo della scorciatoia. Se lo spazio è sufficiente, Avvio app mostra questo valore anziché android:shortcutShortLabel. Se possibile, limita la descrizione lunga a 25 caratteri.

Per maggiori informazioni, consulta setLongLabel().

android:shortcutDisabledMessage

Il messaggio che viene visualizzato in un Avvio app supportato quando l'utente tenta di avviare una scorciatoia disattivata. Il messaggio deve spiegare all'utente perché la scorciatoia è stata disattivata. Il valore di questo attributo non ha effetto se android:enabled è true.

android:enabled

Consente di stabilire se l'utente può interagire con la scorciatoia da un'Avvio app supportato. Il valore predefinito di android:enabled è true. Se la imposti su false, imposta un android:shortcutDisabledMessage che spieghi il motivo per cui stai disattivando la scorciatoia. Se non pensi di dover fornire questo messaggio, rimuovi completamente la scorciatoia dal file XML.

android:icon

L'icona bitmap o adattiva utilizzata da Avvio app quando la scorciatoia viene mostrata all'utente. Questo valore può essere il percorso di un'immagine o il file di risorse che contiene l'immagine. Se possibile, utilizza le icone adattive per migliorare prestazioni e coerenza.

Configura gli elementi interni

Il file XML che elenca le scorciatoie statiche di un'app supporta i seguenti elementi all'interno di ogni elemento <shortcut>. Devi includere un elemento interno intent per ogni scorciatoia statica che definisci.

intent

L'azione che il sistema avvia quando l'utente seleziona la scorciatoia. Questo intent deve fornire un valore per l'attributo android:action.

Puoi fornire più intent per una singola scorciatoia. Consulta Gestire più intent e attività, Impostare un intent e il riferimento della classe TaskStackBuilder per maggiori dettagli.

categories

Fornisce un raggruppamento per i tipi di azioni eseguite dalle scorciatoie dell'app, ad esempio la creazione di nuovi messaggi di chat.

Per un elenco delle categorie di scorciatoie supportate, consulta il riferimento della classe ShortcutInfo.

capability-binding

Dichiara la funzionalità collegata alla scorciatoia.

Nell'esempio precedente, la scorciatoia è collegata a una funzionalità dichiarata per CREATE_MESSAGE, che è un intent integrato Azioni app. Questa associazione di funzionalità consente agli utenti di utilizzare i comandi vocali con l'Assistente Google per richiamare una scorciatoia.

Creare scorciatoie dinamiche

Le scorciatoie dinamiche forniscono link ad azioni specifiche sensibili al contesto all'interno della tua app. Queste azioni possono cambiare da un utilizzo dell'app a un'altra durante l'esecuzione. Le scorciatoie dinamiche possono essere utili, ad esempio, per chiamare una persona specifica, navigare verso una località specifica e caricare un gioco dall'ultimo punto di salvataggio dell'utente. Puoi anche utilizzare le scorciatoie dinamiche per aprire una conversazione.

La ShortcutManagerCompat libreria Jetpack è un aiutante dell'API ShortcutManager che ti consente di gestire le scorciatoie dinamiche nella tua app. L'utilizzo della libreria ShortcutManagerCompat riduce il codice boilerplate e fa sì che le scorciatoie funzionino in modo coerente nelle versioni Android. Questa libreria è necessaria anche per il push delle scorciatoie dinamiche in modo che siano idonee alla visualizzazione sulle piattaforme Google, come l'Assistente Google, con la libreria di integrazione delle scorciatoie di Google.

L'API ShortcutManagerCompat consente alla tua app di eseguire le seguenti operazioni con le scorciatoie dinamiche:

• Esegui il push e l'aggiornamento: utilizza pushDynamicShortcut() per pubblicare e aggiornare le scorciatoie dinamiche. Se esistono già scorciatoie dinamiche o bloccate con lo stesso ID, ogni scorciatoia modificabile viene aggiornata.
• Rimuovi: rimuovi un insieme di scorciatoie dinamiche utilizzando removeDynamicShortcuts(). Rimuovi tutte le scorciatoie dinamiche che utilizzano removeAllDynamicShortcuts().

Per ulteriori informazioni sull'esecuzione delle operazioni sulle scorciatoie, consulta Gestire le scorciatoie e il riferimento ShortcutManagerCompat.

Ecco un esempio di creazione di una scorciatoia dinamica e di associazione alla tua 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)

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);

Aggiungere la libreria di integrazione di Scorciatoie Google

La libreria di integrazione delle scorciatoie Google è una libreria Jetpack facoltativa. Consente di eseguire il push di scorciatoie dinamiche che possono essere visualizzate sulle piattaforme Android, come Avvio app e sulle piattaforme Google come l'assistente. Questa libreria consente agli utenti di scoprire le scorciatoie per accedere rapidamente a contenuti specifici o riprodurre azioni di riproduzione nella tua app.

Ad esempio, un'app di messaggistica potrebbe eseguire il push di una scorciatoia dinamica per un contatto di nome "Alex" dopo che un utente ha inviato un messaggio a quella persona. Dopo aver inviato la scorciatoia dinamica, se l'utente chiede all'assistente "Hey Google, invia un messaggio ad Alex su ExampleApp", l'assistente può avviare ExampleApp e configurarla automaticamente per inviare un messaggio ad Alex.

Le scorciatoie dinamiche caricate con questa libreria non sono soggette ai limiti relativi alle scorciatoie applicati a livello di dispositivo. In questo modo la tua app può eseguire il push di una scorciatoia ogni volta che un utente completa un'azione associata nella tua app. L'invio di scorciatoie frequenti in questo modo consente a Google di comprendere i modelli di utilizzo dell'utente e di suggerire scorciatoie pertinenti al contesto.

Ad esempio, l'assistente può apprendere dalle scorciatoie inviate dalla tua app di monitoraggio dell'attività fisica che generalmente un utente esegue ogni mattina e suggerire in modo proattivo una scorciatoia per "avviare una corsa" quando l'utente solleva il telefono la mattina.

La libreria di integrazione delle scorciatoie di Google non offre funzionalità indirizzabili. L'aggiunta di questa libreria alla tua app consente alle piattaforme Google di acquisire le scorciatoie inviate dall'app utilizzando ShortcutManagerCompat.

Per utilizzare questa raccolta nella tua app, svolgi i seguenti passaggi:

1. Aggiorna il file gradle.properties in modo che supporti le librerie AndroidX:

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

2. In app/build.gradle, aggiungi le dipendenze per la libreria di integrazione Scorciatoie Google e ShortcutManagerCompat:

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

Dopo aver aggiunto le dipendenze della libreria al progetto Android, la tua app può utilizzare il metodo pushDynamicShortcut() di ShortcutManagerCompat per inviare scorciatoie dinamiche idonee per la visualizzazione in Avvio app e sulle piattaforme Google partecipanti.

Creare scorciatoie bloccate

Su Android 8.0 (livello API 26) e versioni successive, puoi creare scorciatoie bloccate. Diversamente dalle scorciatoie statiche e dinamiche, le scorciatoie bloccate vengono visualizzate in Avvio applicazioni supportate come icone separate. La Figura 1 mostra la distinzione tra questi due tipi di scorciatoie.

Per bloccare una scorciatoia a un'Avvio app supportato utilizzando la tua app, svolgi i seguenti passaggi:

1. Utilizza isRequestPinShortcutSupported() per verificare che l'Avvio app predefinito del dispositivo supporti il blocco delle scorciatoie in-app.

2. Crea un oggetto ShortcutInfo in uno dei due modi seguenti, a seconda dell'esistenza o meno della scorciatoia:

   1. Se la scorciatoia esiste, crea un oggetto ShortcutInfo che contiene solo l'ID della scorciatoia esistente. Il sistema trova e blocca automaticamente tutte le altre informazioni relative alla scorciatoia.
   2. Se stai bloccando una nuova scorciatoia, crea un oggetto ShortcutInfo che contenga un ID, un intent e una breve etichetta per la nuova scorciatoia.

3. Fissa la scorciatoia ad Avvio app del dispositivo chiamando il numero requestPinShortcut(). Durante questa operazione, puoi trasmettere un oggetto PendingIntent, che avvisa la tua app solo quando la scorciatoia viene bloccata correttamente.

   Dopo che una scorciatoia è bloccata, l'app può aggiornarne i contenuti utilizzando il metodo updateShortcuts(). Per maggiori informazioni, consulta la pagina Aggiornare le scorciatoie.

Lo snippet di codice riportato di seguito mostra come creare una scorciatoia bloccata.

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());
}

Crea un'attività di scorciatoia personalizzata

Puoi anche creare un'attività specializzata che aiuti gli utenti a creare scorciatoie, complete di opzioni personalizzate e un pulsante di conferma. La figura 2 mostra un esempio di questo tipo di attività nell'app Gmail.

Nel file manifest dell'app, aggiungi ACTION_CREATE_SHORTCUT all'elemento <intent-filter> dell'attività. Questa dichiarazione configura il seguente comportamento quando l'utente tenta di creare una scorciatoia:

1. Il sistema avvia l'attività specializzata della tua app.
2. L'utente imposta le opzioni per la scorciatoia.
3. L'utente seleziona il pulsante di conferma.
4. L'app crea la scorciatoia utilizzando il metodo createShortcutResultIntent(). Questo metodo restituisce un valore Intent, che l'app rimanda all'attività precedentemente eseguita utilizzando setResult().
5. L'app chiama finish() sull'attività utilizzata per creare la scorciatoia personalizzata.

Analogamente, l'app può chiedere agli utenti di aggiungere scorciatoie bloccate alla schermata Home dopo l'installazione o al primo avvio. Questo metodo è efficace perché consente agli utenti di creare una scorciatoia nell'ambito del loro normale flusso di lavoro.

Test delle scorciatoie

Per testare le scorciatoie dell'app, installa l'app su un dispositivo con Avvio app che supporta le scorciatoie. Quindi, esegui le seguenti azioni:

• Tocca e tieni premuta l'icona in Avvio applicazioni dell'app per visualizzare le scorciatoie definite per l'app.
• Trascina una scorciatoia per bloccarla in Avvio app del dispositivo.