Quando implementi Azioni app per la tua app Android, potresti dover gestire le richieste che sono varianti di un tema. Ad esempio, supponiamo che la tua app per l'attività fisica implementi l'intent integrato (BII) di START_EXERCISE
per consentire agli utenti di avviare una vasta gamma di allenamenti chiedendo all'assistente cose come
"Hey Google, avvia una corsa sull'app di esempio".
Per soddisfare questo intent, è necessaria la logica di corrispondenza della richiesta per gestire ogni tipo di esercizio, incluse varianti come "corsa", "sprint" o "gara". Questa logica diventa rapidamente ingombrante man mano che gli esercizi supportati aumentano.
Per gli BII supportati, come START_EXERCISE
, puoi evitare questa complessa logica di corrispondenza
utilizzando un inventario in linea. Un inventario in linea è un insieme di scorciatoie
statiche per Android definite in shortcuts.xml
che rappresentano funzionalità e contenuti
nella tua app.
Ogni scorciatoia contiene un identificatore di elemento e un elenco di sinonimi che rappresentano varianti di come gli utenti potrebbero fare riferimento all'elemento. Durante la chiamata, BII confronta il parametro BII fornito dall'utente con l'elenco di sinonimi. Quando viene trovata una corrispondenza, il parametro BII viene aggiornato all'identificatore di elemento della scorciatoia corrispondente.
Un inventario in linea consente all'Assistente Google di semplificare i valori dei parametri BII forniti all'applicazione durante le chiamate di un'Azione app.
Gli inventari incorporati funzionano come tabelle di ricerca per i parametri BII, esprimendo la varietà di modi in cui gli utenti fanno riferimento alle funzionalità o ai contenuti della tua app utilizzando gli identificatori degli elementi da te definiti. Semplificano la logica di corrispondenza delle richieste dell'app consentendo ai tuoi fulfillment di anticipare gli identificatori degli articoli dai parametri BII.
![Diagramma di flusso utente per l'inventario in linea](https://developer.android.google.cn/static/guide/app-actions/images/appactions-inline-inventory-flow.png?authuser=5&hl=it)
START_EXERCISE
che utilizza un
inventario in linea per interpretare i nomi degli allenamenti forniti dall'utente per i tipi di
esercizi supportati nell'app.
Limitazioni e alternative
Le scorciatoie per l'inventario in linea presentano le seguenti limitazioni:
- Limite di scorciatoie: per ogni app è possibile definire un massimo di 1000 scorciatoie incorporate per l'inventario.
- Limite di sinonimi: ogni scorciatoia per l'inventario in linea può contenere al massimo 20 valori sinonimi.
- Definizione statica: le scorciatoie per l'inventario in linea vengono dichiarate in modo statico in
shortcuts.xml
e possono essere aggiornate per i tuoi utenti solo pubblicando una nuova versione dell'app.
Dato il requisito della configurazione statica, un inventario in linea è più adatto per estendere all'assistente informazioni sulle app non personalizzate e che cambiano raramente, ad esempio voci del menu, percorsi degli autobus o dimensioni delle bevande. Per altri tipi di contenuti, prendi in considerazione le seguenti alternative:
Inventario web: consente all'assistente di eseguire query su contenuti web pubblici quando associa le query degli utenti agli identificatori di contenuti dell'app supportati. Le query dell'inventario web vengono eseguite in tempo reale durante una chiamata, consentendoti di estendere all'assistente cataloghi di prodotti, post sui social media e altri contenuti che vengono aggiornati di frequente.
Scorciatoie dinamiche: estendono un inventario di contenuti personalizzati delle app all'assistente. Le scorciatoie dinamiche consentono agli utenti di riprodurre rapidamente le azioni comuni, come riordinare la bevanda preferita da un'app per ordinare cibo o aprire una lista della spesa in un'app per prendere appunti.
Creare un inventario in linea
L'inventario in linea semplifica lo sviluppo offrendo all'assistente un modo pratico per tradurre i diversi modi in cui gli utenti richiedono i contenuti e le funzionalità della tua app negli identificatori prevedibili previsti dalla tua applicazione. Ad esempio, supponiamo che la tua app offra diversi esercizi che gli utenti possono iniziare a utilizzare la propria voce e che l'app si aspetta che gli utenti facciano le seguenti richieste per lo stesso tipo di allenamento:
- Hey Google, avvia una corsa sull'app di esempio.
- Hey Google, inizia a correre sull'app di esempio.
Nella scorciatoia dell'inventario incorporato, imposti shortcutId
su "CARDIO_RUN"
, l'identificatore dell'allenamento previsto dalla tua app. Dopodiché specifichi "corsa" e "corsa" come sinonimi associati a shortcutId
. Quindi, quando un utente attiva l'Azione app con le query precedenti, l'assistente utilizza l'identificatore "CARDIO_RUN"
per il parametro BII durante la generazione di un intent di fulfillment.
Il seguente snippet di un file app/res/shortcuts.xml
di esempio implementa questo caso:
<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>
<shortcut android:shortcutId="CARDIO_RUN">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/run_names" />
</capability-binding>
</shortcut>
Nell'esempio precedente, l'inventario in linea shortcut
dichiara un tag <parameter-binding>
all'interno di un elemento <capability-binding>
, associandolo al parametro BII exercise.name
definito in <capability>
.
La risorsa array di stringhe @array/run_names
specifica un elenco di sinonimi in res/values/arrays.xml
che l'assistente riconosce e mappa all'ID elemento "CARDIO_RUN"
:
<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
<string-array name="run_names">
<item>Run</item>
<item>Jog</item>
<item>Sprint</item>
</string-array>
</resources>
Quando viene fornito un valore <url-template>
per la funzionalità, il valore shortcutId
di un valore corrispondente viene inserito nell'URL generato in corrispondenza del segnaposto corrispondente per il parametro. Il seguente codice tratto da un file app/res/shortcuts.xml
di esempio implementa questo caso:
<capability android:name="actions.intent.START_EXERCISE">
<intent>
<url-template android:value="myapp://workout{?exercise}" />
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
<shortcut android:shortcutId="CARDIO_RUN">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/run_names" />
</capability-binding>
</shortcut>
Nell'esempio precedente, l'assistente genera il link diretto per il fulfillment
myapp://workout?exercise=CARDIO_RUN
.
Evasione dell'ordine con intent di scorciatoia
Per impostazione predefinita, una scorciatoia fornisce il shortcutId
di un valore di inventario in linea corrispondente al valore intent
del capability
a cui è associata la scorciatoia, come dichiarato nel tag <capability-binding>
della scorciatoia. In alternativa, puoi specificare in alternativa l'utilizzo di un elemento intent
definito nella scorciatoia stessa per il fulfillment, aggiungendo un tag <shortcut-fulfillment>
a capability
.
Il seguente codice di un file app/res/shortcuts.xml
di esempio implementa il fulfillment della scorciatoia:
<capability android:name="actions.intent.START_EXERCISE">
<shortcut-fulfillment>
<parameter android:name="exercise.name"/>
</shortcut-fulfillment>
</capability>
<shortcut android:shortcutId="CARDIO_RUN">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/run_names" />
</capability-binding>
<intent android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.ExerciseActivity">
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</shortcut>
Nell'esempio precedente, se la query dell'utente corrisponde a un valore dell'inventario in linea per il parametro exercise.name
, il tag <shortcut-fulfillment>
specifica che il intent
della scorciatoia associata viene utilizzato per il completamento.
Inventario in linea per funzionalità BII aperta per app
Sebbene l'inventario in linea sia in genere una funzionalità facoltativa per gli oggetti BII che lo supportano, è necessario per alcuni BII, come OPEN_APP_FEATURE
. Questo
BII di uso comune consente agli utenti di creare link diretti a funzionalità specifiche dell'app
utilizzando l'assistente.
La funzionalità BII aperta dell'app richiede un inventario incorporato di nomi di funzionalità dell'app per verificare l'esistenza di una funzionalità richiesta dall'utente prima di collegare l'utente direttamente alla tua app.
Il seguente codice di un file app/res/shortcuts.xml
di esempio implementa questo BII con un'unica scorciatoia che rappresenta la funzionalità dello stato degli ordini dell'app:
<capability android:name="actions.intent.OPEN_APP_FEATURE">
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.MyClass">
<parameter
android:name="feature"
android:key="featureParam" />
</intent>
<!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.MyClass">
<parameter
android:name="HOME_SCREEN"
android:key="featureParam" />
</intent>
</capability>
<!-- Inline inventory for OPEN_APP_FEATURE. -->
<shortcut android:shortcutId="ORDER_STATUS">
<capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
<parameter-binding
android:key="feature"
android:value="@array/order_status_names" />
</capability-binding>
</shortcut>
Le risorse array di stringhe in res/values/arrays.xml
, @array/order_status_names
, specificano un elenco di sinonimi per questa funzionalità:
<resources>
<string-array name="order_status_names">
<item>Order status</item>
<item>Orders</item>
<item>Order history</item>
</string-array>
</resources>
Con la funzionalità precedente attiva, l'assistente può rispondere a una serie di frasi per la stessa funzionalità:
- "Hey Google, mostra lo stato dell'ordine nell'app di esempio."
- "Hey Google, mostra i miei ordini nell'app di esempio."
- "Hey Google, mostra la mia cronologia ordini nell'app di esempio."
Testare l'inventario in linea
Testa l'inventario ispezionando i valori del parametro BII forniti dall'assistente alla tua applicazione, soddisfacendo al contempo le funzionalità pertinenti di Azioni app. Un inventario in linea funziona sostituendo il valore fornito dall'utente di un parametro BII associato all'inventario con il valore shortcutId
di una scorciatoia per l'inventario in linea corrispondente.
Ad esempio, una funzionalità BII START_EXERCISE
potrebbe utilizzare un inventario in linea per tradurre il parametro BII fornito dall'utente "run" nell'ID esercizio corrispondente, "CARDIO_RUN"
.
Il plug-in dell'Assistente Google ti consente di visualizzare l'anteprima del tuo inventario in linea con le azioni nell'assistente su un dispositivo di prova. Testa l'inventario utilizzando il plug-in seguendo questi passaggi:
- Configura i parametri legati all'inventario per le funzionalità BII con valori sinonimi associati all'inventario in linea.
- Attiva lo standard BII dal plug-in, richiamandolo sul dispositivo di test.
- Controlla i valori parametro risultanti che l'assistente fornisce alla tua applicazione durante il fulfillment dell'Azione app.