Aggiungi funzionalità alle scorciatoie

Le funzionalità in shortcuts.xml ti consentono di dichiarare i tipi di azioni che gli utenti possono intraprendere per avviare la tua app ed eseguire direttamente un'attività specifica.

Ad esempio, le Azioni app dell'Assistente Google utilizzano le funzionalità per consentire agli sviluppatori di estendere le funzionalità in-app agli intent integrati (BII), consentendo agli utenti di attivare e controllare queste funzionalità utilizzando i comandi vocali. Una funzionalità è costituita dal nome dell'azione e da un intent che ha come target la destinazione nella tua app che risolve l'intent dell'utente.

Definire le funzionalità in shortcuts.xml

Definisci gli elementi capability in un file di risorse shortcuts.xml nel progetto di sviluppo dell'app per Android. Per definire un elemento capability:

  1. Crea una risorsa shortcuts.xml seguendo le istruzioni riportate in Creare scorciatoie statiche.

  2. Includi le seguenti informazioni obbligatorie nella funzionalità:

    • Nome della funzionalità: l'azione che vuoi che la tua app supporti. Consulta la documentazione dei componenti per la funzionalità che richiede definizioni di funzionalità. I comandi vocali delle Azioni app utilizzano il BII Action ID per i nomi delle funzionalità, che puoi trovare nel riferimento BII. Ad esempio, il GET_THING BII elenca il suo Action ID come actions.intent.GET_THING.

    • Destinazione dell'app: la destinazione nella tua app che l'azione avvia per soddisfare la richiesta dell'utente. Definisci le destinazioni dell'app utilizzando gli elementi intent nidificati all'interno di capability.

    • Mappature dei parametri: ogni intent può contenere parametri da passare come dati extra dell'intent. Ad esempio, ogni BII delle Azioni app include campi che rappresentano le informazioni che gli utenti forniscono spesso nelle query che attivano il BII.

L'esempio seguente mostra una definizione di funzionalità in shortcuts.xml per actions.intent.START_EXERCISE, un BII che consente agli utenti di utilizzare i comandi vocali con l'assistente per iniziare un allenamento in un'app per il fitness:

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.START_EXERCISE">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.sampleApp"
      android:targetClass="com.example.sampleApp.ExerciseActivity">
      <parameter
        android:name="exercise.name"
        android:key="exerciseType"/>
    </intent>
  </capability>
</shortcuts>

Nell'esempio precedente, l'attributi <capability> android:name fa riferimento a il BII START_EXERCISE. Se un utente richiama questo BII chiedendo all'assistente "Hey Google, inizia una corsa in ExampleApp," l'assistente soddisfa la richiesta dell'utente utilizzando le informazioni fornite nell'elemento intent nidificato. L'intent in questo esempio definisce i seguenti dettagli:

  • android:targetPackage imposta il pacchetto dell'applicazione di destinazione per questo intent.
  • Il campo android:targetClass specifica l'attività di destinazione: com.example.sampleApp.ExerciseActivity.
  • L'intent parameter dichiara il supporto per un parametro BII exercise.name e come passare il valore parametro, raccolto dall'utente, come dati extra nel intent.

Associare le scorciatoie a una funzionalità

Dopo aver definito una funzionalità, puoi estenderne la funzionalità associandovi scorciatoie statiche o dinamiche. Il modo in cui le scorciatoie sono collegate a una capability dipende dalla funzionalità implementata e dalle parole effettive incluse nella richiesta di un utente. Ad esempio, quando un utente inizia una corsa nella tua app di monitoraggio del fitness chiedendo all'assistente, "Hey Google, inizia una corsa in ExampleApp." L'assistente può utilizzare una scorciatoia per avviare un'istanza di una capability che definisce un'entità di esercizio valida di "corsa" per il parametro exercise.name.

Per ulteriori informazioni sull'associazione delle scorciatoie alle Azioni app, consulta la panoramica delle Azioni app.