Creare scorciatoie

Le scorciatoie forniscono tipi specifici di contenuti agli utenti perché li aiutano ad accedere rapidamente a parti della tua app.

Un'immagine che mostra il contrasto tra le scorciatoie app e le scorciatoie bloccate
Figura 1. Scorciatoie app e scorciatoie bloccate.

Le modalità di pubblicazione dei contenuti con le scorciatoie dipendono 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 il contesto di una scorciatoia dinamica cambia costantemente, la tua app orienta il contesto in entrambi i casi. Nei casi in cui un utente scelga il modo in cui la tua app invia 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 si collegano ai contenuti utilizzando una struttura coerente per tutta la durata dell'interazione dell'utente con l'app. Poiché la maggior parte delle app Avvio app 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 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 per le azioni eseguite dagli utenti in un'app. Ad esempio, se crei un gioco che consente all'utente di iniziare dal livello attuale all'avvio, devi aggiornare spesso la scorciatoia. Una scorciatoia dinamica ti consente di aggiornarla ogni volta che l'utente cancella un livello.
  • Le scorciatoie bloccate vengono utilizzate per azioni specifiche guidate dagli utenti. Ad esempio, un utente potrebbe voler bloccare un sito web specifico in Avvio app. Ciò è utile perché consente all'utente di eseguire un'azione personalizzata, come 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 dell'app e queste azioni devono rimanere coerenti per tutta la durata della versione corrente dell'app. Le 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 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 delle risorse, aggiungi un elemento principale <shortcuts> che contiene un elenco di elementi <shortcut>. In ogni elemento <shortcut>, includi informazioni su una scorciatoia statica, tra cui la relativa icona, le etichette descrittive 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 di 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 questa descrizione breve a 10 caratteri.

Per maggiori informazioni, vedi setShortLabel().

android:shortcutLongLabel

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

Per maggiori informazioni, vedi 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 è 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'Avvio app supportato. Il valore predefinito di android:enabled è true. Se lo imposti su false, imposta un valore android:shortcutDisabledMessage che spiega perché stai disattivando la scorciatoia. Se non ritieni di dover fornire questo messaggio, rimuovi completamente la scorciatoia dal file XML.

android:icon

L'icona bitmap o adattiva utilizzata da 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. Quando 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. Per informazioni dettagliate, consulta Gestire più intent e attività, Impostare un intent e le informazioni di riferimento della 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 la pagina di 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 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 tra l'utilizzo dell'app e l'esecuzione dell'app. Le scorciatoie dinamiche sono ideali per chiamare una persona specifica, per raggiungere una località specifica e per 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 per ShortcutManager l'API, che ti consente di gestire le scorciatoie dinamiche nell'app. L'utilizzo della libreria ShortcutManagerCompat riduce il codice boilerplate e contribuisce a garantire il funzionamento coerente delle scorciatoie su tutte le versioni di Android. Questa libreria è necessaria anche per il push di scorciatoie dinamiche in modo che siano idonee a essere visualizzate 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 aggiorna: usa 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 che utilizzano removeDynamicShortcuts(). Rimuovi tutte le scorciatoie dinamiche che utilizzano removeAllDynamicShortcuts().

Per ulteriori informazioni sull'esecuzione delle operazioni sulle scorciatoie, consulta Gestione delle scorciatoie e ShortcutManagerCompat.

Ecco un esempio di creazione di una scorciatoia dinamica e relativa associazione alla tua app:

Kotlin


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)

Java


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 delle scorciatoie Google

La libreria di integrazione delle scorciatoie Google è una libreria Jetpack facoltativa. Ti consente di eseguire il push di scorciatoie dinamiche che possono essere visualizzate sulle piattaforme Android, ad esempio Avvio app e sulle piattaforme Google come l'assistente. L'uso di questa libreria aiuta gli utenti a scoprire le tue scorciatoie per accedere rapidamente a contenuti specifici o ad azioni di riproduzione nella tua app.

Ad esempio, un'app di messaggistica potrebbe eseguire il push di una scorciatoia dinamica per un contatto chiamato "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 trasferite con questa libreria non sono soggette ai limiti relativi alle scorciatoie applicati in base al dispositivo. Ciò consente all'app di 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ò imparare dalle scorciatoie inviate dalla tua app di monitoraggio dell'attività fisica che un utente in genere esegue ogni mattina e suggerire proattivamente una scorciatoia per iniziare una corsa quando l'utente prende il telefono la mattina.

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

Per utilizzare questa raccolta nella tua app, segui questi passaggi:

  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 dipendenze per la libreria di integrazione Scorciatoie di 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 alla visualizzazione in Avvio app e sulle 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 programmi di avvio supportati 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, procedi nel seguente modo:

  1. Utilizza isRequestPinShortcutSupported() per verificare che l'Avvio app predefinito del dispositivo supporti il blocco in-app delle scorciatoie.
  2. Crea un oggetto ShortcutInfo in uno dei due seguenti modi, a seconda dell'esistenza o meno della scorciatoia:

    1. Se la scorciatoia esiste, crea un oggetto ShortcutInfo contenente 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 requestPinShortcut(). Durante questo processo, puoi trasferire 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 maggiori informazioni, consulta la pagina Aggiornare le scorciatoie.

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

Kotlin

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

Java

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

Un&#39;immagine che mostra l&#39;attività delle finestre di dialogo personalizzate con il messaggio &quot;Vuoi aggiungere l&#39;icona di Avvio applicazioni di Gmail alla tua schermata Home?&quot; Le opzioni personalizzate sono &quot;No, grazie&quot; e &quot;Aggiungi icona&quot;.
Figura 2. Esempio di attività della finestra di dialogo di scorciatoie app personalizzate.

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 della tua 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 Intent, che l'app rimanda all'attività precedentemente in esecuzione utilizzando setResult().
  5. L'app chiama finish() dell'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 dell'app. Questo metodo è efficace perché aiuta gli utenti a creare una scorciatoia nell'ambito del loro normale flusso di lavoro.

Testa le scorciatoie

Per testare le scorciatoie della tua 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 che definisci per l'app.
  • Trascina una scorciatoia per fissarla in Avvio applicazioni del dispositivo.