Gestisci le scorciatoie

Dopo aver creato le scorciatoie, potrebbe essere necessario gestirle per l'intera durata dell'app. Ad esempio, potresti voler ottimizzare l'app determinando la frequenza con cui gli utenti completano azioni specifiche con le scorciatoie. In un altro caso, potresti decidere di disattivare una scorciatoia bloccata per impedire all'app di eseguire azioni obsolete o mancanti. Per quanto riguarda le scorciatoie a cui viene fatto riferimento nelle conversazioni, ti consigliamo di monitorare l'utilizzo per fornire indicatori che migliorino il ranking delle scorciatoie.

In questa pagina vengono descritti questi e diversi altri modi comuni per gestire le scorciatoie.

Comportamento della scorciatoia

Le seguenti sezioni contengono informazioni generali sul comportamento delle scorciatoie, inclusi visibilità, ordine di visualizzazione e ranking.

Visibilità scorciatoia

Le scorciatoie statiche e dinamiche vengono visualizzate in Avvio app o in assistente supportato quando l'utente esegue un gesto o un comando vocale specifico. Nelle app Avvio app supportate, il gesto è tocco e pressione sull'icona in Avvio applicazioni dell'app, ma il gesto potrebbe essere diverso in altre app Avvio app. Con l'Assistente Google, le scorciatoie possono essere visualizzate all'interno dell'assistente o avviate da un comando vocale dell'utente.

Il corso LauncherApps fornisce API che consentono alle app Avvio app di accedere alle scorciatoie.

Poiché le scorciatoie bloccate vengono visualizzate in Avvio app, sono sempre visibili. Una scorciatoia bloccata viene rimossa da Avvio app solo nelle seguenti situazioni:

  • L'utente lo rimuove.
  • L'app associata alla scorciatoia è stata disinstallata.
  • L'utente cancella i dati di un'app andando a Impostazioni > App e notifiche, selezionando l'app, quindi toccando Spazio di archiviazione > Cancella spazio di archiviazione.

I target di condivisione sono un sottoinsieme di scorciatoie dinamiche che vengono visualizzate nella riga della condivisione diretta del foglio di condivisione di Android.

Uno screenshot di Android Sharesheet
Figura 1. Android Sharesheet. I target della condivisione diretta vengono visualizzati nella prima riga, seguiti dalle app classificate e poi dagli elenchi di app.

Ordine di visualizzazione delle scorciatoie

Quando in Avvio app vengono visualizzate le scorciatoie di un'app, queste devono apparire nel seguente ordine:

  1. Scorciatoie statiche: scorciatoie il cui metodo isDeclaredInManifest() restituisce true.
  2. Scorciatoie dinamiche: scorciatoie il cui metodo ShortcutInfo.isDynamic() restituisce true.

All'interno di ogni tipo di scorciatoia, statica e dinamica, le scorciatoie sono ordinate in base all'aumento del ranking in base a ShortcutInfo.getRank. L'Assistente Google prende in considerazione anche il ranking delle scorciatoie quando stabilisce le scorciatoie contestuali da mostrare agli utenti.

I ranking sono numeri interi sequenziali non negativi. Le scorciatoie statiche vengono classificate dalla prima all'ultima nell'ordine in cui appaiono nel file shortcuts.xml. Per le scorciatoie dinamiche, puoi aggiornare i ranking delle scorciatoie esistenti quando chiami updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat) o setDynamicShortcuts(Context, List).

L'ordine dei target di condivisione si basa su vari fattori, tra cui cronologia utente passata, recency, frequenza, suggerimento per il ranking, utilizzo delle app e priorità impostata nella conversazione associata a una scorciatoia di condivisione. I target di condivisione creati utilizzando l'API Sharing Scorciatoias hanno la priorità sui target di condivisione creati dalla ChooserTargetService che è stata ritirata in Android 11. In Android 12 e versioni successive, i target di condivisione generati dal ChooserTargetService deprecato non verranno più visualizzati nel foglio di condivisione.

La maggior parte delle app Avvio app mostra un massimo di quattro scorciatoie. Per qualsiasi combinazione di scorciatoie statiche e dinamiche definite, Avvio app visualizza un massimo di due scorciatoie statiche e due scorciatoie dinamiche. Ad esempio, se definisci quattro scorciatoie statiche e crei in modo programmatico tre scorciatoie dinamiche, in Avvio app vengono visualizzate le prime due scorciatoie statiche e le due scorciatoie dinamiche con il ranking più elevato.

Gestisci più intent e attività

Se vuoi che l'app esegua più operazioni quando l'utente attiva una scorciatoia, puoi configurarla in modo che attivi attività successive. Puoi risolvere questo problema assegnando più intent, avviando un'attività da un altro o impostando flag di intent, a seconda del tipo di scorciatoia.

Assegna più intent

Quando crei una scorciatoia con ShortcutInfoCompat.Builder, puoi utilizzare setIntents() anziché setIntent(). Se chiami setIntents(), puoi avviare più attività all'interno dell'app quando l'utente seleziona una scorciatoia, posizionando tutte le attività nell'elenco tranne l'ultima nell'elenco posteriore. Se poi l'utente tocca il pulsante Indietro del dispositivo, vedrà un'altra attività nell'app anziché tornare ad Avvio app del dispositivo.

Avviare un'attività da un'altra

Le scorciatoie statiche non possono avere flag personalizzati per intent. Il primo intent di una scorciatoia statica ha sempre i valori Intent.FLAG_ACTIVITY_NEW_TASK e Intent.FLAG_ACTIVITY_CLEAR_TASK imposta. Ciò significa che quando la tua app è in esecuzione, tutte le attività esistenti nell'app vengono eliminate quando viene avviata una scorciatoia statica. Se preferisci non seguire questo tipo di comportamento, puoi utilizzare un'attività trampolino, ossia un'attività invisibile che avvia un'altra attività, in Activity.onCreate(Bundle) che chiama Activity.finish():

  1. Nel file AndroidManifest.xml, includi l'assegnazione dell'attributo android:taskAffinity="" nell'attività trampolino.
  2. Nel file delle risorse delle scorciatoie, fai riferimento all'attività trampolino nell'intent all'interno della scorciatoia statica.

Per ulteriori informazioni sulle attività di trampolino, consulta la sezione Avviare un'attività da un'altra.

Imposta flag intent

Puoi pubblicare scorciatoie dinamiche con qualsiasi insieme di flag Intent. Preferibilmente, specifica Intent.FLAG_ACTIVITY_CLEAR_TASK insieme agli altri flag. In caso contrario, se tenti di avviare un'altra attività mentre la tua app è in esecuzione, l'attività target potrebbe non essere visualizzata.

Per scoprire di più sulle attività e sui flag di intent, consulta Attività e back stack.

Aggiorna scorciatoie

L'icona in Avvio applicazioni di ogni app può contenere al massimo una serie di scorciatoie statiche e dinamiche combinate per un valore pari al valore restituito da getMaxShortcutCountPerActivity. Non c'è limite al numero di scorciatoie bloccate che un'app può creare.

Quando una scorciatoia dinamica viene bloccata, anche se il publisher la rimuove come scorciatoia dinamica, rimane visibile e avviabile. Questo consente a un'app di avere più di getMaxShortcutCountPerActivity() di scorciatoie.

Considera l'esempio seguente, che presuppone che il valore restituito da getMaxShortcutCountPerActivity() sia 4:

  1. Un'app di chat pubblica quattro scorciatoie dinamiche, che rappresentano le quattro conversazioni più recenti: c1, c2, c3 e c4.
  2. L'utente blocca tutte e quattro le scorciatoie.
  3. Successivamente, l'utente avvia altre tre conversazioni: c5, c6 e c7. L'app del publisher ripubblica le scorciatoie dinamiche. Il nuovo elenco di scorciatoie dinamiche è c4, c5, c6 e c7.

L'app deve rimuovere c1, c2 e c3 perché non può visualizzare più di quattro scorciatoie dinamiche. Tuttavia, c1, c2 e c3 sono ancora scorciatoie bloccate a cui l'utente può accedere e avviare.

L'utente può quindi accedere a un totale di sette scorciatoie che rimandano alle attività nell'app dell'editore. Questo perché il totale include il numero massimo di scorciatoie e le tre scorciatoie bloccate.

  1. L'app può utilizzare updateShortcuts(Context, List) per aggiornare una qualsiasi delle sette scorciatoie esistenti. Ad esempio, puoi aggiornare questo insieme di scorciatoie quando le icone delle app peer nella chat cambiano.
  2. Puoi utilizzare i metodi addDynamicShortcuts(Context, List) e setDynamicShortcuts(Context, List) per aggiornare le scorciatoie esistenti con gli stessi ID. Non puoi però utilizzarli per aggiornare le scorciatoie non dinamiche e bloccate, perché questi due metodi tentano di convertire gli elenchi di scorciatoie indicati in scorciatoie dinamiche.

Non esiste un limite al numero di scorciatoie che è possibile inviare tramite push per la visualizzazione nelle app dell'assistente come l'Assistente Google. Usa il metodo pushDynamicShortcut() della libreria Jetpack ShortcutManagerCompat per creare e aggiornare le scorciatoie da utilizzare nelle app dell'assistente. Inoltre, aggiungi la libreria di integrazione delle scorciatoie Google alla tua app per rendere i link dinamici idonei alla visualizzazione nell'Assistente Google.

Per scoprire di più sulle linee guida per le scorciatoie delle applicazioni, incluso l'aggiornamento delle scorciatoie, consulta le best practice per le scorciatoie.

Gestire le modifiche alle impostazioni internazionali del sistema

Le app devono aggiornare le scorciatoie dinamiche e fissate quando ricevono la trasmissione Intent.ACTION_LOCALE_CHANGED che indica una modifica alla lingua del sistema.

Monitorare l'utilizzo delle scorciatoie

Per determinare le situazioni in cui vengono visualizzate le scorciatoie statiche e dinamiche, Avvio app esamina la cronologia di attivazione delle scorciatoie. Per le scorciatoie statiche, puoi tenere traccia di quando gli utenti completano azioni specifiche nella tua app chiamando il metodo reportShortcutUsed() e trasmettendolo l'ID di una scorciatoia quando si verifica uno dei seguenti eventi:

  • L'utente seleziona la scorciatoia con l'ID specificato.
  • All'interno dell'app, l'utente completa manualmente l'azione corrispondente alla stessa scorciatoia.

L'app monitora l'utilizzo delle scorciatoie dinamiche chiamando il metodo pushDynamicShortcut() e trasmettendolo l'ID della scorciatoia quando si verifica un evento pertinente. Se applichi questo metodo, le app di assistenza come l'Assistente Google possono suggerire scorciatoie pertinenti agli utenti. Poiché il metodo pushDynamicShortcut() segnala l'utilizzo quando viene chiamato, non chiamare il metodo reportShortcutUsed() per le stesse scorciatoie.

Per le scorciatoie relative alle conversazioni, è importante monitorare l'utilizzo dei messaggi in uscita e in arrivo. Per informazioni dettagliate, consulta le best practice relative alle persone e alle conversazioni.

Disattiva scorciatoie

Poiché la tua app e i suoi utenti possono bloccare le scorciatoie ad Avvio app del dispositivo, è possibile che queste scorciatoie bloccate possano indirizzare gli utenti ad azioni nella tua app che non sono aggiornate o che non esistono più. Per gestire questa situazione, puoi disattivare le scorciatoie che non vuoi che gli utenti selezionino chiamando disableShortcuts. Questa azione rimuove le scorciatoie specificate dall'elenco delle scorciatoie statiche e dinamiche e disattiva le copie bloccate di queste scorciatoie. Puoi anche utilizzare una versione sovraccaricata di questo metodo che accetta un CharSequence come messaggio di errore personalizzato. Il messaggio di errore viene visualizzato quando gli utenti tentano di avviare una scorciatoia disattivata.

Limitazione di frequenza

Quando utilizzi i metodi setDynamicShortcuts(), addDynamicShortcuts() o updateShortcuts(), potresti riuscire a chiamare questi metodi solo un numero specifico di volte in un'app in background, ovvero senza attività o servizi in primo piano. Il limite al numero specifico di volte in cui puoi chiamare questi metodi è chiamato limitazione di frequenza. Questa funzionalità impedisce a ShortcutManagerCompat di consumare un numero eccessivo di risorse del dispositivo.

Quando la limitazione di frequenza è attiva, isRateLimitingActive() restituisce true. Tuttavia, la limitazione di frequenza viene reimpostata durante determinati eventi, quindi anche le app in background possono chiamare i metodi ShortcutManager fino a quando il limite di frequenza non viene raggiunto di nuovo. Questi eventi includono:

  • Un'app viene in primo piano.
  • Le impostazioni internazionali di sistema vengono modificate.
  • L'utente esegue l'azione di risposta incorporata su una notifica.

Se riscontri un limite di frequenza durante lo sviluppo o il test, puoi selezionare Opzioni sviluppatore > Reimposta limite di frequenza di ScorciatoiaManager dalle impostazioni del dispositivo oppure puoi inserire il seguente comando in adb:

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

Backup e ripristino

Puoi consentire agli utenti di eseguire operazioni di backup e ripristino sulla tua app quando cambiano dispositivo includendo l'assegnazione dell'attributo android:allowBackup="true" nel file manifest dell'app. Se supporti il backup e ripristino, tieni presente i seguenti punti sulle scorciatoie app:

  • Le scorciatoie statiche vengono ripubblicate automaticamente, ma solo dopo che l'utente reinstalla l'app su un nuovo dispositivo.
  • Non viene eseguito il backup delle scorciatoie dinamiche, quindi includi la logica nell'app per ripubblicarle quando un utente apre la tua app su un nuovo dispositivo.
  • Le scorciatoie bloccate vengono ripristinate automaticamente in Avvio app del dispositivo, ma il sistema non esegue il backup delle icone associate alle scorciatoie bloccate. Pertanto, salva le immagini delle scorciatoie bloccate nell'app, in modo che sia facile ripristinarle su un nuovo dispositivo.

Il seguente snippet di codice mostra il modo migliore per ripristinare le scorciatoie dinamiche dell'app e come verificare se le scorciatoie bloccate dell'app sono state mantenute:

Kotlin

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}

Java

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}