Inventario web

Con Azioni app, gli utenti possono accedere direttamente ai contenuti della tua app dicendo, ad esempio, "Hey Google, mostrami il menu di Three Dot Cafe su ExampleApp". Questa funzionalità si chiama link diretti e può aiutare gli utenti a completare più facilmente le attività con la tua app.

Per soddisfare questo tipo di richiesta, l'Assistente Google genera un link diretto ai contenuti corrispondenti nella tua app. Se gestisci attivamente il tuo sito web con informazioni sui contenuti o sui prodotti e i link diretti in-app sono organizzati in base a questi contenuti web pubblici, puoi configurare l'assistente in modo che recuperi gli URL per l'evasione dell'azione dal tuo sito web utilizzando un inventario web.

Un inventario web è la posizione del sito web degli URL degli elementi supportati dalla tua app. Quando un utente richiama l'Azione app, l'assistente abbina la query dell'utente, ad esempio "Three Dot Cafe", agli URL corrispondenti nell'indice della Ricerca Google del sito web specificato nella sezione shortcuts.xml per la tua app Android.

Vantaggi

L'inventario web offre vantaggi per le app con elenchi di articoli estesi e regolarmente aggiornati che gli utenti visualizzano o ordinano nell'app:

  • I dati dell'inventario web si trovano sul tuo sito web, a differenza dei dati dell'inventario in linea, che archivia gli elenchi di articoli nella tua app. Consentire all'assistente di accedere ai dati web evita il rischio di dati di inventario in linea inattivi, che possono essere aggiornati solo pubblicando una nuova versione dell'app.

  • Le scorte in linea sono limitate a 1.000 articoli. Al contrario, un inventario web non ha limiti per gli articoli e può crescere con le tue esigenze.

  • Un inventario web può semplificare la logica dell'app consentendo al fulfillment di gestire solo URL di contenuti prevedibili recuperati dal tuo sito web. Al contrario, se non è configurato un inventario, l'assistente genera link diretti per il completamento mappando i parametri di intent alle variabili in un modello di URL. Il tuo fulfillment dovrà quindi analizzare questo URL generato dinamicamente per determinare se un utente ha richiesto un'entità supportata nella tua app.

Come funziona

Durante un'azione app, l'assistente crea link diretti ai contenuti dell'app tramite gli intent integrati che definisci in shortcuts.xml. L'assistente utilizza l'elaborazione del linguaggio naturale per identificare gli elementi pertinenti nella richiesta di un utente e li estrae in parametri BII. L'assistente genera quindi un link diretto utilizzando i parametri, in base alla configurazione di fulfillment in shortcuts.xml..

Sono disponibili tre metodi per generare link diretti per il fulfillment:

  • Mappatura dei parametri: mappa i parametri di intent ai segnaposto in un modello di URL di fulfillment.
  • Inventario incorporato: associa i parametri per intent a un elenco di entities supportati definiti nell'app.
  • Inventario web: abbina i parametri di intent ai contenuti trovati nell'indice di ricerca di Google di un sito web.

Un inventario web è un pattern URL del sito web definito dallo sviluppatore, come https://www.exampleapp.com/restaurants/.*, che rappresenta un insieme di entità supportato da un'app.

Se per un inventario web è configurato un parametro BII, l'assistente invia una query sul sito web per eseguire una corrispondenza di entità alla query dell'utente. L'assistente quindi trasmette al fulfillment i risultati URL corrispondenti al pattern URL configurato, come https://www.exampleapp.com/restaurants/three-dot-cafe.

Figura 1. Un esempio di query dell'assistente che utilizza l'inventario web per recuperare un articolo dell'entità ristorante.

Intent integrati supportati

L'inventario web è supportato, per determinati parametri di intent, dai seguenti BII:

  • [actions.intent.CREATE_REVIEW]
  • [actions.intent.GET_NEWS_ARTICLE]
  • [actions.intent.GET_REVIEW]
  • [actions.intent.GET_THING]
  • [actions.intent.ORDER_MENU_ITEM]
  • [actions.intent.GET_EXERCISE_PLAN]
  • [actions.intent.GET_DIGITAL_DOCUMENT]
  • [actions.intent.GET_ITEM_LIST]
  • [actions.intent.GET_OFFER]
  • [actions.intent.CREATE_OFFER]
  • [actions.intent.GET_PRODUCT]
  • [actions.intent.UPDATE_CART]
  • [actions.intent.CREATE_SOCIAL_MEDIA_CONNECTION]
  • [actions.intent.GET_IMAGE_OBJECT]
  • [actions.intent.GET_SOCIAL_MEDIA_POSTING]
  • [actions.intent.GET_SOCIAL_MEDIA_PROFILE]
  • [actions.intent.CREATE_TAXI_RESERVATION]
  • [actions.intent.CREATE_FLIGHT_RESERVATION]
  • [actions.intent.CREATE_LODGING_RESERVATION]
  • [actions.intent.GET_LOCAL_BUSINESS]
  • [actions.intent.GET_RESERVATION]
  • [actions.intent.UPDATE_RESERVATION]

Aggiungi inventario web

Dopo aver identificato uno BII supportato, puoi attivarlo per l'inventario web aggiornando shortcuts.xml con i dettagli del tuo sito web. Il file shortcuts.xml è una risorsa nel progetto Android in cui definisci i BII mappati alla funzionalità della tua app e il modo in cui ogni BII deve generare link diretti da soddisfare per la tua app. Per scoprire di più su shortcuts.xml, vedi Crea shortcuts.xml.

Per utilizzare l'inventario web per uno BII supportato:

  1. Nel file shortcuts.xml della tua app, aggiungi un tag <capability> con un attributo android:name impostato sul nome di uno BII che gestisci con l'inventario web, ad esempio: actions.intent.ORDER_MENU_ITEM.

  2. Nel tag <capability>, aggiungi un tag <intent> con un attributo android:action impostato sul nome della vista che deve essere attivata da questo intent.

  3. Nello stesso tag <intent>, aggiungi un tag <parameter> e imposta il relativo attributo android:name sul parametro BII che corrisponde il più possibile all'entità descritta nelle tue pagine web. Ad esempio, quando fornisci l'inventario web per ORDER_MENU_ITEM, devi collegare le pagine del menu a menuItem.name.

  4. Nel nuovo tag <parameter>, aggiungi un tag <data> e imposta il relativo attributo android:pathPattern sul pattern URL del percorso da utilizzare per l'inventario web.

Se configuri shortcuts.xml seguendo questa procedura, l'assistente può recuperare i contenuti web dall'indice della Ricerca Google del pattern URL che hai fornito nell'attributo android:pathPattern. L'assistente fornisce quindi un valore URL al fulfillment utilizzando i risultati corrispondenti al pattern del percorso dell'URL che hai definito. L'app indirizza poi l'utente a un punto specifico dell'app in base ai dati dell'URL forniti dall'assistente.

Ad esempio, il tuo sito web contiene schede di prodotto che utilizzano un percorso dell'URL che inizia con https://www.examplecafe.com/items/. Tu utilizzi il valore https://www.examplecafe.com/items/.* di pathPattern e l'assistente utilizza questo pattern URL in una ricerca web per trovare un URL di evasione degli ordini, ad esempio https://www.examplecafe.com/items/item123.

Se l'assistente trova un URL di inventario web corrispondente, fornisce l'URL nel campo <data> dell'intent di evasione, come se si trattasse di un link diretto. Utilizza il metodo getData() dell'intent per ottenere l'URL come oggetto Uri. L'attività dell'app che riceve l'intent è responsabile dell'interpretazione dell'URL e dell'attivazione dell'interfaccia utente dell'app appropriata.

Esempio di shortcuts.xml

Il seguente esempio definisce un BII ORDER_MENU_ITEM che fornisce un inventario web per restituire i risultati URL per le richieste contenenti il parametro BII menuItem.name:

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.ORDER_MENU_ITEM">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.OrderMenuItemActivity">
      <!-- Define URL match pattern in the pathPattern data field -->
      <parameter android:name="menuItem.name">
        <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
      </parameter>
    </intent>
  </capability>
</shortcuts>

Nell'esempio precedente, è specificato un pathPattern per menuItem.name, indicando all'assistente di restituire solo gli URL corrispondenti al pattern URL: https://www.examplecafe.com/items/.*

Altri shortcuts.xml esempi di BII che supportano l'inventario web sono disponibili nella documentazione di riferimento.

Gestisci gli elementi di riserva per i risultati mancanti

Nelle situazioni in cui i risultati dell'inventario web non vengono restituiti al fulfillment, l'app deve implementare una logica di fallback per completare l'azione con la migliore esperienza utente possibile. Le situazioni che comportano risultati mancanti includono:

  • Parametro di intent mancante: l'utente ha omesso un parametro previsto nella query oppure l'assistente non ha capito il parametro nella richiesta dell'utente.
  • Risultato URL mancante: l'assistente non è riuscito a trovare sul tuo sito web un'entità corrispondente alla query dell'utente.

Puoi gestire i valori dei parametri mancanti definendo più elementi <intent> per una funzionalità. Se l'assistente non riesce a soddisfare il primo intent, torna a quello successivo e così via.

Gli intent di riserva non devono richiedere parametri. Devono invece soddisfare la funzionalità con un link diretto più generico, come la visualizzazione dei risultati di ricerca per la query dell'utente.

Nel seguente esempio shortcuts.xml, un ORDER_MENU_ITEM BII definisce due fulfillment: il primo prevede un URL dal parametro menuItem.name. Il secondo non richiede parametri, indirizzando l'utente a una pagina in cui sono mostrate tutte le voci di menu.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
    </parameter>
  </intent>
  <!-- Fallback intent with no required parameters -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ViewMenuActivity">
    <url-template android:value="myapp://app.examplecafe.com/menu/all-items" />
  </intent>
</capability>

Nelle situazioni in cui un URL dell'inventario web non viene restituito, i contenuti della query dell'utente possono comunque essere utilizzati in intent di riserva, ad esempio per visualizzare i risultati di ricerca.

Nel seguente esempio shortcuts.xml, sono definiti due elementi intent:

  1. Il primo richiede un link diretto all'inventario web dal parametro menuItem.name.
  2. Se non viene restituito un link diretto, il secondo intent mostra i risultati di ricerca, utilizzando la query dell'utente da menuItem.name, se presente.
<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- Fallback intent displaying search results, using "menuItem.name" -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.SearchMenuActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Aggiungi la ricerca in-app con l'inventario web

Puoi consentire agli utenti di cercare contenuti web nella tua app combinando l'inventario web con un'implementazione di actions.intent.GET\_THING BII.

Questo BII cerca contenuti o entità utilizzando la funzionalità di ricerca in-app predefinita in un'app, attivando query come "Hey Google, mostrami le escursioni a cascata su SampleApp". Se configuri l'inventario web per il parametro delle funzionalità thing.name trasmesso dallo BII di GET_THING, i risultati delle entità corrispondenti del tuo sito web vengono passati per il completamento.

Per gli esempi di shortcuts.xml di inventario web, consulta la documentazione di riferimento di GET\_THING BII.

Test dell'inventario web

Quando definisci un inventario web per un fulfillment BII, l'assistente genera un link diretto utilizzando i risultati web corrispondenti al pattern urlTemplate definito per il parametro BII specificato. Se non è possibile trovare un risultato dell'inventario web, l'assistente genera un URL corrispondente al pattern urlTemplate del tuo intent di riserva. Puoi testare l'implementazione dell'inventario web verificando che i link forniti dall'assistente siano URL corrispondenti ai pattern urlTemplate del tuo inventario web.

Nel seguente esempio di BII ORDER_MENU_ITEM, l'assistente genera link di evasione dell'inventario web corrispondenti al pattern urlFilter specificato nel parametro menuItem.name, ad esempio: https://www.examplecafe.com/items/nuggets. Il secondo intent prende il valore di menuItem.name ed esegue una ricerca se il primo intent non corrisponde al pattern URL.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <!-- web inventory fulfillment -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- search intent -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MenuSearchActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Utilizza lo strumento Test Azioni app per testare l'inventario web su un dispositivo fisico o virtuale.

Per utilizzare lo strumento di test, procedi nel seguente modo:

  1. Collega il dispositivo di test all'app in esecuzione.
  2. In Android Studio, vai a Strumenti > Azioni app > Strumento di test di Azioni app.
  3. Fai clic su Crea anteprima.
  4. In Android Studio, esegui l'app sul dispositivo di test.
  5. Usa l'app Assistente sul dispositivo di test per testare l'Azione app. Ad esempio, puoi dire ad esempio "Hey Google, ordina delle pepite su ExampleCafe".
  6. Osserva il comportamento della tua app o utilizza il debugger di Android Studio per verificare il risultato dell'azione desiderato.