Avviare un'app in primo piano con i comandi vocali di Cortana (HTML)

[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]

Oltre a usare i comandi vocali all'interno di Cortana per accedere alle funzionalità di sistema, puoi anche usare i comandi vocali tramite Cortana per avviare un'app in primo piano e specificare un'azione o un comando da eseguire all'interno dell'app.

Nota  

Un comando vocale è una singola parola o un enunciato con un intento specifico, definito in un file di definizione comando vocale (VCD, Voice Command Definition), indirizzato a un'app installata tramite Cortana.

La definizione di un comando vocale può avere complessità variabili. Può supportare qualsiasi cosa, da un singolo enunciato vincolato a una raccolta di enunciati in linguaggio naturale più flessibili, tutti con lo stesso intento.

Un file VCD definisce uno o più comandi vocali, ognuno con un intento univoco.

L'app di destinazione può essere avviata in primo piano (l'app assume lo stato attivo) o attivata in background (Cortana mantiene lo stato attivo ma fornisce risultati dall'app), a seconda del livello e della complessità dell'interazione. Ad esempio, i comandi vocali che richiedono ulteriore contesto o input dell'utente (come l'invio di un messaggio a un contatto specifico) vengono gestiti meglio in un'app in primo piano, mentre i comandi di base possono essere gestiti in Cortana tramite un'app in background.

Forniremo una dimostrazione di queste funzionalità con un'app per la pianificazione e la gestione dei viaggi denominata Adventure Works.

Per creare un nuovo viaggio in Adventure Works senza Cortana, un utente deve avviare l'app e passare alla pagina Nuovo viaggio. Per visualizzare un viaggio esistente, un utente deve avviare l'app, passare alla pagina Viaggi in programma e selezionare il viaggio.

Usando i comandi vocali tramite Cortana, l'utente può invece semplicemente dire "Adventure Works, aggiungi un viaggio" o "Aggiungi un viaggio in Adventure Works" per avviare l'app e passare alla pagina Nuovo viaggio. Dicendo invece "Adventure Works, mostra il mio viaggio a Londra", verrà avviata l'app e sarà visualizzata la pagina dei dettagli del viaggioqui raffigurata.

Questi sono i passaggi di base per aggiungere funzionalità dei comandi vocali e integrare Cortana nella tua app mediante input vocale o da tastiera:

1. Crea un file VCD. Si tratta di un documento XML in cui vengono definiti tutti i comandi vocali che l'utente può pronunciare per avviare le azioni o richiamare comandi quando attiva l'app. Vedi VCD elements and attributes v1.2.
2. Registra i set di comandi nel file VCD quando l'app viene avviata.
3. Gestisci l'attivazione tramite comando vocale, lo spostamento nell'app e l'esecuzione del comando.

Obiettivo: Apprendere come abilitare i comandi vocali in primo piano.

Prerequisiti

Se non hai familiarità con lo sviluppo di app mediante JavaScript:

Per completare questa esercitazione leggi gli argomenti seguenti per scoprire di più sulle tecnologie descritte qui.

• Installare Microsoft Visual Studio.
• Ottenere una licenza per sviluppatori. Per le istruzioni, vedi Sviluppare con Visual Studio 2013.
• Creare la prima app con JavaScript.
• Roadmap per app di Windows Store scritte in JavaScript
• Informazioni sugli eventi sono disponibili in Guida introduttiva: Aggiunta di controlli HTML e gestione degli eventi

Linee guida per l'esperienza utente:

Vedi le linee guida per la progettazione di Cortana per informazioni su come integrare la tua app con Cortana e le linee guida per la progettazione delle funzionalità vocali per trovare suggerimenti utili sulla progettazione di un'app pratica e coinvolgente abilitata per i comandi vocali.

1. Creare un file VCD

1. In Visual Studio fai clic con il pulsante destro del mouse sul nome del progetto, scegli Add->New Item e quindi seleziona File XML.
2. Digita un nome per il file VCD. Ad esempio, "AdventureWorksCommands.xml". Seleziona Aggiungi.
3. In Esplora soluzioni seleziona il file VCD.
4. Nella finestra Proprietà imposta l'azione di compilazione su Contenuto e quindi imposta Copia in directory di output su Copia se più recente.

2. Modificare il file VCD

Per ogni lingua supportata dall'app, crea un CommandSet di comandi vocali che l'app può gestire.

Ogni Command dichiarato in un file VCD deve includere queste informazioni:

• Un nome di comando usato dall'applicazione per identificare il comando vocale in fase di esecuzione

• Un elemento Example che contiene una frase che descrive in che modo un utente può richiamare il comando. Cortana mostra questo esempio quando l'utente pronuncia "Cosa posso dire?" o "Guida" oppure quando tocca Vedi altro.

• Un elemento ListenFor che contiene le parole e le frasi che l'app riconosce per avviare il comando. Ogni comando deve disporre di almeno un elemento ListenFor.

• Un elemento Feedback che contiene il testo visualizzato e pronunciato da Cortana all'avvio dell'applicazione.

• Un elemento Navigate con un attributo Target per indicare che il comando vocale deve avviare l'app in primo piano. Specifica un elemento VoiceCommandService se il comando vocale deve invece avviare l'app in background. Per altre informazioni, vedi [Estendibilità di Cortana].

Per altri dettagli, vedi la sezione VCD elements and attributes v1.2.

Puoi specificare versioni per più lingue dei comandi utilizzati per attivare l'app ed eseguire comandi. Puoi creare più elementi CommandSet, ciascuno con un attributo xml:lang diverso per usare l'app in paesi diversi. Ad esempio, un'app per gli Stati Uniti potrebbe avere un elemento CommandSet per l'inglese e un elemento CommandSet per lo spagnolo.

Attenzione  

Per attivare un'app e avviare un'azione usando un comando vocale, l'app deve registrare un file VCD contenente un elemento CommandSet con una lingua che corrisponde alla lingua dei comandi vocali che l'utente ha selezionato sul dispositivo. Questa lingua viene impostata dall'utente nella schermata Settings > System > Speech > Speech Language del dispositivo.

Ecco un file VCD che definisce un comando vocale per l'app Adventure Works.

Per questo esempio, CommandPrefix è impostato su "Adventure Works", Command, identificato da Name (" showTripToDestination"), specifica sia cosa può pronunciare l'utente che il feedback fornito da Cortana, ListenFor specifica il testo che può essere riconosciuto (con un riferimento a un elemento PhraseList che vincola le destinazioni riconosciute), Navigate indica che il comando vocale è gestito avviando l'app in primo piano e Feedback specifica cosa sentirà l'utente quando Cortana avvia l'app.

Gli elementi ListenFor non possono essere modificati a livello di codice. Tuttavia, gli elementi PhraseList associati agli elementi ListenFor possono essere modificati a livello di codice. Le applicazioni devono modificare il contenuto del PhraseList in fase di esecuzione, in base al set di dati generato mentre l'utente usa l'app. Vedi Come modificare in modo dinamico gli elenchi frasi VCD.

<?xml version="1.0" encoding="utf-8"?>
<VoiceCommands xmlns="https://schemas.microsoft.com/voicecommands/1.1">
  <CommandSet xml:lang="en-us" Name="AdventureWorksCommandSet_en-us">
    <CommandPrefix> Adventure Works, </CommandPrefix>
    <Example> Show trip London </Example>

    <Command Name="showTripToDestination">
      <Example> show trip to London  </Example>
      <ListenFor> show trip to {destination} </ListenFor>
      <Feedback> Showing trip to {destination} </Feedback>
      <Navigate/>
    </Command>

    <PhraseList Label="destination">
      <Item> London </Item>
      <Item> Dallas </Item>
      <Item> New York </Item>
    </PhraseList>

    <PhraseTopic Label="newDestination" Scenario="Search">
      <Subject>City/State</Subject>
    </PhraseTopic>
  </CommandSet>

<!-- Other CommandSets for other languages -->

</VoiceCommands>

3. Installare i comandi VCD

L'app deve essere seguita una volta per installare il set di comandi del file VCD.

All'attivazione dell'app, chiama InstallCommandSetsFromStorageFileAsync durante Launch per registrare i comandi che devono essere riconosciuti dal sistema.

Nota  Se viene eseguito il backup del dispositivo e l'app viene reinstallata automaticamente, i dati dei comandi vocali non vengono preservati. Per garantire che i dati dei comandi vocali dell'app rimangano intatti, puoi considerare di inizializzare il file VCD ogni volta che l'app viene avviata o si attiva oppure di memorizzare un'impostazione che indica se il file VCD è installato e verifica l'impostazione ogni volta che l'app viene avviata o si attiva.

Ecco un esempio che illustra come installare i comandi specificati da un file VCD (vcd.xml).

N/A

4. Gestire l'attivazione ed esecuzione dei comandi vocali

Dopo che l'app è stata avviata e i set di comandi vocali sono stati installati, specifica in che modo l'app deve rispondere alle successive attivazioni di comandi vocali. L'app potrebbe ad esempio passare a una pagina specifica di contenuti, visualizzare una mappa o un'altra utilità di navigazione oppure emettere un messaggio di conferma o di stato.

A tale scopo, devi:

1. Confermare che l'app sia stata attivata da un comando vocale.

   Nell'evento onactivated, controlla se activationKind è voiceCommand.

2. Stabilisci il nome del comando e ciò che è stato pronunciato.

   Ottieni un riferimento a un oggetto VoiceCommandActivatedEventArgs da IActivatedEventArgs e richiedi un oggetto speechRecognitionResult alla proprietà result.

   Per determinare ciò che è stato pronunciato dall'utente, controlla il valore di text o le proprietà semantiche della frase riconosciuta nel dizionario speechRecognitionSemanticInterpretation.

3. Esegui l'azione appropriata nell'app, in genere lo spostamento alla pagina pertinente.

Per questo esempio, facciamo di nuovo riferimento al file VCD nel passaggio 3: Edit the VCD file.

Dopo aver ottenuto il risultato del riconoscimento del comando vocale, recuperiamo il nome del comando dal primo valore nell'array rulePath. Poiché nel file VCD è stato definito più di un possibile comando vocale, dobbiamo confrontare il valore con i nomi dei comandi nel file VCD ed eseguire l'azione appropriata.

L'azione più comune che un'applicazione può eseguire è lo spostamento a una pagina con contenuti pertinenti per il contesto del comando vocale. Per questo esempio, ci spostiamo a una pagina TripPage e passiamo il valore del comando vocale, il modo in cui è stato immesso il comando e la frase "destination" riconosciuta (se applicabile). In alternativa, l'app può inviare un parametro di spostamento a speechRecognitionResult durante lo spostamento alla pagina.

Puoi scoprire se il comando vocale che ha avviato l'app è arrivato sotto forma di input vocale o di testo dal dizionario speechRecognitionSemanticInterpretation.properties, usando la chiave commandMode. Il valore della chiave sarà "voice" o "text". Se il valore della chiave è "voice", valuta se usare la sintesi vocale (Windows.Media.SpeechSynthesis) per fornire all'utente un feedback vocale.

Usa speechRecognitionSemanticInterpretation.properties per individuare il contenuto pronunciato in PhraseList o nei vincoli PhraseTopic di un elemento ListenFor. La chiave del dizionario è il valore dell'attributo Label dell'elemento PhraseList o PhraseTopic. Di seguito viene illustrato come accedere al valore della frase {destination}.

N/A

Riepilogo e passaggi successivi

In questa sezione abbiamo appreso come implementare comandi vocali di base mediante file VCD che devono essere avviati in primo piano da Cortana.

Successivamente, impareremo a implementare comandi vocali che visualizzano i risultati nel canvas di Cortana. Vedi Avviare un'app in background con i comandi vocali di Cortana (HTML).

In alternativa, vedi Come modificare in modo dinamico gli elenchi frasi VCD. Questo può essere utile se l'azione del comando vocale implica dati transitori generati durante l'uso dell'app.

Argomenti correlati

Interazioni con Cortana

Come definire vincoli di riconoscimento personalizzati

VCD elements and attributes v1.2

Progettisti

Linee guida per la progettazione di Cortana