Gestisci le scorciatoie

Dopo aver creato le scorciatoie, potrebbe essere necessario gestirle durante il ciclo di vita della tua app. Ad esempio, potresti voler ottimizzare la tua 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 alla tua app di eseguire azioni obsolete o mancanti. Per le scorciatoie a cui viene fatto riferimento nelle conversazioni, ti consigliamo di monitorare l'utilizzo per fornire indicatori che migliorino il ranking delle scorciatoie.

Questa pagina descrive questi e molti altri modi comuni per gestire le scorciatoie.

Comportamento delle scorciatoie

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

Visibilità delle scorciatoie

Le scorciatoie statiche e dinamiche vengono visualizzate in un launcher o assistente supportato quando l'utente esegue un gesto o un comando vocale specifico. Sui launcher supportati, il gesto consiste nel toccare e tenere premuta l'icona in Avvio applicazioni dell'app, ma potrebbe essere diverso su altre app di avvio. Con l'Assistente Google, le scorciatoie possono essere visualizzate all'interno dell'assistente o avviate da un comando vocale dell'utente.

La classe LauncherApps fornisce API per le app di avvio per accedere alle scorciatoie.

Poiché le scorciatoie bloccate vengono visualizzate nel launcher stesso, sono sempre visibili. Una scorciatoia bloccata viene rimossa dal launcher solo nelle seguenti situazioni:

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

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

Ordine di visualizzazione delle scorciatoie

Quando il launcher mostra le scorciatoie di un'app, queste devono essere visualizzate 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 vengono ordinate in base al rank crescente in base a ShortcutInfo.getRank. L'Assistente Google prende in considerazione anche il ranking delle scorciatoie quando determina le scorciatoie contestuali da mostrare agli utenti.

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

L'ordine delle destinazioni di condivisione si basa su vari fattori, tra cui la cronologia passata degli utenti, la frequenza, la recenza, il suggerimento di ranking, l'utilizzo delle app e la priorità impostata nella conversazione associata a una scorciatoia per la condivisione. I target di condivisione creati utilizzando l'API Sharing Shortcuts hanno la priorità sui target di condivisione prodotti da ChooserTargetService, che è stato ritirato in Android 11. In Android 12 e versioni successive, le destinazioni di condivisione generate da ChooserTargetService deprecato non verranno più visualizzate nel foglio di condivisione.

La maggior parte delle app di avvio mostra un massimo di quattro scorciatoie. Per qualsiasi combinazione di scorciatoie statiche e dinamiche definite, il launcher mostra un massimo di due scorciatoie statiche e due dinamiche. Ad esempio, se definisci quattro scorciatoie statiche e crei tre scorciatoie dinamiche a livello di programmazione, il launcher mostra le prime due scorciatoie statiche e le due scorciatoie dinamiche con il ranking più alto.

Gestire più intent e attività

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

Avviare un'attività da un'altra

Le scorciatoie statiche non possono avere flag personalizzati per intenzione. Il primo intent di una scorciatoia statica ha sempre impostato Intent.FLAG_ACTIVITY_NEW_TASK e Intent.FLAG_ACTIVITY_CLEAR_TASK. Ciò significa che quando la tua app è in esecuzione, tutte le attività esistenti nell'app vengono eliminate all'avvio di una scorciatoia statica. Se non vuoi questo comportamento, puoi utilizzare un'attività trampoline, un'attività invisibile che avvia un'altra attività, chiamando finish all'interno di un blocco di avvio o onCreate prima che venga impostato il contenuto di Compose:

1. In AndroidManifest.xml file, includi l'assegnazione dell'attributo android:taskAffinity="" nell'attività di trampolino.

2. Nel file di risorse delle scorciatoie, fai riferimento all'attività di trampolino nell'intent all'interno della scorciatoia statica.

Per saperne di più sulle attività trampolino, vedi Avviare un'attività da un'altra.

Imposta i flag di intent

Puoi pubblicare scorciatoie dinamiche con qualsiasi insieme di flag Intent. Se possibile, specifica la combinazione di Intent.FLAG_ACTIVITY_SINGLE_TOP e Intent.FLAG_ACTIVITY_CLEAR_TOP nell'intent della scorciatoia. In questo modo, se il tuo ComponentActivity è già attivo, viene portato in primo piano e riutilizzato senza essere distrutto, consentendo all'architettura a singola attività di gestire correttamente l'evento di scorciatoia tramite onNewIntent().

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

Aggiornare le scorciatoie

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

Quando una scorciatoia dinamica viene bloccata, anche se l'editore la rimuove come scorciatoia dinamica, la scorciatoia bloccata è ancora visibile e avviabile. In questo modo un'app può avere più di getMaxShortcutCountPerActivity 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. In un secondo momento, l'utente avvia altre tre conversazioni: c5, c6 e c7. L'app dell'editore ripubblica le sue 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 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, potresti aggiornare questo insieme di scorciatoie quando cambiano le icone dei peer della chat.
2. Puoi utilizzare i metodi addDynamicShortcuts(Context, List) e setDynamicShortcuts(Context, List) per aggiornare le scorciatoie esistenti con gli stessi ID. Tuttavia, non puoi utilizzarli per aggiornare le scorciatoie non dinamiche e bloccate, perché questi due metodi tentano di convertire gli elenchi di scorciatoie forniti in scorciatoie dinamiche.

Non esiste un limite al numero di scorciatoie che possono essere inviate per la visualizzazione su app di assistenza come l'Assistente Google. Utilizza il metodo pushDynamicShortcut della libreria Jetpack ShortcutManagerCompat per creare e aggiornare scorciatoie da utilizzare nelle app di assistenza. Inoltre, aggiungi la libreria Google Shortcuts Integration alla tua app per rendere i link dinamici idonei a essere visualizzati sull'Assistente Google.

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

Gestire le modifiche alle impostazioni internazionali del sistema

Le app devono aggiornare le scorciatoie dinamiche e quelle bloccate quando ricevono la trasmissione Intent.ACTION_LOCALE_CHANGED che indica una modifica alle impostazioni internazionali del sistema.

Monitorare l'utilizzo delle scorciatoie

Per determinare le situazioni in cui vengono visualizzate le scorciatoie statiche e dinamiche, il launcher esamina la cronologia di attivazione delle scorciatoie. Per le scorciatoie statiche, puoi tenere traccia di quando gli utenti completano azioni specifiche all'interno della tua app chiamando il metodo reportShortcutUsed e passando 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.

La tua app monitora l'utilizzo delle scorciatoie dinamiche chiamando il metodo pushDynamicShortcut e passando l'ID della scorciatoia quando si verifica un evento pertinente. Il push dell'utilizzo delle scorciatoie dinamiche con questo metodo consente alle app di assistenza come l'Assistente Google di suggerire agli utenti scorciatoie pertinenti. 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 entrata. Per maggiori dettagli, consulta le best practice per persone e conversazioni.

Disattivare le scorciatoie

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

Limitazione di frequenza

Quando utilizzi i metodi setDynamicShortcuts, addDynamicShortcuts o updateShortcuts, potresti essere in grado di chiamarli solo un numero specifico di volte in un'app in background, ovvero un'app 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 eccessivamente le 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 finché non viene nuovamente raggiunto il limite di frequenza. Questi eventi includono:

• Un'app viene portata in primo piano.
• Le impostazioni internazionali di sistema cambiano.
• L'utente esegue l'azione di risposta in linea su una notifica.

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

$ adb shell cmd shortcut reset-throttling [ --user <var>your-user-id</var> ]

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 il ripristino, tieni presente quanto segue in merito alle scorciatoie delle app:

• Le scorciatoie statiche vengono ripubblicate automaticamente, ma solo dopo che l'utente reinstalla l'app su un nuovo dispositivo.
• Le scorciatoie dinamiche non vengono sottoposte a backup, quindi includi la logica nella tua app per ripubblicarle quando un utente apre l'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 nella tua app in modo da poterle ripristinare rapidamente su un nuovo dispositivo.

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

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts(this).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}