Creare scorciatoie

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

La modalità di pubblicazione dei 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, la tua app determina il contesto in entrambi i casi. Nei casi in cui un utente sceglie in che modo la tua app fornisce i contenuti, ad esempio con una scorciatoia bloccata, il contesto è definito dall'utente. Gli scenari seguenti descrivono alcuni casi d'uso per ciascun tipo di scorciatoia:

• Le scorciatoie statiche sono ideali per le app che collegano i contenuti utilizzando una struttura coerente per tutta la durata dell'interazione di un utente con l'app. Poiché la maggior parte dei launcher mostra solo quattro scorciatoie alla volta, le scorciatoie statiche sono utili per eseguire un'attività di routine in modo coerente, ad esempio se l'utente vuole visualizzare il calendario o la posta elettronica 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 che gli utenti eseguono in un'app. Ad esempio, se crei un gioco che consente all'utente di iniziare dal livello corrente all'avvio, devi aggiornare frequentemente la scorciatoia. L'utilizzo di una scorciatoia dinamica ti consente di aggiornarla ogni volta che l'utente supera un livello.
• Le scorciatoie bloccate vengono utilizzate per azioni specifiche guidate dall'utente. Ad esempio, un utente potrebbe voler bloccare un sito web specifico nel launcher. Questo è utile perché consente all'utente di eseguire un'azione personalizzata, ad esempio navigare sul sito web in un solo passaggio, più rapidamente rispetto all'utilizzo di un'istanza predefinita di un browser.

Creare scorciatoie statiche

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

Per creare una scorciatoia statica:

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

2. Aggiungi a questa attività un elemento <meta-data> che fa riferimento al file di 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 radice <shortcuts> che contenga un elenco di elementi <shortcut>. In ogni elemento <shortcut>, includi informazioni su una scorciatoia statica, tra cui l'icona, le etichette di 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.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>
   

Personalizzare i valori degli attributi

L'elenco seguente include le descrizioni dei diversi attributi all'interno di 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.

android:shortcutShortLabel

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

Per saperne di più, consulta setShortLabel().

android:shortcutLongLabel

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

Per saperne di più, consulta setLongLabel().

android:shortcutDisabledMessage

Il messaggio visualizzato in un launcher supportato quando l'utente tenta di avviare una scorciatoia disattivata. Il messaggio deve spiegare all'utente il motivo per cui la scorciatoia è disattivata. Il valore di questo attributo non ha effetto se android:enabled è true.

android:enabled

Determina se l'utente può interagire con la scorciatoia da un launcher supportato. Il valore predefinito di android:enabled è true. Se lo imposti su false, imposta un android:shortcutDisabledMessage che spieghi perché stai disattivando la scorciatoia. Se ritieni di non dover fornire un messaggio di questo tipo, rimuovi completamente la scorciatoia dal file XML.

android:icon

L'icona bitmap o icona adattiva utilizzata dall'Avvio app quando mostra la scorciatoia all'utente. Questo valore può essere il percorso di un'immagine o il file di risorse che contiene l'immagine. Utilizza le icone adattive ogni volta che è possibile per migliorare il rendimento e la coerenza.

Configurare 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 avviata dal sistema 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. Per maggiori dettagli, consulta Gestire più intent e attività, Impostare un intent e il riferimento alla classe TaskStackBuilder.

categories

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

Per un elenco delle categorie di scorciatoie supportate, consulta il riferimento alla 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 di Azioni app. Questo binding di intent 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 e sensibili al contesto all'interno della tua app. Queste azioni possono cambiare tra un utilizzo e l'altro dell'app e durante l'esecuzione dell'app. I buoni utilizzi delle scorciatoie dinamiche includono chiamare una persona specifica, raggiungere una posizione specifica e caricare un gioco dall'ultimo punto di salvataggio dell'utente. Puoi anche utilizzare le scorciatoie dinamiche per aprire una conversazione.

La libreria Jetpack ShortcutManagerCompat è un helper per l'API ShortcutManager, che ti consente di gestire le scorciatoie dinamiche nella tua app. L'utilizzo della libreria ShortcutManagerCompat riduce il codice boilerplate e contribuisce a garantire che le scorciatoie funzionino in modo coerente nelle varie versioni di Android. Questa libreria è necessaria anche per il push delle scorciatoie dinamiche, in modo che siano idonee a essere visualizzate sulle piattaforme Google, come l'assistente, con la libreria Google Shortcuts Integration.

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

• Push e aggiornamento:utilizza pushDynamicShortcut() per pubblicare e aggiornare le tue scorciatoie dinamiche. Se esistono già scorciatoie dinamiche o fisse con lo stesso ID, ogni scorciatoia modificabile viene aggiornata.
• Remove:rimuove un insieme di scorciatoie dinamiche utilizzando removeDynamicShortcuts(). Rimuovi tutte le scorciatoie dinamiche utilizzando removeAllDynamicShortcuts().

Per saperne di più sull'esecuzione di operazioni sui tasti di scelta rapida, consulta Gestire le scorciatoie e il riferimento ShortcutManagerCompat.

Ecco un esempio di creazione di una scorciatoia dinamica e della sua associazione all'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)

Aggiungere la libreria Google Shortcuts Integration

La libreria Google Shortcuts Integration è una libreria Jetpack facoltativa. Consente di eseguire il push di scorciatoie dinamiche che possono essere visualizzate su piattaforme Android, come il launcher e le piattaforme Google. L'utilizzo di questa libreria aiuta gli utenti a scoprire le tue scorciatoie per accedere rapidamente a contenuti specifici o riprodurre azioni nella tua app.

Le scorciatoie dinamiche inviate con questa libreria non sono soggette ai limiti delle scorciatoie applicati per dispositivo. In questo modo, la tua app può inviare una scorciatoia ogni volta che un utente completa un'azione associata nella tua app. L'invio frequente di scorciatoie in questo modo consente a Google di comprendere i pattern di utilizzo dell'utente e suggerirgli scorciatoie pertinenti al contesto.

Ad esempio, l'assistente può apprendere dalle scorciatoie inviate dall'app di monitoraggio dell'attività fisica che un utente di solito corre ogni mattina e suggerire in modo proattivo una scorciatoia "Inizia una corsa" quando l'utente prende lo smartphone al mattino.

La libreria di integrazione delle scorciatoie Google non offre alcuna funzionalità indirizzabile. L'aggiunta di questa libreria alla tua app consente alle piattaforme Google di utilizzare le scorciatoie che la tua app invia utilizzando ShortcutManagerCompat.

Per utilizzare questa libreria nella tua app:

1. Aggiorna il file gradle.properties per supportare 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 delle scorciatoie Google e ShortcutManagerCompat:

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

Con le dipendenze della libreria aggiunte al progetto Android, la tua app può utilizzare il metodo pushDynamicShortcut() di ShortcutManagerCompat per eseguire il push di scorciatoie dinamiche idonee per la visualizzazione nel launcher e nelle piattaforme Google partecipanti.

Creare scorciatoie fissate

Su Android 8.0 (livello API 26) e versioni successive, puoi creare scorciatoie bloccate. A differenza delle scorciatoie statiche e dinamiche, le scorciatoie bloccate vengono visualizzate nei launcher supportati come icone separate. La Figura 1 mostra la distinzione tra questi due tipi di scorciatoie.

Per bloccare una scorciatoia in un launcher supportato utilizzando la tua app, completa i seguenti passaggi:

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

2. Crea un oggetto ShortcutInfo in uno dei due modi seguenti, a seconda che la scorciatoia esista:

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

3. Blocca la scorciatoia nell'Avvio app del dispositivo chiamando requestPinShortcut(). Durante questa procedura, puoi passare un oggetto PendingIntent, che invia una notifica alla tua app solo quando la scorciatoia viene bloccata correttamente.

   Una volta bloccata una scorciatoia, l'app può aggiornarne i contenuti utilizzando il metodo updateShortcuts(). Per ulteriori informazioni, leggi Aggiornare le scorciatoie.

Il seguente snippet di codice mostra come creare una scorciatoia bloccata.

val shortcutManager = getSystemService<ShortcutManager>()

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

Creare un'attività di scorciatoia personalizzata

Puoi anche creare un'attività specializzata che aiuti gli utenti a creare scorciatoie, completa 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 dell'app.
2. L'utente imposta le opzioni per la scorciatoia.
3. L'utente seleziona il pulsante di conferma.
4. La tua app crea la scorciatoia utilizzando il metodo createShortcutResultIntent(). Questo metodo restituisce un Intent, che la tua app ritrasmette all'attività eseguita in precedenza utilizzando setResult().
5. Le chiamate dell'app finish() sull'attività utilizzata per creare la scorciatoia personalizzata.

Allo stesso modo, la tua app può chiedere agli utenti di aggiungere scorciatoie bloccate alla schermata Home dopo l'installazione o al primo avvio dell'app. Questo metodo è efficace perché aiuta gli utenti a creare una scorciatoia nell'ambito del loro flusso di lavoro ordinario.

Scorciatoie di test

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

• Tocca e tieni premuta l'icona in Avvio applicazioni della tua app per visualizzare le scorciatoie che definisci per l'app.
• Trascina una scorciatoia per bloccarla nell'Avvio app del dispositivo.