Creare le 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. Sebbene il contesto di una scorciatoia statica non cambi e quello di una scorciatoia dinamica cambi costantemente, l'app gestisce il contesto in entrambi i casi. Nei casi in cui un utente sceglie in che modo la tua app gli fornisce i contenuti, ad esempio con una scorciatoia bloccata, il contesto è 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 rimandano ai contenuti utilizzando una struttura coerente per tutta la durata dell'interazione dell'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 l'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 livello corrente al momento del lancio, devi aggiornare spesso 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 avviate dall'utente. Ad esempio, un utente potrebbe voler bloccare un sito web specifico in Avvio app. Questo è utile perché consente all'utente di eseguire un'azione personalizzata, come accedere al 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 dell'app e queste azioni devono rimanere coerenti per tutta la durata della versione corrente dell'app. Alcune buone opzioni per 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 della tua 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 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 root <shortcuts> che contiene un elenco di elementi <shortcut>. In ogni elemento <shortcut>, includi informazioni su una scorciatoia statica, tra cui l'icona, le eticintent e le etichette di descrizione, nonché 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>
   shortcuts.xml

Personalizza i valori degli attributi personalizzati

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

Una stringa letterale che rappresenta la scorciatoia quando un oggetto ShortcutManager esegue operazioni su di essa.

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, Avvio app visualizza questo valore anziché android:shortcutShortLabel. Se possibile, limita questa descrizione lunga a 25 caratteri.

Per saperne di più, consulta setLongLabel().

android:shortcutDisabledMessage

Il messaggio che viene 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 avviatore supportato. Il valore predefinito di android:enabled è true. Se la imposti su false, imposta un android:shortcutDisabledMessage che spieghi il motivo per cui disattivi la scorciatoia. Se ritieni di non dover fornire un messaggio di questo tipo, rimuovi completamente la scorciatoia dal file XML.

android:icon

La bitmap o l'icona adattiva utilizzata dal programma di avvio quando mostra la scorciatoia all'utente. Questo valore può essere il percorso di un'immagine o del file di risorse che contiene l'immagine. Utilizza le icone adattive ogni volta che è possibile per migliorare le prestazioni e la 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. Per maggiori dettagli, consulta Gestisci più intent e attività, Imposta 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 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. Questa associazione di funzionalità consente agli utenti di utilizzare i comandi vocali con l'Assistente Google per richiamare una scorciatoia.

Crea scorciatoie dinamiche

Le scorciatoie dinamiche forniscono link ad azioni specifiche sensibili al contesto all'interno della tua app. Queste azioni possono cambiare tra un utilizzo e l'altro dell'app e mentre l'app è in esecuzione. I casi d'uso più comuni 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 trasferire le scorciatoie dinamiche in modo che siano idonee per la visualizzazione 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 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 utilizzando removeAllDynamicShortcuts().

Per saperne di più sull'esecuzione di operazioni sulle scorciatoie, consulta Gestisci 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)
ShortcutsSnippets.kt

Aggiungi la libreria Google Shortcuts Integration

La libreria Google Shortcuts Integration è una libreria Jetpack facoltativa. Ti consente di inviare scorciatoie dinamiche che possono essere visualizzate sulle piattaforme Android, come il programma di avvio delle app, e sulle piattaforme Google. L'utilizzo di questa libreria aiuta gli utenti a scoprire le tue scorciatoie per accedere rapidamente a contenuti specifici o ripetere azioni nella tua app.

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

Ad esempio, l'assistente può apprendere dalle scorciatoie inviate dalla tua app di monitoraggio dell'attività fisica che un utente in genere 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 di Google non offre alcuna funzionalità indirizzabile. L'aggiunta di questa libreria alla tua app consente alle piattaforme Google di acquisire le scorciatoie che la tua app invia tramite ShortcutManagerCompat.

Per utilizzare questa libreria nella tua app, aggiungi le dipendenze per la libreria di integrazione delle scorciatoie di Google e ShortcutManagerCompat al file app/build.gradle o app/build.gradle.kts:

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

Dopo aver aggiunto le dipendenze della libreria al tuo progetto Android, la tua app può utilizzare il metodo pushDynamicShortcut() di ShortcutManagerCompat per eseguire il push delle scorciatoie dinamiche idonee per la visualizzazione nell'Avvio app e nelle piattaforme Google partecipanti.

Crea scorciatoie bloccate

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 programma di avvio supportato utilizzando la tua app, completa i seguenti passaggi:

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

2. Crea un oggetto ShortcutInfoCompat che contiene un ID, un intent e un'etichetta breve per la scorciatoia. Se la scorciatoia esiste, utilizza l'ID della scorciatoia esistente. Il sistema trova e fissa automaticamente tutte le altre informazioni relative alla scorciatoia.

3. Fissa 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.

   Dopo aver bloccato una scorciatoia, la tua app può aggiornarne i contenuti utilizzando il metodo updateShortcuts(). Per saperne di più, consulta Aggiorna le scorciatoie.

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

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

Crea 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 della tua 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 l'app trasmette all'attività precedentemente in esecuzione utilizzando setResult().
5. La tua app chiama finish() nell'attività utilizzata per creare la scorciatoia personalizzata.

Analogamente, 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 per i test

Per testare le scorciatoie della tua app, installala su un dispositivo con un Avvio app che supporta le scorciatoie. Quindi, esegui queste azioni:

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