Crea scorciatoie.xml

Dopo aver identificato la funzionalità in-app e l'intent integrato corrispondente da implementare, dichiara le BII supportate dalla tua funzionalità definendo un elemento capability in un file di risorse shortcuts.xml. La dichiarazione di BII come capability registra il supporto per quell'intent semantico nell'app e consente il completamento di query vocali dell'intent utilizzando l'Assistente Google.

L'assistente utilizza l'elaborazione del linguaggio naturale per estrarre parametri dalla query di un utente. Il riferimento per intent integrati elenca i campi che ogni BII è in grado di estrarre da una query utente associata. Ad esempio, se un utente richiama la funzionalità actions.intent.ORDER_MENU_ITEM nella tua app dicendo "Hey Google, ordina una pizza da ExampleCafe in ExampleApp", l'assistente estrae i seguenti parametri BII dalla richiesta dell'utente:

• menuItem.name = "pizza"
• menuItem.inMenuSection.inMenu.forRestaurant.name = "EsempioCaffè"

L'assistente passa i parametri BII al fulfillment intent definito nel capability. È possibile definire uno o più elementi intent in una funzionalità per accogliere i diversi modi in cui un utente può richiamare uno BII. Ad esempio, nell'esempio riportato sopra potresti definire un intent di fulfillment che richiede entrambi i parametri BII. Puoi quindi definire un secondo intent che richiede un singolo parametro BII, menuItem.name, che mostra le opzioni dei ristoranti nelle vicinanze se un utente effettua una richiesta più semplice, ad esempio "Hey Google, ordina una pizza su ExampleApp".

Nota: un intent di riserva intent che non richiede la presenza di un parametro per soddisfare la richiesta di un utente per ogni capability. Questi intent di riserva migliorano l'esperienza utente consentendo l'esecuzione delle azioni anche per query utente poco chiare, come "Hey Google, ordina cibo su ExampleApp".

Panoramica

Per configurare Azioni app, devi utilizzare un file shortcuts.xml posizionato nella directory res/xml del progetto di app e creare un riferimento a shortcuts.xml nel file manifest dell'app. Aggiungi un riferimento a shortcuts.xml nel file manifest dell'app seguendo questi passaggi:

1. Nel file manifest della tua app (AndroidManifest.xml), trova un'attività i cui filtri 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 che dispone di filtri di intent sia per MAIN sia 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.

Nota: se usi uno strumento di offuscamento per l'APK di release, disattiva l'offuscamento per il file shortcuts.xml dell'app utilizzando una lista consentita. In caso contrario, è probabile che si verifichi un errore quando carichi l'APK su Google Play Console.

La libreria Jetpack androidx.core:core:1.6.0 (o superiore) è obbligatoria nel tuo progetto Android per evitare errori di compilazione quando definisci le funzionalità di Azioni app in shortcuts.xml. Per i 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 evidenziare attività e contenuti comuni nella tua app.

Nota: l'assistente può anche mostrare scorciatoie dinamiche agli utenti. Le scorciatoie dinamiche sono personalizzate per i tuoi utenti e possono essere create e aggiornate in fase di runtime. Per maggiori dettagli, vedi Eseguire il push di scorciatoie dinamiche all'assistente.

Puoi attivare le seguenti funzionalità di Azioni app con le scorciatoie statiche:

• Scorciatoie delle funzionalità: Crea scorciatoie che avviano un'istanza di capability contenente valori parametro intent predefiniti. Ad esempio, puoi dichiarare una scorciatoia dell'app "Avvia una corsa" che richiama la funzionalità BII di START_EXERCISE nella tua app per l'attività fisica.

  Queste scorciatoie contengono gli attributi intent, shortLabel e longLabel, che li rendono idonee per essere suggerite e fornite come chip in piattaforme proattive, come l'assistente, o quando si preme a lungo l'icona di un'app in Avvio app di Android. Una scorciatoia di un'azione può anche essere utilizzata come scorciatoia per un'entità, descritta di seguito, associandola a un capability tramite un tag <capability-binding>.

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

  Le scorciatoie di Entity non definiscono gli attributi intent, shortLabel o longLabel e pertanto non vengono suggerite sulle piattaforme proattive. Per i dettagli, consulta Inventario incorporato per azioni app.

  Nota: le scorciatoie statiche dichiarate come scorciatoie delle entità vengono eliminate dall'API LauncherApps, il che significa che sono disponibili per l'avvio app di Android.

Schema funzionalità

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

Tag Scorciatoias.xml	Contenuto in	Attributi
<capability>	<shortcuts>	android:name app:queryPatterns (applicabile solo per gli intent personalizzati)
<intent>	<capability>	android:action (facoltativo) android:targetClass (facoltativo) android:targetPackage (facoltativo) android:data (facoltativo)
<url-template>	<intent>	android:value
<extra>	<intent>	android:key android:value Applicabile solo per le chiamate di app in primo piano
<parameter>	<intent>	android:name android:key android:mimeType (applicabile solo per gli intent personalizzati) android:required (facoltativo) app:shortcutMatchRequired (facoltativo)
<data>	<parameter>	android:pathPattern (applicabile solo all'inventario web)
<shortcut-fulfillment>	<capability>	Applicabile solo per l'inventario in linea
<parameter>	<shortcut-fulfillment>	android:name
<slice>	<capability>	Applicabile solo per Sezioni Android

Descrizione dello schema di funzionalità

Questa sezione descrive gli elementi dello schema capability.

<capability>

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

Attributi:

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

Nota: gli intent integrati di Azioni app sono distinti dagli intent Android. Gli BII modellano una query dell'utente per un'attività che l'utente vuole eseguire nella tua app. Gli intent Android, invece, le destinazioni di lancio nella tua app includono il contesto. Devi dichiarare i tag capability per mappare una BII a un intent Android corrispondente, in modo che gli utenti possano avviare la funzionalità in-app richiamando lo BII con l'assistente.

<intent>

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

Attributi:

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

Nota: android:targetClass e android:targetPackage sono obbligatori per gli intent che hanno come target esplicitamente un'attività. L'attributo android:data può essere utilizzato anche per definire un'attività target. Per maggiori dettagli, consulta Opzioni di fulfillment dell'intent.

<modello-url>

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

Di seguito sono riportati alcuni esempi di valori di modelli di URL:

Modello	Valori	Valore espanso
https://example.com/test{?foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?utm_campaign=appactions&foo=123&bar=456
https://example.com/test?utm_campaign=appactions{#foo}	"foo": "123"	https://example.com/test?utm_campaign=appactions#foo=123
myapp://example/{foo}	"foo": "123"	myapp://example/123

Per ulteriori informazioni sulla configurazione dei modelli di URL, consulta Modelli di URL in fulfillment.

Nota: <url-template> è un metodo facoltativo per il targeting di un'attività in un intent. Per maggiori dettagli, vedi Opzioni di completamento dell'intent.

<extra>

Definisce i dati aggiuntivi per un elemento intent. Per Azioni app, questo campo viene utilizzato solo per abilitare le chiamate di app in primo piano per una capability.

<parametro>

Mappa un parametro BII ai valori dei parametri per intent. Per ulteriori informazioni, consulta Dati dei parametri e corrispondenza.

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 esempio, foodObservation.aboutFood.name).
• android:key: chiave definita dallo sviluppatore di un valore parametro BII. Ad esempio, puoi definire contact_name per il parametro BII message.recipient.name.
• android:mimeType: il mimeType del parametro, ad esempio text/*. Questo campo è obbligatorio solo per i parametri degli intent personalizzati.
• android:required: dichiara se la query dell'utente deve includere questo parametro affinché questo intent possa essere utilizzato per il fulfillment. Se il parametro non è disponibile, l'assistente tenta di soddisfare la query dell'utente utilizzando il valore intent successivo definito per capability.

<dati>

Associa un inventario web a una parameter.

Attributo:

• android:pathPattern: pattern URL per entity URL da restituire utilizzando l'inventario web. Questo attributo supporta due caratteri jolly:

  • *: un asterisco corrisponde a una sequenza di zero o più occorrenze del carattere immediatamente precedente.

  • .*: un punto seguito da un asterisco corrisponde a qualsiasi sequenza di zero o più caratteri.

  • I caratteri di escape sono necessari solo per i valori letterali * e \, a cui puoi eseguire l'escape rispettivamente come \\* e \\\\.

<scorciatoie-fulfillment>

Consente di specificare che un intent definito in una scorciatoia per l'inventario in linea per un parametro specificato deve essere utilizzato per il fulfillment. Per maggiori dettagli, consulta l'articolo Fulfillment utilizzando intent scorciatoia.

<parametro> (per <shortcut-fulfillment>)

Attributo facoltativo che mappa un singolo parametro BII al completamento della scorciatoia per l'inventario in linea. Per maggiori dettagli, consulta l'articolo Fulfillment utilizzando intent scorciatoia.

Attributo:

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

<sezione>

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

Schema della scorciatoia

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

Tag Scorciatoias.xml	Contenuto in	Attributi
<shortcut>	<shortcuts>	android:shortcutId android:shortcutShortLabel android:shortcutLongLabel (facoltativo) android:icon (facoltativo)
<intent>	<shortcut>	android:action android:targetClass (facoltativo) android:targetPackage (facoltativo) android:data (facoltativo)
<capability-binding>	<shortcut>	android:key
<parameter-binding>	<capability-binding>	android:key (facoltativo) android:value
<extra>	<shortcut>	android:name (facoltativo) android:value Applicabile solo per la corrispondenza dei parametri di enum.

Descrizione schema della scorciatoia

Questa sezione descrive gli elementi dello schema shortcut.

<scorciatoia>

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

Attributi:

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

<intent>

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

Gli attributi per intent di shortcut sono identici agli attributi intent di capability.

<capability-binding>

Associa un shortcut a un capability di Azioni app. L'aggiunta di questo elemento a shortcut ne abilita il completamento vocale utilizzando Assistant.

Attributi:

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

<associazione-parametri>

Attributo facoltativo che associa shortcut a un singolo parametro di un'istanza Azioni app capability. Se viene definito un parameter-binding per un shortcut, è possibile utilizzare la scorciatoia per fornire un'entità di inventario in linea a un parametro BII. Per ulteriori dettagli, consulta la sezione Inventario incorporato per azioni app.

Attributi:

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

<extra>

I dati del gruppo extra per la scorciatoia. sameAs sono gli unici dati pertinenti per gli elementi shortcut di Azioni app. L'URL sameAs si riferisce a una pagina web di riferimento che identifica in modo inequivocabile l'entità. Utilizzato per specificare un valore enum se e solo se il tipo di parametro intent è un sottotipo di schema.org/Enumeration. È obbligatorio per i campi di 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 maggiori dettagli, consulta la sezione Corrispondenza dei valori dei parametri enumerati.

Opzioni di completamento dell'intent

Definisci gli elementi intent in un <capability> per dichiarare in che modo l'assistente risponde ai comandi vocali dell'utente o li soddisfa. Esistono diversi modi per configurare il modo in cui un intent lancia una destinazione di evasione degli ordini nella tua app, a seconda di come è strutturata la navigazione nell'app.

Sono disponibili le seguenti opzioni di evasione degli ordini:

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

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

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

Nota: queste opzioni di evasione degli ordini si escludono a vicenda. Ad esempio, se definisci un elemento intent esplicito utilizzando gli attributi targetClass e targetPackage, non devi definire anche un elemento <url-template>.

Dati dei parametri e corrispondenza

Per impostazione predefinita, l'assistente invia alla tua app i parametri BII estratti dalla query dell'utente come dati extra del intent Android definito in capability.

In alternativa, puoi dichiarare un tag <url-template> nel file capability che contiene segnaposto per parametri dinamici. Questo modello è mappato a una delle tue attività Android utilizzando un URL dei link alle app, uno schema personalizzato o un URL basato sull'intenzione.

Utilizzo degli elementi extra per l'intent

L'esempio seguente mostra un intent esplicito definito per un fulfillment capability:

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

Dato l'esempio precedente, per una query utente come "Hey Google, ordina un latte macchiato da ExampleApp", l'app riceve un intent che richiama il componente: targetPackage, targetClass. Il componente riceve un extra con key = ”menu”, value = ”latte”.

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 i parametri dinamici, puoi definire un <url-template> in intent per generare link diretti Android per il fulfillment. Il seguente esempio definisce un <url-template>:

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent>
    <url-template android:value="myapp://order{?menu}" />
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

Considerato l'esempio precedente, per una query utente del tipo "Hey Google, ordina un latte macchiato da ExampleApp", l'app riceve l'URL generato: "myapp://order?menu=latte".

Nota: se l'URL generato per un intent che utilizza <url-template> per il fulfillment è collegato all'app e sono stati aggiunti filtri di intent pertinenti nel file di risorse AndroidManifest.xml, gli attributi targetClass e targetActivity non devono essere definiti in intent.

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 ({}).

Associa i valori parametro enumerati

Alcuni parametri BII forniscono valori enumerati per l'intent di fulfillment, ad esempio i valori di testo supportati di 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 di enum (https://schema.googleapis.com/MealTypeBreakfast). Per associare i valori di enum per un elemento entity supportato, devi dichiarare un'associazione sameAs in shortcut. Il seguente esempio mostra un'associazione sameAs per una scorciatoia di un'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", il seguente extra viene inviato con il fulfillment intent:

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

Funzionalità

Le seguenti funzionalità di Azioni app sono disponibili in shortcuts.xml.

Inventario incorporato per Azioni app

Per alcuni parametri BII, le scorciatoie possono essere utilizzate per guidare l'estrazione delle entità verso un insieme di entità supportate specificate in shortcuts.xml, note come inventario in linea. Per maggiori dettagli, consulta la sezione Inventario in linea.

Inventario web per Azioni app

Per alcuni BII, è possibile utilizzare un inventario web come metodo per generare URL per il fulfillment. L'inventario web usa il tuo sito web per scoprire gli URL per il completamento delle azioni app. Questa funzionalità è utile soprattutto se hai una forte presenza sul web e i link diretti in-app sono organizzati in base a contenuti web disponibili pubblicamente.

Attenzione: l'inventario web restituisce gli URL in base alla pathPattern che hai fornito, poiché questi URL esistono e vengono posizionati sul web. Se l'app non è in grado di analizzare gli URL con il pattern, l'Azione app non si attiva correttamente.

Per maggiori dettagli, consulta Inventario web.

Nota: l'inventario web supporta un massimo di parameter per evasione delle funzionalità intent.

Segmenti di pubblico personalizzati per intenzione

Gli intent personalizzati possono essere dichiarati in shortcuts.xml per attivare le funzionalità vocali nell'app che non corrispondono ai BII disponibili. Sebbene siano 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 pattern di query per un intent personalizzato.

• android:mimeType: tipo di parametro di un intent personalizzato. Questo campo non è obbligatorio per gli oggetti BII, in cui il tipo di parametro è noto. Per i parametri personalizzati per intent, deve essere dichiarato un tipo semantico supportato.

Per maggiori dettagli, consulta la sezione Intent personalizzati.