Inventario in linea

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.

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:

1. Configura i parametri legati all'inventario per le funzionalità BII con valori sinonimi associati all'inventario in linea.
2. Attiva lo standard BII dal plug-in, richiamandolo sul dispositivo di test.
3. Controlla i valori parametro risultanti che l'assistente fornisce alla tua applicazione durante il fulfillment dell'Azione app.