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".
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:
Nel file manifest della tua app (
AndroidManifest.xml
), trova un'attività i cui filtri intent sono impostati sull'azioneandroid.intent.action.MAIN
e sulla categoriaandroid.intent.category.LAUNCHER
.Aggiungi un riferimento a
shortcuts.xml
inAndroidManifest.xml
utilizzando un tag<meta-data>
inActivity
che dispone di filtri di intent sia perMAIN
sia perLAUNCHER
, 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 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.
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 parametrointent
predefiniti. Ad esempio, puoi dichiarare una scorciatoia dell'app "Avvia una corsa" che richiama la funzionalità BII diSTART_EXERCISE
nella tua app per l'attività fisica.Queste scorciatoie contengono gli attributi
intent
,shortLabel
elongLabel
, 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 uncapability
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 BIIexercise.name
della funzionalitàSTART_EXERCISE
. Se un'espressione utente corrisponde a un'entità, l'IDshortcutId
viene passato all'intent anziché il valore non elaborato della query dell'utente.Le scorciatoie di
Entity
non definiscono gli attributiintent
,shortLabel
olongLabel
e pertanto non vengono suggerite sulle piattaforme proattive. Per i dettagli, consulta Inventario incorporato per azioni app.
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> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
Applicabile solo per le chiamate di app in primo piano |
<parameter> |
<intent> |
|
<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.
<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 intentAction
. 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 inintent
.
<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"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
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.
<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 parametrointent
. 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 definirecontact_name
per il parametro BIImessage.recipient.name
.android:mimeType
: il mimeType del parametro, ad esempiotext/*
. 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 valoreintent
successivo definito percapability
.
<dati>
Associa un inventario web a una parameter
.
Attributo:
android:pathPattern
: pattern URL perentity
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 esempiomenuItem.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> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
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'attributoandroid:name
dicapability
a cui è associatoshortcut
. 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 BIIcapability
a cui associare questa scorciatoia. Ad esempio,foodObservation.aboutFood.name
.android:value
: il valore dientity
. Può essere un singoloentity
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'URLsameAs
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
etargetPackage
perintent
. 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'elementointent
. 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 diintent
.
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".
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.
Per maggiori dettagli, consulta Inventario web.
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.