Dopo aver identificato la funzionalità in-app e il corrispondente intent integrato
(BII) da implementare, dichiara gli intent integrati supportati dalla tua funzionalità definendo
un elemento capability
in un file di risorse shortcuts.xml
. Dichiarazione di un intent integrato
come capability
registra il supporto per quell'intent semantico nella tua app, e
consente il completamento dell'intent tramite query vocali utilizzando l'Assistente Google.
L'assistente usa l'elaborazione del linguaggio naturale per estrarre parametri da un utente
query. Il riferimento per intent integrati elenca i campi in cui viene inserito ogni intent integrato
in grado di estrarre da una query utente associata. Ad esempio, se un utente
richiama la funzionalità [actions.intent.GET_FOOD_OBSERVATION
][] nella tua app
dicendo "Hey Google, chiedi ad ExampleApp cosa ho mangiato a pranzo venerdì scorso", assistente
estrae i seguenti parametri dell'intent integrato dalla richiesta dell'utente:
foodObservation.forMeal
= "https://schema.googleapis.com/MealTypeLunch"foodObservation.startTime
= "06-09-2024T00:00:00"foodObservation.endTime
= "06-09-2024T23:59:59"
L'assistente passa i parametri dell'intent integrato al completamento intent
definito nell'
capability
. In una funzionalità possono essere definiti uno o più elementi intent
i diversi modi in cui un utente può richiamare un intent integrato. Ad esempio,
è possibile definire un intent
di completamento che richiede entrambi i parametri BII in
dall'esempio riportato sopra. Potresti quindi definire un secondo intent che richiede un singolo intent integrato
foodObservation.forMeal
, che riporta tutti i pasti in un determinato giorno, ad esempio "Hey Google, chiedi ad ExampleApp cosa ho mangiato a pranzo".
Panoramica
Configuri le Azioni app utilizzando un file shortcuts.xml
inserito nella tua app
directory res/xml
del progetto, quindi viene creato un riferimento a shortcuts.xml
nel file manifest dell'app. Aggiungi un riferimento a shortcuts.xml
nel file manifest dell'app
procedendo nel seguente modo:
Nel file manifest dell'app (
AndroidManifest.xml
), trova un'attività la cui i filtri per intent sono impostati sull'azioneandroid.intent.action.MAIN
e Categoriaandroid.intent.category.LAUNCHER
.Aggiungi un riferimento a
shortcuts.xml
inAndroidManifest.xml
utilizzando un Tag<meta-data>
inActivity
che ha un intent filtri sia perMAIN
che 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
Crea scorciatoie statiche nella documentazione per gli sviluppatori Android.
La raccolta Jetpack androidx.core:core:1.6.0
(o superiore) nel tuo progetto Android per evitare errori di compilazione
quando definisci le funzionalità delle Azioni app in shortcuts.xml
. Per maggiori dettagli, vedi
Guida introduttiva ad Android Jetpack.
Scorciatoie statiche
Quando definisci capability
, puoi dichiarare elementi shortcut
statici in
shortcuts.xml
per estendere la funzionalità della funzionalità. Scorciatoie statiche
vengono importati 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 Azioni app con scorciatoie statiche:
Scorciatoie delle funzionalità. Creare scorciatoie che avviano un'istanza di
capability
contenente valori di parametrointent
predefiniti. Ad esempio: puoi dichiarare la scorciatoia dell'app "Avvia una corsa" che richiama ilSTART_EXERCISE
Funzionalità degli intent integrati nella tua app per l'attività fisica.Queste scorciatoie contengono gli attributi
intent
,shortLabel
elongLabel
, 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 alle azioni può anche fungere da scorciatoia per un'entità, come descritto di seguito, associandolo acapability
tramite un Tag<capability-binding>
.Scorciatoie per le entità. Le scorciatoie delle entità forniscono un elenco dei parametri supportati valori per il completamento di query vocali di un
capability
. Ad esempio, un'entità scorciatoia con un elenco di tipi di allenamento ("escursionismo", "corsa" ecc.) associati alexercise.name
del parametro dell'intent integratoSTART_EXERCISE
funzionalità. Se un'espressione dell'utente corrisponde a un'entità, l'IDshortcutId
viene passato all'intent anziché al valore della query dell'utente non elaborato.Entity
scorciatoie non definisconointent
,shortLabel
olongLabel
che, in quanto tali, non sono suggeriti 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 suoi attributi sono obbligatori
a meno che non sia contrassegnato come "facoltativo".
Tag Shortcuts.xml | All'interno di | Attributi |
---|---|---|
<capability> |
<shortcuts> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
Applicabile solo per le chiamate di app in primo piano |
<parameter> |
<intent> |
|
<shortcut-fulfillment> |
<capability> |
Applicabile solo per l'inventario in linea |
<parameter> |
<shortcut-fulfillment> |
android:name |
<slice> |
<capability> |
Applicabile solo alle sezioni Android |
Descrizione 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. Ciascuna
L'elemento <capability>
nel file shortcuts.xml
deve fornirne almeno uno
<intent>
per gestire il completamento dell'azione.
Attributi:
android:name
: ID azione per intent integrato, ad esempio [actions.intent.GET_FOOD_OBSERVATION
][]). Per un elenco delle consulta il riferimento agli intent integrati.app:queryPatterns
: una risorsa array di query delle query previste dalla dell'utente per questo intento. Questo attributo è applicabile solo a: intent personalizzati, poiché gli intent integrati includono già modelli modi comuni in cui gli utenti esprimono le attività che stanno cercando di svolgere o le informazioni che cercano.
<intent>
Elemento intent
di Android che definisce il modo in cui deve essere una query dell'utente
mediante funzionalità in-app. Gli sviluppatori possono fornire più <intent>
in un capability
. L'assistente cerca di rispondere a una query dell'utente utilizzando
primo <intent>
in un capability
per cui tutti i parametri obbligatori sono
fornito.
Attributi:
android:action
: il tipoAction
di intent. Il valore predefinito èACTION_VIEW
.android:targetClass
: classe attività di destinazione, ad esempio:"com.example.exercise.ExerciseActivity"
android:targetPackage
: pacchetto contenente la classe attività target, per esempio:"com.example.exercise
android:data
: questo campo è stato sovrascritto da<url-template>
se questo tag viene dichiarato inintent
.
<modello-url>
Modello per la creazione di un URI del link diretto per essere aperti 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 di modello di URL HTTP, consulta la Articolo di Wikipedia sui modelli di URL. La è conforme alle specifiche del modello di URI RFC6570.
Di seguito sono riportati alcuni esempi di valori dei 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 fase di completamento.
<extra>
Definisce i dati aggiuntivi per un valore intent
. Per le Azioni app, questo campo viene utilizzato solo per
abilita [invocazione app in primo piano][] per capability
.
<parametro>
Mappa un parametro dell'intent integrato ai valori dei parametri di intent. Per ulteriori informazioni, vedi Dati dei parametri e corrispondenza.
Attributi:
android:name
: nome del parametro dell'intent integrato da associare a questointent
. Il nome deve essere un campo a livello di foglia del parametro dell'intent integrato (ad ad esempiofoodObservation.aboutFood.name
).android:key
: chiave definita dallo sviluppatore di un valore parametro dell'intent integrato. Ad esempio: potresti definirecontact_name
per l'intent integratomessage.recipient.name
.android:mimeType
: il tipo MIME del parametro, ad esempiotext/*
. Questo è 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 prossimointent
definito percapability
.
<scorciatoia-fulfillment>
Specifica che un intent
definito in una scorciatoia per l'inventario in linea per un
il parametro specificato per il completamento.
Per maggiori dettagli, consulta Completamento con intent delle scorciatoie.
<parametro> (per <shortcut-fulfillment>
)
Attributo facoltativo che mappa un singolo parametro dell'intent integrato all'inventario in linea completamento della scorciatoia. Per maggiori dettagli, consulta Completamento con intent delle scorciatoie.
Attributo:
android:name
: nome del parametro dell'intent integrato da associare all'inventario in linea completamento della scorciatoia. Il nome deve essere un campo a livello foglia dell'intent integrato (ad esempiomenuItem.name
).
<sezione>
Consente all'assistente di incorporare il risultato di una query corrispondente a questo capability
come
sezione Android. Per maggiori dettagli, vedi
Integrare le Azioni app con Android Slices.
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 indicati come "facoltativo".
Tag Shortcuts.xml | All'interno di | Attributi |
---|---|---|
<shortcut> |
<shortcuts> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
Applicabile solo per la corrispondenza dei parametri enum. |
Descrizione schema della scorciatoia
Questa sezione descrive gli elementi dello schema shortcut
.
<scorciatoia>
Un <shortcut>
Android definito in shortcuts.xml
con determinati attributi pertinenti per le azioni di app. Valori stringa per shortcutShortLabel
e shortcutLongLabel
di campi viene fatto riferimento tramite
risorse stringa.
Attributi:
android:shortcutId
: identificatore per questa scorciatoia.android:shortcutShortLabel
: risorsa stringa che rappresenta una breve scorciatoia a frase. Ad esempio,"@string/callDavidShort"
che rappresenta il valore "Chiamata David".android:shortcutLongLabel
: risorsa stringa che rappresenta una scorciatoia lunga a frase. Ad esempio,"@string/callDavidLong"
che rappresenta il valore "Rendi a Davide".
<intent>
Intent Android associato a questa scorciatoia. Questo intent
viene eseguito quando
l'utente avvia questa scorciatoia tramite comandi vocali o tocco.
shortcut
attributi per intenzione sono identici a capability
intent
attributi.
<capability-binding>
Associa un shortcut
ad Azioni app capability
. Aggiunta di questo elemento a
shortcut
consente il completamento vocale utilizzando Assistant
.
Attributi:
android:key
: l'attributoandroid:name
delcapability
a cui è associato questoshortcut
. Ad esempio:actions.intent.START_EXERCISE
.
<parameter-binding>
Attributo facoltativo che associa shortcut
a un singolo parametro di un'app
Azioni capability
. Se viene definito un parameter-binding
per un shortcut
, il valore
può essere utilizzata per fornire un'entità di inventario in linea a un parametro dell'intent integrato.
Per ulteriori dettagli, consulta Inventario in linea per App Actions.
Attributi:
android:key
: il nome del parametro dell'intent integratocapability
da associare questa scorciatoia. Ad esempio,exercise.name
.android:value
: il valore dientity
. Può essere un singoloentity
o un dell'elenco delle risorse.
<extra>
Il gruppo di dati extra
per la scorciatoia. sameAs è l'unico dato
pertinente agli elementi shortcut
delle Azioni app. L'URL sameAs si riferisce a una
pagina web di riferimento che identifica in modo inequivocabile l'entità. Utilizzato per specificare
valore enum 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'URLsameAs
Per maggiori dettagli, consulta Corrispondenza dei valori dei parametri enumerati.
Opzioni di completamento dell'intent
Devi definire gli elementi intent
in un <capability>
per dichiarare in che modo l'assistente
Risponde o completa i comandi vocali dell'utente corrispondenti a quella funzionalità. Là
sono disponibili diversi modi per configurare il modo in cui un intent
avvia una destinazione di evasione
nell'app, a seconda di come è strutturata la navigazione.
Sono disponibili le seguenti opzioni di evasione degli ordini:
Intent espliciti: avvia un componente dell'app specifico definendo gli attributi
targetClass
etargetPackage
perintent
. Questo è il metodo di completamento delle Azioni app consigliato.Link diretti. Avvia le destinazioni delle app utilizzando i link diretti di Android definendo un tag
<url-template>
nell'elementointent
. Questo è utile se la navigazione nell'app si basa già su link diretti.Dati relativi all'intent: puoi fornire un URI di fulfillment nel
intent
android:data
. Questo campo è sovrascritto dai dati di<url-template>
se questo tag è definito anche inintent
.
Dati dei parametri e corrispondenza
Per impostazione predefinita, l'assistente invia i parametri degli intent integrati estratti dalla query dell'utente al tuo
come dati di extra
di Android intent
definiti in capability
.
In alternativa, puoi dichiarare un tag <url-template>
nella
capability
che contiene segnaposto per i parametri dinamici. Questo modello
viene mappato a una delle tue attività Android utilizzando un URL del link alle app,
uno schema personalizzato o un URL basato sull'intent.
Utilizzo degli extra per intent
L'esempio seguente mostra un intent esplicito definito per un capability
distribuzione:
<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 sopra, 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 = "exercise"
, value = "Running"
.
Utilizzo di 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 Android
link diretti per il fulfillment. Nell'esempio seguente viene definito 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 sopra, per una query utente del tipo "Hey Google, ordina un latte macchiato". da ExampleApp", l'app riceve l'URL generato: "myapp://start?exercise=Running".
Per mappare il parametro dell'intent integrato a una posizione nell'URL, utilizza la classe
Attributo android:name
del tag <parameter>
. Questo attributo
corrisponde al valore android:key
nel modello di URL che vuoi
sostituire con informazioni fornite dall'utente. Il valore android:key
deve essere presente
in <url-template>
e tra parentesi graffe ({}
).
Crea corrispondenze con i valori dei parametri enumerati
Alcuni parametri dell'intent integrato forniscono valori enumerati all'intento di completamento,
Ad esempio, i valori di testo supportati dell'intent integrato RECORD_FOOD_OBSERVATION
. Per
questi parametri, l'assistente abbina la query dell'utente ("Colazione") a un
entità il cui valore sameAs
corrisponde all'URL dello schema enum
(https://schema.googleapis.com/MealTypeBreakfast
). Per associare l'enum
per un elemento entity
supportato, dichiari un'associazione sameAs
in
il tuo shortcut
. L'esempio seguente mostra un'associazione sameAs
per un
scorciatoia 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 un
corrispondenza per "colazione" pasto, il seguente Extra viene inviato con
evasione degli ordini 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 degli intent integrati, puoi usare le scorciatoie per guidare le entità
a un insieme di entità supportate specificate in shortcuts.xml
, noto come
inventario in linea. Per maggiori dettagli, vedi Inventario incorporato.
Segmenti di pubblico personalizzati per intenzione
Gli intent personalizzati per intent possono essere dichiarati in shortcuts.xml
per consentire l'attivazione vocale delle funzionalità in
dell'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 la modelli di query diversi per un intent personalizzato.android:mimeType
: tipo di parametro di un intent personalizzato. Questo campo è non richiesto per gli intent integrati, 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.