Gestisci le scorciatoie

Dopo aver creato le scorciatoie, potrebbe essere necessario gestirle per l'intera durata delle scorciatoie la tua app. Ad esempio, potresti voler ottimizzare l'app determinando il spesso 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 che eseguono azioni obsolete o mancanti. Per le scorciatoie a cui viene fatto riferimento in conversazioni, potrebbe essere utile monitorare l'utilizzo per fornire indicatori che migliorano il ranking delle scorciatoie.

In questa pagina vengono descritti questi e molti altri metodi comuni per gestire scorciatoie.

Comportamento della scorciatoia

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

Visibilità scorciatoia

Importante: tutte le informazioni sulle scorciatoie sono archiviate in un sistema con crittografia credenziali spazio di archiviazione, in modo che la tua app non possa accedere alle scorciatoie di un utente finché non si sblocca del dispositivo.

Le scorciatoie statiche e le scorciatoie dinamiche vengono visualizzate in Avvio app o quando l'utente esegue un gesto specifico o un comando vocale. Attivato Avvio app supportati, il gesto è un tocco e tieni premuta l'icona in Avvio applicazioni dell'app, ma il gesto potrebbe essere diverso su altre app Avvio app. Con Google Assistente, le scorciatoie possono essere visualizzate all'interno dell'assistente o lanciate da un utente comando vocale.

Il corso LauncherApps fornisce API a cui le app Avvio app possono accedere scorciatoie.

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

• L'utente lo rimuove.
• L'app associata alla scorciatoia viene disinstallata.
• L'utente cancella i dati di un'app in Impostazioni > App e notifiche, Selezione dell'app e poi tocca Spazio di archiviazione > Libera spazio di archiviazione.

Condividere i target sono un sottoinsieme di scorciatoie dinamiche visualizzate nella riga della condivisione diretta Foglio di condivisione di Android.

. Figura 1. Android Sharesheet. I target della condivisione diretta sono visualizzati nella prima riga, seguiti dalle app classificate e infine dagli elenchi delle app.

Ordine di visualizzazione della scorciatoia

Quando in Avvio app vengono visualizzate le scorciatoie di un'app, queste devono essere visualizzate come segue: ordine:

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

All'interno di ogni tipo di scorciatoia, statica e dinamica, le scorciatoie vengono ordinate in ordine di: aumentando il ranking secondo ShortcutInfo.getRank. Assistente Google prende in considerazione anche il ranking delle scorciatoie nel determinare le scorciatoie contestuali da visualizzare utenti.

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

L'ordine dei target di condivisione si basa su vari fattori, tra cui gli utenti passati storia, recency, frequenza suggerimento ranking, utilizzo di app e la priorità impostata per la conversazione associata a un scorciatoia per la condivisione. Condividi le destinazioni create utilizzando API Sharing Shortcuts hanno la priorità rispetto ai target di condivisione prodotti ChooserTargetService: che è stata ritirata in Android 11. In target di condivisione per Android 12 e versioni successive generate dall'elemento ChooserTargetService deprecato non verranno più visualizzati in 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 mostra al massimo due scorciatoie statiche e due scorciatoie dinamiche. Ad esempio, se definire quattro scorciatoie statiche e creare in modo programmatico tre l'Avvio app mostra le prime due scorciatoie statiche e le scorciatoie dinamiche con ranking più elevato.

Nota: i ranking vengono regolati automaticamente in modo da essere univoci per ogni tipo di scorciatoia statica o dinamica. Ad esempio, se sono presenti tre scorciatoie dinamiche, con i gradi 0, 1 e 2, aggiungendo un'altra scorciatoia dinamica con grado 1 rappresenta una richiesta per posizionare questa scorciatoia nella seconda posizione. In risposta, i ranghi delle scorciatoie precedentemente classificate 1 e 2 passano a 2 e 3, rispettivamente.

Gestisci più intent e attività

Se vuoi che l'app esegua più operazioni quando l'utente attiva un puoi configurarla per attivare attività successive. Puoi può farlo assegnando più intent, iniziando un'attività o l'impostazione di flag di intent, a seconda del tipo di scorciatoia.

Assegna più intent

Quando crei una scorciatoia con ShortcutInfoCompat.Builder, puoi utilizzare setIntents() anziché setIntent(). Chiamate il numero setIntents(), può avviare più attività all'interno dell'app quando l'utente seleziona una scorciatoia, posizionando tutte le attività dell'elenco, tranne le ultime, sul stack posteriore. Se l'utente tocca il pulsante Indietro del dispositivo e vede un'altra attività nell'app anziché tornare all'Avvio app del dispositivo.

Nota: quando l'utente seleziona una scorciatoia e poi tocca il pulsante Indietro, il tuo avvia l'attività corrispondente al penultimo e all'ultimo intent elencato in il file di risorse delle scorciatoie. Questo modello di comportamento persiste man mano che l'utente continua a toccare il pulsante Indietro finché l'utente non cancella la pila posteriore che crea una scorciatoia. Quindi, se l'utente tocca di nuovo il pulsante Indietro, il sistema e lo riporta ad Avvio app.

Iniziare un'attività dall'altra

Le scorciatoie statiche non possono avere flag personalizzati per intent. Il primo intent di un container la scorciatoia ha sempre Intent.FLAG_ACTIVITY_NEW_TASK e Intent.FLAG_ACTIVITY_CLEAR_TASK impostato. Ciò significa che quando la tua app è in esecuzione, tutte le attività esistenti nell'app vengono eliminate quando viene viene avviata. Se non vuoi questo comportamento, puoi utilizzare un trampolino elastico. : un'attività invisibile che inizia un'altra attività, nel Activity.onCreate(Bundle) che chiama Activity.finish():

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

Per ulteriori informazioni sulle attività con trampolino, consulta Iniziare un'attività da un altro.

Imposta flag di intent

Puoi pubblicare scorciatoie dinamiche con qualsiasi set di flag Intent. Preferibilmente, specifica Intent.FLAG_ACTIVITY_CLEAR_TASK insieme all'altro e i flag facoltativi. In caso contrario, se tenti di avviare un'altra attività mentre l'app è è in esecuzione, l'attività target potrebbe non essere visualizzata.

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

Aggiorna scorciatoie

L'icona in Avvio applicazioni di ogni app può contenere al massimo una serie di elementi statici e dinamici le scorciatoie combinate che corrispondono al valore restituito getMaxShortcutCountPerActivity Non c'è un limite al numero di le scorciatoie fissate che un'app può creare.

Quando una scorciatoia dinamica viene bloccata, anche se il publisher la rimuove come scorciatoia fissata, la scorciatoia bloccata è ancora visibile e avviabile. Ciò consente un'app ha più di getMaxShortcutCountPerActivity() di scorciatoie.

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

1. Un'app di chat pubblica quattro scorciatoie dinamiche, che rappresentano le quattro conversazioni 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. La l'app del publisher ripubblica le sue scorciatoie dinamiche. La nuova scorciatoia dinamica sono: c4, c5, c6 e c7.

L'app deve rimuovere c1, c2 e c3 perché non è possibile visualizzarne più di quattro scorciatoie dinamiche. Tuttavia, c1, c2 e c3 sono ancora scorciatoie bloccate che all'utente può accedere e avviare.

L'utente può quindi accedere a un totale di sette scorciatoie che collegano alle attività in l'app del publisher. Questo perché il totale include il numero massimo di e le tre scorciatoie fissate.

1. L'app può usare updateShortcuts(Context, List) per aggiornare uno qualsiasi dei sette scorciatoie esistenti. Ad esempio, potresti aggiornare questo insieme di scorciatoie quando la chat si avvicina le icone cambiano.
2. Puoi utilizzare le addDynamicShortcuts(Context, List) e setDynamicShortcuts(Context, List) metodi per aggiornare le scorciatoie esistenti con gli stessi ID. ma non puoi utilizzarle per aggiornare gli asset non dinamici, scorciatoie bloccate, perché questi due metodi tentano di convertire gli elenchi scorciatoie alle scorciatoie dinamiche.

Non esiste un limite al numero di scorciatoie che è possibile inviare tramite push per la visualizzazione app di assistenza, come l'Assistente Google. Utilizza la pushDynamicShortcut() della libreria Jetpack di ShortcutManagerCompat per creare e aggiornare scorciatoie da utilizzare nelle app dell'assistente. Inoltre, aggiungi Google Shortcuts Integration raccolta alla tua app per rendere i link dinamici idonei alla pubblicazione su Google Assistente Google.

Per ulteriori informazioni sulle linee guida relative alle scorciatoie app, incluso l'aggiornamento delle scorciatoie, consulta le Best practice per le scorciatoie.

Gestire le modifiche alle impostazioni internazionali di sistema

Le app devono aggiornare le scorciatoie dinamiche e bloccate quando ricevono il Trasmissione Intent.ACTION_LOCALE_CHANGED che indica una modifica al sistema impostazioni internazionali.

Monitora l'utilizzo delle scorciatoie

Per determinare le situazioni in cui vengono visualizzate le scorciatoie statiche e dinamiche, l'Avvio app esamina la cronologia di attivazione delle scorciatoie. Per le scorciatoie statiche, Puoi monitorare quando gli utenti completano azioni specifiche all'interno dell'app chiamando il metodo reportShortcutUsed() e trasmettendogli l'ID di 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 ai la stessa scorciatoia.

L'app monitora l'utilizzo delle scorciatoie dinamiche chiamando il pulsante pushDynamicShortcut() e passargli l'ID della scorciatoia quando si verifica un evento pertinente. Il push dell'utilizzo delle scorciatoie dinamiche con questo metodo consente le app di assistenza, come l'Assistente Google, suggeriscono scorciatoie pertinenti agli utenti. Dato che 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 per le chiamate in uscita e messaggi in arrivo. Per maggiori dettagli, consulta le best practice per le persone e conversazioni.

Nota: per attivare la funzionalità, è necessaria la libreria di integrazione di Google Shortcuts I link dinamici inviati dalla tua app per renderli idonei alla visualizzazione sulle piattaforme Google come l'Assistente Google. Se aggiungi questa raccolta alla tua app, consenti all'assistente acquisire i tuoi link dinamici e consigliarli agli utenti dall'app dell'assistente.

Disattiva scorciatoie

Poiché la tua app e i suoi utenti possono bloccare scorciatoie in Avvio app del dispositivo, è possibile che queste scorciatoie fissate possano indirizzare gli utenti a eseguire azioni nella tua app non aggiornati o che non esistono più. Per gestire questa situazione, puoi disattiva le scorciatoie che non vuoi che gli utenti selezionino chiamando disableShortcuts, che rimuove le scorciatoie specificate dal feed statico e le scorciatoie dinamiche elencano e disattivano le copie fissate di queste scorciatoie. Tu puoi anche utilizzare una versione sovraccarica di questo metodo che accetta un CharSequence come messaggio di errore personalizzato. Il messaggio di errore viene visualizzato. Quando gli utenti tentano di avviare qualsiasi scorciatoia disattivata.

Nota: se rimuovi alcune scorciatoie statiche dell'app quando aggiorni la app, il sistema disattiva automaticamente queste scorciatoie.

Limitazione di frequenza

Quando utilizzi l'setDynamicShortcuts(), addDynamicShortcuts() o updateShortcuts(), potresti essere in grado di chiamare questi metodi solo numero specifico di volte in un'app in background: un'app senza attività o servizi in primo piano. Il limite al numero specifico di volte in cui è possibile chiamati limitazione di frequenza. Questa funzione impedisce ShortcutManagerCompat da un consumo 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 può chiamare metodi ShortcutManager fino a quando non viene raggiunto nuovamente il limite di frequenza. Questi includono i seguenti:

• Un'app appare in primo piano.
• Le impostazioni internazionali del sistema cambiano.
• L'utente esegue l'azione risposta integrata su una notifica.

Se riscontri una limitazione di frequenza durante lo sviluppo o il test, puoi selezionare Opzioni sviluppatore > Reimposta il limite di frequenza di ShortcutManager dal dispositivo impostazioni oppure 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 cambiare dispositivo includendo l'elemento android:allowBackup="true" attributo nel file manifest dell'app. Se supporti il backup e il ripristino, conserva tieni presenti 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 è stato eseguito il backup delle scorciatoie dinamiche, quindi includi nella tua app la logica per ripubblicarla quando un utente apre la tua app su un nuovo dispositivo.
• Le scorciatoie bloccate vengono ripristinate automaticamente nell'Avvio app del dispositivo, ma non esegue il backup delle icone associate alle scorciatoie fissate. Pertanto, risparmia le scorciatoie fissate di immagini nella tua app in modo che sia facile ripristinarle un nuovo dispositivo.

Il seguente snippet di codice mostra il modo migliore per ripristinare le creatività dinamiche dell'app scorciatoie e come controllare se le scorciatoie fissate 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.
            }
        }
    }
    // ...
}