Crea scorciatoie.xml

Dopo aver identificato la funzionalità in-app e l'intent integrato corrispondente da implementare, dichiara gli intent integrati supportati dalla tua funzionalità definendo un elemento capability in un file di risorse shortcuts.xml. La dichiarazione di un BII come capability registra il supporto dell'intent semantico nella tua app e consente l'esecuzione della query vocale dell'intent utilizzando l'Assistente Google.

L'assistente utilizza l'elaborazione del linguaggio naturale per estrarre i parametri da una query dell'utente. La documentazione di riferimento sugli intenti integrati elenca i campi che ogni BII è in grado di estrarre da una query utente associata. Ad esempio, se un utente invoca la funzionalità [actions.intent.GET_FOOD_OBSERVATION][] nella tua app dicendo "Hey Google, chiedi a EsempioApp cosa ho mangiato a pranzo venerdì scorso", l'assistente estrae i seguenti parametri BII dalla richiesta dell'utente:

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

L'assistente passa i parametri BII al intent di completamento definito in capability. In una funzionalità è possibile definire uno o più elementi intent per supportare i diversi modi in cui un utente può richiamare un BII. Ad esempio, nel esempio precedente potresti definire un fulfillment intent che richiede entrambi i parametri BII. Potresti quindi definire un secondo intento che richiede un singolo parametro BII, foodObservation.forMeal, che genera report per tutti i pasti di un determinato giorno, ad esempio "Hey Google, chiedi a ExampleApp cosa ho mangiato a pranzo".

Panoramica

Configura le azioni app utilizzando un file shortcuts.xml posizionato nella directory shortcuts.xml del progetto dell'app, quindi creando un riferimento a shortcuts.xml nel file manifest dell'app.res/xml Aggiungi un riferimento a shortcuts.xml nel manifest dell'app:

1. Nel file manifest dell'app (AndroidManifest.xml), trova un'attività i cui filtri per intent sono impostati sull'azione android.intent.action.MAIN e sulla categoria android.intent.category.LAUNCHER.

2. Aggiungi un riferimento a shortcuts.xml in AndroidManifest.xml utilizzando un tag <meta-data> in Activity con filtri di intente sia per MAIN che per LAUNCHER, come segue:

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

L'esempio riportato sopra dichiara una risorsa XML per il file xml/shortcuts.xml nell'APK. Per maggiori dettagli sulla configurazione delle scorciatoie, consulta Creare scorciatoie statiche nella documentazione per gli sviluppatori Android.

La libreria Jetpack androidx.core:core:1.6.0 (o successive) è obbligatoria nel tuo progetto Android per evitare errori di compilazione durante la definizione delle funzionalità delle Azioni app in shortcuts.xml. Per maggiori dettagli, consulta la guida introduttiva ad Android Jetpack.

Scorciatoie statiche

Quando definisci capability, puoi dichiarare elementi shortcut statici in shortcuts.xml per estendere la funzionalità della funzionalità. Le scorciatoie statiche vengono importate dall'assistente quando carichi una release su Google Play Console. Poiché le scorciatoie statiche possono essere create e aggiornate solo creando nuove release, sono più utili per mettere in evidenza attività e contenuti comuni nella tua app.

Puoi attivare la seguente funzionalità di App Actions con le scorciatoie statiche:

• Scorciatoie per le funzionalità. Creare scorciatoie che avviano un'istanza di capability contenente valori di parametro intent predefiniti. Ad esempio, puoi dichiarare una scorciatoia per l'app "Inizia una corsa" che invoca la funzionalità BII START_EXERCISE nella tua app per il fitness.

  Queste scorciatoie contengono gli attributi intent, shortLabel e longLabel, pertanto possono essere suggerite e soddisfatte come chip nelle piattaforme proactive, come l'assistente o quando si preme a lungo l'icona di un'app sui avviatori Android. Una scorciatoia per un'azione può anche fungere da scorciatoia per un'entità, come descritto di seguito, associandola a un capability utilizzando un tag <capability-binding>.

• Scorciatoie per le entità. Le scorciatoie delle entità forniscono un elenco di valori di parametri supportati per l'evasione delle query vocali di un capability. Ad esempio, una scorciatoia per entità con un elenco di tipi di esercizio ("escursione", "corsa" e così via) associata al parametro BII exercise.name della funzionalità START_EXERCISE. Se un'espressione dell'utente corrisponde a un'entità, l'ID shortcutId viene passato all'intent anziché al valore della query dell'utente non elaborato.

  Le scorciatoie Entity non definiscono gli attributi intent, shortLabel o longLabel e, pertanto, non vengono suggerite sulle piattaforme proattive. Per maggiori dettagli, consulta Inventario in linea per le azioni in-app.

Schema delle funzionalità

La seguente tabella descrive lo schema di App Actions per gli elementi capability in shortcuts.xml. Quando includi un tag, tutti i relativi attributi sono obbligatori, a meno che non siano contrassegnati come "facoltativi".

Descrizione dello schema delle funzionalità

Questa sezione descrive gli elementi dello schema capability.

<capability>

Un capability che definisce l'intent Azione app supportato dalla tua app. Ogni elemento <capability> nel file shortcuts.xml deve fornire almeno un <intent> per gestire il completamento dell'azione.

Attributi:

• android:name: ID azione dell'intent integrato (ad es. [actions.intent.GET_FOOD_OBSERVATION][]). Per un elenco degli intent integrati supportati, consulta la documentazione di riferimento sugli intent integrati.
• app:queryPatterns: una risorsa array di stringhe di query previste dall'utente per questo intento. Questo attributo è applicabile solo agli intent personalizzati, poiché gli IIB includono già modelli dei modi comuni in cui gli utenti esprimono le attività che stanno cercando di svolgere o le informazioni che cercano.

<intent>

Elemento Android intent che definisce come deve essere soddisfatta una query dell'utente utilizzando la funzionalità in-app. Gli sviluppatori possono fornire più tag <intent> in un capability. L'assistente tenta di soddisfare una query dell'utente utilizzando il primo <intent> in un capability per il quale sono forniti tutti i parametri richiesti.

Attributi:

• android:action: il tipo di intent Action. Il valore predefinito è ACTION_VIEW.
• android:targetClass: classe Attività target, ad esempio: "com.example.exercise.ExerciseActivity"
• android:targetPackage: pacchetto contenente la classe Activity di destinazione, ad esempio: "com.example.exercise
• android:data: questo campo viene sovrascritto da <url-template> se il tag è dichiarato in intent.

<url-template>

Modello per la creazione di un URI di link diretto da aprire sul dispositivo. Il modello può essere espanso con i parametri di intent integrati se sono disponibili tutti i parametri obbligatori per il modello. Per esempi del modello di URL HTTP, consulta l'articolo di Wikipedia sui modelli di URL. Il formato del modello segue la specifica del modello URI RFC6570.

Di seguito sono riportati alcuni esempi di valori del modello di URL:

Per scoprire di più sulla configurazione dei modelli di URL, consulta Modelli di URL nell'evasione.

<extra>

Definisce dati aggiuntivi per un intent. Per le azioni app, questo campo viene utilizzato solo per attivare [chiamata app in primo piano][] per un capability.

<parameter>

Mappa un parametro BII ai valori dei parametri dell'intent. Per saperne di più, consulta la sezione Dati e corrispondenza dei parametri.

Attributi:

• android:name: nome del parametro BII da associare a questo parametro intent. Il nome deve essere un campo a livello di foglia del parametro BII (ad es. foodObservation.aboutFood.name).
• android:key: chiave definita dallo sviluppatore di un valore del parametro BII. Ad esempio, potresti definire contact_name per il parametro BII message.recipient.name.
• android:mimeType: il tipo MIME del parametro, ad esempio text/*. Questo campo è obbligatorio solo per i parametri degli intent personalizzati.
• android:required: indica se la query dell'utente deve includere questo parametro affinché questo intento venga utilizzato per l'evasione. Se il parametro non è disponibile, l'assistente tenta di soddisfare la query dell'utente utilizzando il prossimo intent definito per capability.

<shortcut-fulfillment>

Specifica che per l'evasione deve essere utilizzato un intent definito in una scorciatoia dell'inventario in linea per un parametro specificato. Per maggiori dettagli, vedi Eseguire il completamento utilizzando gli intent di scorciatoia.

<parameter> (per <shortcut-fulfillment>)

Attributo facoltativo che mappa un singolo parametro BII al completamento della scorciatoia per l'inventario in linea. Per maggiori dettagli, vedi Eseguire il completamento utilizzando gli intent di scorciatoia.

Attributo:

• android:name: nome del parametro BII da associare all'evasione delle scorciatoie per l'inventario in linea. Il nome deve essere un campo a livello di foglia del parametro BII (ad esempio menuItem.name).

<slice>

Consente all'assistente di incorporare il risultato di una query corrispondente a questo capability come sezione Android. Per maggiori dettagli, vedi Integrare Azioni app con le sezioni di Android.

Schema delle scorciatoie

La tabella seguente descrive gli attributi degli elementi shortcut utilizzati per attivare la funzionalità App Actions. Quando includi un tag, tutti i relativi attributi sono obbligatori, a meno che non siano contrassegnati come "facoltativi".

Descrizione dello schema delle scorciatoie

Questa sezione descrive gli elementi dello schema shortcut.

<shortcut>

Un <shortcut> Android definito in shortcuts.xml con determinati attributi pertinenti per le azioni in-app. I valori di stringa per i campi shortcutShortLabel e shortcutLongLabel vengono richiamati tramite le risorse stringa dell'APK.

Attributi:

• android:shortcutId: identificatore di questa scorciatoia.
• android:shortcutShortLabel: risorsa stringa che rappresenta una breve frase di abbreviazione. Ad esempio, "@string/callDavidShort" che rappresenta il valore "Chiama David".
• android:shortcutLongLabel: risorsa stringa che rappresenta una frase di scorciatoia lunga. Ad esempio, "@string/callDavidLong" che rappresenta il valore "Fai una chiamata audio a Davide".

<intent>

Intent Android associato a questa scorciatoia. Questo intent viene eseguito quando un utente avvia questa scorciatoia tramite comandi vocali o tocco.

Gli attributi shortcut intent sono identici agli attributi capability intent.

<capability-binding>

Associa un shortcut a un capability di Azioni app. L'aggiunta di questo elemento a un shortcut lo abilita per l'evasione vocale utilizzando Assistant.

Attributi:

• android:key: l'attributo android:name del capability a cui è associato questo shortcut. Ad esempio, actions.intent.START_EXERCISE.

<parameter-binding>

Attributo facoltativo che associa un shortcut a un singolo parametro di un capability App Actions. Se è definito un parameter-binding per un shortcut, la scorciatoia può essere utilizzata per fornire un'entità di inventario in linea a un parametro BII. Per ulteriori dettagli, consulta Inventario in linea per App Actions.

Attributi:

• android:key: il nome del parametro BII capability a cui associare questa scorciatoia. Ad esempio, exercise.name.
• android:value: il valore entity. Può essere un singolo entity o un elenco di risorse.

<extra>

I dati del bundle extra per la scorciatoia. sameAs è l'unico dato pertinente per gli elementi shortcut di App Actions. L'URL sameAs fa riferimento a una pagina web di riferimento che identifica in modo univoco l'entità. Viene utilizzato per specificare un valore enumerato se e solo se il tipo di parametro di intent è un sottotipo di schema.org/Enumeration. È obbligatorio per i campi dei parametri i cui tipi sono sottotipi di schema.org/Enumeration (ad esempio: MealTypeBreakfast).

Attributi:

• android:key: il valore supportato per Azioni app è: sameAs
• android:value: il valore dell'URL sameAs

Per ulteriori dettagli, consulta la sezione Corrispondenza dei valori dei parametri enumerati.

Opzioni di adempimento degli intent

Definisci gli elementi intent all'interno di un <capability> per dichiarare in che modo l'assistente risponde o soddisfa i comandi vocali dell'utente corrispondenti a quella funzionalità. Esistono diversi modi per configurare il modo in cui un intent avvia una destinazione di adempimento nella tua app, a seconda della struttura della navigazione dell'app.

Sono disponibili le seguenti opzioni di evasione degli ordini:

• Intent espliciti: avvia un componente dell'app specifico definendo gli attributi targetClass e targetPackage per intent. Questo è il metodo di adempimento di App Actions consigliato.

• Link diretti: avvia le destinazioni dell'app utilizzando i link diretti per Android definendo un tag <url-template> all'interno dell'elemento intent. Questo metodo è utile se la navigazione nell'app si basa già su link diretti.

• Dati sull'intenzione: puoi fornire un URI di adempimento nell'attributo intent android:data. Questo campo viene sovrascritto dai dati <url-template> se il tag è definito anche all'interno di intent.

Dati e corrispondenza dei parametri

Per impostazione predefinita, l'assistente invia alla tua app i parametri di intent integrati estratti dalla query dell'utente come dati extra dell'intent Android definiti nel capability.

In alternativa, puoi dichiarare un tag <url-template> in capability contenente segnaposto per i parametri dinamici. Questo modello viene mappato a una delle tue attività Android utilizzando un URL dei link alle app, un'schema personalizzato o un URL basato sull'intent.

Utilizzare gli elementi aggiuntivi per intenzione

L'esempio seguente mostra un intent esplicito definito per l'esecuzione di capability:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Dato l'esempio precedente, per una query dell'utente come "Hey Google, avvia la mia corsa", l'app riceve un intent che richiama il componente: targetPackage, targetClass. Il componente riceve un extra con key = "exercise", value = "Running".

Utilizzare un modello di URL per i link diretti Android

Se la tua app è già in grado di gestire gli URL collegati all'app, con parametri dinamici, puoi definire un <url-template> in intent per generare link diretti Android per il completamento. L'esempio seguente definisce un <url-template>:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Dato l'esempio riportato sopra, per una query dell'utente come "Hey Google, avvia la corsa", l'app riceve l'URL generato: "myapp://start?exercise=Corsa".

Per mappare il parametro BII a una posizione nell'URL, utilizza l'attributo android:name del tag <parameter>. Questo attributo corrisponde al valore android:key nel modello di URL che vuoi sostituire con le informazioni dell'utente. Il valore android:key deve essere presente in <url-template> e racchiuso tra parentesi graffe ({}).

Corrispondenza dei valori dei parametri enumerati

Alcuni parametri BII forniscono valori enumerati all'intent di adempimento, ad esempio i valori di testo supportati del BII RECORD_FOOD_OBSERVATION. Per questi parametri, l'assistente associa la query dell'utente ("Colazione") a un'entità il cui valore sameAs corrisponde all'URL dello schema dell'enum (https://schema.googleapis.com/MealTypeBreakfast). Per associare i valori dell'enum per un entity supportato, devi dichiarare un'associazione sameAs nel tuo shortcut. L'esempio seguente mostra un'associazione sameAs per una scorciatoia dell'entità in linea:

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

Nell'esempio precedente, se la funzionalità RECORD_FOOD_OBSERVATION attiva una corrispondenza per il tipo di pasto "colazione", con il completamento intent viene inviato il seguente Extra:

• key = "for_meal"
• value = "meal_breakfast"

Funzionalità

In shortcuts.xml sono disponibili le seguenti funzionalità di Azioni app.

Inventario in linea per Azioni app

Per alcuni parametri BII, è possibile utilizzare scorciatoie per indirizzare l'estrazione delle entità a un insieme di entità supportate specificato in shortcuts.xml, noto come inventario in linea. Per maggiori dettagli, consulta Inventario in linea.

Intenzioni personalizzate

Gli intent personalizzati possono essere dichiarati in shortcuts.xml per attivare tramite comandi vocali le funzionalità della tua app che non corrispondono agli intent integrati disponibili. Sebbene simili per funzionalità a una definizione BII, gli intent personalizzati richiedono due attributi aggiuntivi in shortcuts.xml:

• app:queryPatterns: risorsa array che dichiara i diversi modelli di query per un intent personalizzato.

• android:mimeType: tipo di parametro di un'intenzione personalizzata. Questo campo non è obbligatorio per i report di analisi di mercato, in cui il tipo di parametro è noto. Per i parametri di intent personalizzati, è necessario dichiarare un tipo di semantica supportato.

Per maggiori dettagli, consulta la sezione Intenti personalizzati.