Coinvolgi gli utenti con l'Azione per l'Assistente Google

1. Panoramica

Attenzione: le azioni di conversazione verranno ritirate il 13 giugno 2023. Per saperne di più, vedi Disattivazione delle azioni di conversazione.

Actions on Google è una piattaforma per sviluppatori che ti consente di creare software per estendere le funzionalità di Assistente Google, l'assistente personale virtuale di Google, su più di un miliardo di dispositivi, tra cui smart speaker, telefoni, auto, TV, cuffie e altro ancora. Gli utenti interagiscono con l'assistente in una conversazione per svolgere diverse attività, ad esempio fare la spesa o prenotare una corsa. Per un elenco completo delle possibili, consulta la directory delle azioni. In qualità di sviluppatore, puoi utilizzare Actions on Google per creare e gestire facilmente esperienze di conversazione piacevoli ed efficaci tra gli utenti e il tuo servizio di terze parti.

Questo è un modulo di codelab avanzato, rivolto ai lettori che hanno già esperienza nella creazione di azioni per l'Assistente Google. Se non hai già avuto esperienza di sviluppo con Actions on Google, ti consigliamo vivamente di familiarizzare con la piattaforma seguendo i nostri codelab introduttivi ( Livello 1, Livello 2 e Livello 3). Questi moduli avanzati ti guideranno attraverso una serie di funzionalità che possono aiutarti a espandere la funzionalità della tua azione e ad ampliare il tuo pubblico.

Un modo importante per misurare il successo di un'azione è il coinvolgimento degli utenti o l'efficacia dell'azione nel far tornare gli utenti dopo la prima interazione. Per semplificare questa operazione, puoi implementare diverse funzionalità nell'azione che consentono agli utenti di tornare alla conversazione.

Il codelab tratta le funzionalità di coinvolgimento degli utenti e le best practice per Actions on Google.

Cosa devi creare

Puoi migliorare una funzione che è già stata creata consentendo di:

• Invia agli utenti un aggiornamento giornaliero che possono toccare per parlare con l'azione
• Inviare notifiche push agli utenti che rimandano all'azione
• Crea un link che indirizzi gli utenti alla tua azione da un browser web per dispositivi mobili

Obiettivi didattici

• Che cos'è il coinvolgimento degli utenti e perché è importante per il successo di un'azione
• Come modificare un'azione per aumentare il coinvolgimento dell'utente
• Quali funzionalità di coinvolgimento degli utenti utilizzare in diversi tipi di azioni
• Come usare l'API Actions per inviare notifiche tramite l'assistente

Che cosa ti serve

Devi disporre dei seguenti strumenti:

• Un editor IDE/text di tua scelta, ad esempio WebStorm, Atom o Sublime
• Un terminale per eseguire i comandi della shell con Node.js, npm e git installati
• Un browser web, ad esempio Google Chrome
• Un ambiente di sviluppo locale con l'interfaccia a riga di comando di Firebase
• Un dispositivo mobile (Android o iOS) con l'assistente. Per creare questo progetto, devi aver eseguito l'accesso all'assistente con lo stesso Account Google che utilizzerai.

Consigliamo inoltre di acquisire familiarità con JavaScript (ES6) anche se non è necessario per comprendere il codice webhook.

2. Configura il progetto

Questa sezione mostra come aggiungere funzionalità di coinvolgimento degli utenti a un'azione completata e creata in precedenza.

Parole chiave:

• Coinvolgimento utenti: la metrica utilizzata per misurare se gli utenti trovano valore in un prodotto o un servizio. Il coinvolgimento può essere rappresentato dal numero di utenti che ritornano all'azione, ovvero una metrica utilizzata per determinare se promuovere o meno un'azione. Il coinvolgimento elevato degli utenti proviene da due componenti di un'azione: informazioni utili che gli utenti vogliono vedere in un secondo momento e modi in cui possono tornare all'azione quando hanno maggiori probabilità di recuperarle.

Comprendere il campione

L'esempio di questo codelab è una semplice azione per una palestra fittizia denominata "Action Gym." L'azione fornisce informazioni sulla palestra, incluso un elenco di lezioni che ruotano ogni giorno. Un'azione informativa come questa è adatta a tutte le funzionalità di coinvolgimento dell'utente perché l'elenco delle classi a rotazione fornisce ogni giorno informazioni utili differenti.

Il seguente diagramma mostra il flusso di conversazione della campione di Action Gym:

apporterai piccole modifiche alla finestra di dialogo in base alle funzionalità di coinvolgimento aggiunte. Tuttavia, il design generale della conversazione non cambierà molto.

Scarica i file di base

Esegui il comando seguente per clonare il repository GitHub per il codelab:

git clone https://github.com/actions-on-google/user-engagement-codelab-nodejs

Configura il progetto e l'agente

Per configurare il progetto Actions e l'agente Dialogflow:

1. Apri la Console azioni.
2. Fai clic su Nuovo progetto.
3. Digita un Nome progetto, ad esempio engagement-codelab.
4. Fai clic su Crea progetto.
5. Anziché scegliere una categoria, scorri verso il basso fino alla sezione Altre opzioni e fai clic sulla scheda Conversazione.
6. Fai clic su Crea azione per espandere le opzioni e seleziona Aggiungi azione.
7. Fai clic su Aggiungi la tua prima azione.
8. Nella finestra di dialogo Create Action (Crea azione), seleziona Custom Intent, quindi fai clic su Build per avviare la console di Dialogflow.
9. Nella pagina di creazione dell'agente della console di Dialogflow, fai clic su Crea.
10. Fai clic sull'icona a forma di ingranaggio nella barra di navigazione a sinistra.
11. Fai clic su Esporta e importa, quindi su Ripristina da Zip.
12. Carica il file agent.zip dalla directory /user-engagement-codelab-nodejs/start/ che hai scaricato in precedenza.
13. Digita RESTORE e fai clic su Ripristina.
14. Fai clic su Fine.

Esegui il deployment del tuo fulfillment

Ora che il progetto Actions e l'agente Dialogflow sono pronti, esegui il deployment del tuo file index.js locale utilizzando l'interfaccia a riga di comando di Firebase Functions.

Dalla directory /user-engagement-codelab-nodejs/start/functions/ del clone dei file di base, esegui questi comandi:

firebase use <PROJECT_ID>

Suggerimento: trova l'ID progetto dell'azione nella Console azioni, nella sezione Panoramica > (icona a forma di ingranaggio) > Impostazioni progetto.

npm install

firebase deploy

Se viene visualizzato il messaggio "È stato rilevato un errore imprevisto nell'interfaccia a riga di comando", prova a eseguire di nuovo il comando firebase deploy.

Dopo qualche minuto, dovrebbe essere visualizzato il messaggio "Deploy complete!", che indica che il deployment del webhook è stato eseguito correttamente.

Recuperare l'URL del deployment

Devi fornire a Dialogflow l'URL della funzione cloud. Per recuperare questo URL, procedi nel seguente modo:

1. Apri la Console Firebase.
2. Seleziona il progetto Actions dall'elenco di opzioni.
3. Vai a Develop > Functions nella barra di navigazione a sinistra. Se ti viene chiesto di scegliere le impostazioni di condivisione dei dati, puoi ignorare questa opzione facendo clic su Più tardi.
4. Nella scheda Dashboard, dovresti vedere una voce per "fulfillment" con un URL nella sezione Attiva. Salva questo URL; dovrai copiarlo in Dialogflow nella sezione successiva.

Impostare l'URL webhook in Dialogflow

Ora devi aggiornare l'agente Dialogflow in modo che utilizzi il webhook per il fulfillment. A tale scopo, procedi nel seguente modo:

1. Apri la console di Dialogflow (se vuoi, puoi chiuderla, se vuoi).
2. Fai clic su Fulfillment nel riquadro di navigazione a sinistra.
3. Attiva Webhook.
4. Incolla l'URL che hai copiato dalla dashboard di Firebase se non è ancora visualizzato.
5. Fai clic su Salva.

Verifica che il progetto sia configurato correttamente

Gli utenti devono essere in grado di richiamare l'Azione per ottenere informazioni sulla palestra, tra cui una risposta di testo hardcoded con orario di apertura e una risposta di testo che riporta il programma delle lezioni per ogni giorno della settimana.

Suggerimento: puoi trovare le informazioni più recenti sull'utilizzo del Simulatore delle azioni nella guida del Simulatore delle azioni. Consulta i dati se si verificano problemi seguendo i passaggi sotto riportati.

Per testare l'azione nel simulatore di Actions:

1. Nel pannello di navigazione a sinistra della console Dialogflow, fai clic su Integrations (Integrazioni) > Google Assistant.
2. Assicurati che l'opzione Modifiche automatiche di anteprima sia abilitata e fai clic su Test per aggiornare il progetto Actions.
3. Il simulatore di Actions carica il tuo progetto Actions. Per testare l'Azione, digita Talk to my test app nel campo Input e premi Invio.
4. Dovresti vedere una risposta che ti dà il benvenuto nella palestra. Prova a seguire le istruzioni per continuare la conversazione e assicurarti che il tuo fulfillment abbia una risposta per ogni input.

Se non vedi queste risposte, potrebbe esserci un problema con la configurazione di Firebase. In questo caso, prova a ripetere i passaggi descritti nella sezione Esegui il deployment del fulfillment.

3. Aggiungi abbonamenti con aggiornamento giornaliero

Un modo comune per coinvolgere gli utenti è offrire loro informazioni quando sono più utili. A tale scopo, offri agli utenti la possibilità di iscriversi a un aggiornamento giornaliero per un intent, che invia loro una notifica dell'assistente che rimanda direttamente all'intent in questione.

In questo passaggio, scoprirai gli aggiornamenti giornalieri dell'abbonamento e li aggiungerai all'intento dell'Elenco dei corsi di Action. Una volta seguite queste istruzioni, la conversazione dell'azione sarà simile al seguente diagramma:

In che modo coinvolgerà gli utenti?

Gli utenti di smartphone probabilmente hanno familiarità con le notifiche push, che forniscono informazioni e aggiornamenti specifici per le app. Gli abbonamenti con aggiornamento giornaliero rappresentano un modo semplice per accedere agli utenti su dispositivi mobili esterni all'assistente, a condizione che l'intento di inviare aggiornamenti continui a offrire valore all'utente ogni giorno.

Gli aggiornamenti giornalieri possono essere uno strumento di coinvolgimento utile, ma non devono necessariamente essere incorporati in ogni azione. Prendi in considerazione questi suggerimenti quando decidi se aggiungere abbonamenti di aggiornamento giornalieri a un'azione:

• Assicurati che gli aggiornamenti giornalieri consentano all'utente di visualizzare ogni giorno informazioni utili e diverse. Se ogni volta che tocchi un aggiornamento giornaliero viene visualizzato sempre lo stesso messaggio, è probabile che l'utente annulli l'iscrizione dopo un paio di giorni.
• Assicurati che la finestra di dialogo abbia un senso per l'utente se passa direttamente all'intenzione di aggiornamento giornaliero. L'utente non deve necessariamente iniziare dall'inizio della conversazione, quindi non ci si aspetta che abbia un contesto molto ampio.
• Mostra all'utente il vantaggio della tua azione prima di chiedergli di iscriversi agli aggiornamenti giornalieri. L'utente deve pensare "Voglio che questi contenuti siano disponibili ogni giorno", quando può scegliere di iscriversi.
• Non sovraccaricare l'utente con un numero ripetuto di suggerimenti per abbonarsi. Offri un abbonamento di aggiornamento giornaliero subito dopo aver mostrato all'utente a cosa è iscritto e di non infastidirlo altrove.
• Mantieni la conversazione breve dopo l'attivazione dell'intent di aggiornamento. La maggior parte degli aggiornamenti giornalieri consiste in una singola risposta, dopodiché viene chiusa senza richiedere l'input dell'utente.

Suggerimento: poiché gli aggiornamenti giornalieri verranno visualizzati come notifiche sul dispositivo dell'utente, ti consigliamo di consultare le nostre best practice per la progettazione di notifiche utili. La maggior parte dei contenuti della notifica di aggiornamento giornaliero è preconfigurata per l'assistente, ma questi principi si applicano quando decidi se gli aggiornamenti giornalieri sono adatti alle tue intenzioni o alle tue azioni.

Attiva gli aggiornamenti giornalieri

Le iscrizioni di aggiornamento giornaliero possono essere aggiunte all'intent di benvenuto che porta l'utente all'inizio della conversazione o a un'intenzione più specifica per un link diretto a un punto della conversazione. Per questo codelab, l'intent dell'Elenco corsi è più logico perché la finestra di dialogo cambierà ogni giorno e gli utenti potrebbero trovare utile ricordare i corsi disponibili.

Per attivare gli aggiornamenti giornalieri per l'intent Elenco dei corsi:

1. Nella console di Actions, fai clic sulla scheda Sviluppo e scegli Azioni nella barra di navigazione a sinistra.
2. Fai clic su Elenco dei corsi nell'elenco Azioni.
3. Nella sezione Coinvolgimento utenti, attiva l'opzione Vuoi offrire aggiornamenti giornalieri per gli utenti.
4. Imposta un Titolo contenuti descrittivo che descriva l'aggiornamento giornaliero. Il contesto sarà "A che ora vuoi che invii il tuo messaggio giornaliero", quindi assicurati che il titolo sia descrittivo e che suoni correttamente. Per questo esempio, imposta il Titolo dei contenuti su list of upcoming Action Gym classes.
5. Fai clic su Salva nella parte superiore della pagina.

Configura Dialogflow

Segui questi passaggi nella console di Dialogflow per creare intent per il flusso di abbonamento giornaliero degli aggiornamenti:

Chiedi all'utente di abbonarsi

1. Configura un nuovo intent per gestire l'utente che chiede di iscriversi agli aggiornamenti giornalieri. Nella console di Dialogflow, fai clic sul pulsante + accanto a Intent nel menu di navigazione a sinistra per creare un nuovo intent.
2. Assegna un nome a questo nuovo intent: Setup Updates.
3. Nella sezione Frasi di addestramento, aggiungi le seguenti espressioni utente:

• Send daily reminders
• Reminder
• Remind me
• Updates
• Upcoming classes

4. Nella sezione Fulfillment, attiva l'opzione Abilita chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Gestire la decisione dell'utente

1. Configura un nuovo intent per gestire la risposta dell'utente alla richiesta di aggiornamento giornaliero dell'abbonamento. Fai clic sul pulsante + accanto a Intent nel riquadro di navigazione a sinistra per creare un nuovo intent.
2. Assegna un nome a questo nuovo intent: Confirm Updates.
3. Nella sezione Eventi, aggiungi actions_intent_REGISTER_UPDATE. Questo evento Dialogflow verrà attivato dall'utente che completa il flusso di abbonamento con aggiornamento giornaliero, anche se non ha sottoscritto alcun abbonamento.
4. Nella sezione Fulfillment, attiva l'opzione Abilita chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Implementare il fulfillment

Per implementare il fulfillment nel webhook, completa i seguenti passaggi:

Dipendenze carico

Nel file index.js, aggiorna la funzione require() per aggiungere il pacchetto RegisterUpdate dal pacchetto actions-on-google, in modo che le importazioni abbiano il seguente aspetto:

indice.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
} = require('actions-on-google');

Aggiornare i chip di suggerimenti

Nel file index.js, aggiungi una voce DAILY all'elenco dei titoli dei chip di suggerimenti, in modo che la definizione di Suggestion abbia il seguente aspetto:

indice.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
};

Aggiungere fulfillment per nuovi intent

Quando l'utente dichiara di voler iscriversi, avvia il flusso di abbonamento giornaliero degli aggiornamenti chiamando l'Assistente RegisterUpdate con l'intent di aggiornamento (Elenco dei corsi) e il tipo (DAILY). Al termine dell'abbonamento, l'assistente attiva l'evento actions_intent_REGISTER_UPDATE con un argomento status che descrive se l'abbonamento è stato completato o meno. Offri all'utente messaggi di follow-up che cambiano in base allo stato dell'abbonamento.

Nel file index.js, aggiungi il seguente codice:

indice.js

// Start opt-in flow for daily updates
app.intent('Setup Updates', (conv) => {
  conv.ask(new RegisterUpdate({
    intent: 'Class List',
    frequency: 'DAILY',
  }));
});

// Confirm outcome of opt-in for daily updates
app.intent('Confirm Updates', (conv, params, registered) => {
  if (registered && registered.status === 'OK') {
     conv.ask(`Gotcha, I'll send you an update everyday with the ` +
     'list of classes. Can I help you with anything else?');
  } else {
    conv.ask(` I won't send you daily reminders. Can I help you with anything else?`);
  }
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS, Suggestion.CLASSES]));
  }
});

Offrire messaggi alternativi all'utente

Alla fine, la risposta all'Elenco dei corsi offrirà l'abbonamento giornaliero per l'aggiornamento, ma questo rappresenta un problema. Poiché la stessa risposta verrà attivata quando l'utente toccherà la notifica dell'aggiornamento giornaliero, riceverà comunque una richiesta di iscrizione agli aggiornamenti giornalieri anche se ha appena ricevuto una notifica. Cosa puoi fare per evitare che l'utente pensi di dover ripetere l'iscrizione?

Per fortuna, gli argomenti dell'oggetto conv includono informazioni su dove l'utente ha iniziato la conversazione. Puoi controllare gli argomenti conv per vedere se contengono una sezione UPDATES, che indica che l'utente ha iniziato la conversazione da una notifica di aggiornamento giornaliero e modificare la risposta di conseguenza. Puoi utilizzare questo ramo di conversazione anche per chiudere la finestra di dialogo subito dopo aver fornito l'elenco di corsi, seguendo la nostra best practice che consente di mantenere l'aggiornamento giornaliero breve.

Nel file index.js, sostituisci il codice seguente:

indice.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  const classesMessage =
  `On ${day} we offer the following classes: ${classes}. ` +
  `Can I help you with anything else?`;
  conv.ask(classesMessage);
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS]));
  }
});

con questo:

indice.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

Testare gli aggiornamenti giornalieri

Nel terminale, esegui il comando seguente per eseguire il deployment del codice webhook aggiornato in Firebase:

firebase deploy

Suggerimento: puoi trovare le informazioni più recenti sull'utilizzo del Simulatore delle azioni nella guida del Simulatore delle azioni. Consulta i dati se si verificano problemi seguendo i passaggi sotto riportati.

Per testare il rendimento personalizzato nel simulatore di Actions:

1. Nella console di Actions, vai a Test.
2. Digita Talk to my test app nel campo Input e premi Invio.
3. Digita Learn about classes e premi Invio. Ora la tua risposta all'azione dovrebbe offrirti l'invio di promemoria giornalieri.
4. Digita Send daily reminders e premi Invio.
5. Digita l'ora in cui vuoi vedere l'aggiornamento e premi Invio. A scopo di test, prova a rispondere con 3-5 minuti di ritardo rispetto all'ora attuale.

Se viene visualizzato un messaggio di errore quando cerchi di iscriverti agli aggiornamenti giornalieri nel passaggio 4, torna a Build > Actions > Class List e disattiva gli aggiornamenti giornalieri. Fai clic su Save (Salva), riattiva gli aggiornamenti giornalieri, fai di nuovo clic su Save (Verifica), quindi riprova a eseguire il test nel Simulatore.

Sul tuo dispositivo mobile, dovresti ricevere una notifica dall'assistente intorno all'ora specificata per gli aggiornamenti. La visualizzazione di questa notifica potrebbe richiedere un paio di minuti. Tocca la notifica che contiene un link diretto all'intent Elenco dei corsi nell'assistente, che ti fornisce un elenco dei prossimi corsi:

4. Aggiungi notifiche push

Come opzione alternativa per coinvolgere gli utenti al di fuori dell'azione, puoi chiamare l'API Actions per inviare notifiche push agli utenti. A differenza degli aggiornamenti giornalieri, queste notifiche non vengono programmate automaticamente dall'assistente per consentirti di inviarle quando vuoi.

Parole chiave:

• API Actions:l'API Actions è un'API REST Assistant che viene utilizzata per inviare notifiche agli utenti. Con l'autorizzazione dell'utente, puoi inviare una richiesta POST all'endpoint dell'API Actions che invia una notifica push utilizzando i contenuti della richiesta.

In questo passaggio, imparerai a implementare le notifiche push nell'azione aggiungendo un nuovo intent Annullato dal corso e inviando notifiche agli utenti che li avvisano dell'annullamento di un corso. Inoltre, configurerai i seguenti tre componenti necessari per l'invio delle notifiche:

• Account API Actions: per inviare notifiche all'utente, puoi inviare una richiesta POST a un'API, quindi dovrai configurare un account di servizio e le credenziali per interagire con questa API.
• Assistente per le autorizzazioni: devi disporre dell'autorizzazione dell'utente per accedere allo User-ID necessario per inviare notifiche push. In questo esempio utilizzerai una funzione libreria client per chiamare l'assistente e richiedere questo ID.

Parole chiave:

• Assistente: un assistente è un intent che, una volta completato, consente all'assistente di rilevare temporaneamente la conversazione e richiedere informazioni specifiche all'utente. Se la richiesta ha esito positivo, l'assistente ti restituisce tali informazioni.

• Archiviazione: per inviare notifiche push a un utente esterno a una conversazione, devi archiviare gli ID utente in un punto che possa essere richiamato quando vuoi. In questo esempio, configurerai un database Firestore per archiviare le informazioni per ogni utente.

Dopo aver seguito queste istruzioni, aggiungerai la seguente finestra di dialogo alla conversazione di Action:

In che modo coinvolgerà gli utenti?

Gli utenti di smartphone probabilmente hanno familiarità con le notifiche push, che forniscono informazioni e aggiornamenti specifici per le app. Le notifiche push sono un modo flessibile per accedere agli utenti su dispositivi mobili esterni all'assistente, a condizione che gli utenti abbiano un buon motivo per abilitarli. Grazie agli aggiornamenti giornalieri, gli utenti sono già consapevoli che riceveranno una notifica su base giornaliera. Con le notifiche push, tuttavia, gli utenti non sanno se attivano la ricezione di notifiche non frequenti o verranno disturbati con più notifiche al giorno.

Le notifiche push possono essere uno strumento di coinvolgimento utile, ma non devono necessariamente essere incorporate in ogni azione. Prendi in considerazione questi suggerimenti quando decidi se aggiungere notifiche push a un'azione:

• Pianifica alcune pianificazioni di esempio per le notifiche push. Se prevedi di inviare una sola notifica push al giorno, valuta l'utilizzo di aggiornamenti giornalieri.
• Assicurati che le notifiche push forniscano informazioni utili ogni volta che le ricevi. Le notifiche possono anche indirizzare direttamente a uno degli intent dell'Azione, perciò assicurati che l'intent sia utile e pertinente.
• Chiedi esplicitamente all'utente di iscriversi alle notifiche push. Devono capire cosa aspettarsi da ogni notifica push e avere un'idea della frequenza di invio.

Suggerimento: consulta le nostre best practice per progettare notifiche utili. Il logo e la priorità della notifica sono predeterminati per l'assistente, ma questi principi si applicano quando decidi se aggiungere una notifica push per l'azione.

Abilita l'API Actions

1. Apri Google Cloud Console e seleziona il nome del progetto Actions nel menu a discesa.

2. Nel menu di navigazione (☰) vai ad API e servizi e libreria.
3. Cerca l'API Actions e fai clic su Attiva.

Crea un account di servizio

L'API Actions richiede l'autenticazione, pertanto devi creare un account di servizio per inviare le richieste. Segui questi passaggi per creare e installare una chiave dell'account di servizio per l'API Actions:

1. Nel menu di navigazione di (☰) di Google Cloud Console, vai a API e servizi > Credenziali.
2. Fai clic su Crea credenziali > Chiave account di servizio.
3. Nel menu a discesa Account di servizio, seleziona Nuovo account di servizio.
4. Inserisci le seguenti informazioni:

• Nome account di servizio: service-account
• Ruolo: progetto > proprietario
• ID account di servizio: service-account (sempre seguito da @<project_id>.iam.gserviceaccount.com)
• Tipo di chiave: JSON

5. Fai clic su Crea.
6. Sposta il file JSON scaricato nella directory /user-engagement-codelab/start/functions/ del tuo progetto.
7. Rinomina il file JSON in service-account.json.

Abilita Firestore

Per inviare notifiche al di fuori della conversazione, devi utilizzare un metodo per memorizzare gli ID utente a cui è possibile fare riferimento dal tuo codice di notifica. Per questo esempio utilizziamo un database Firestore per archiviare gli ID utente degli utenti iscritti.

Per creare un database Firestore per l'azione:

1. Nella Console Firebase, seleziona il nome del tuo progetto Actions.
2. Nel pannello di navigazione a sinistra, vai a Sviluppo > database e fai clic su Crea database.
3. Seleziona Avvia in modalità test.
4. Fai clic su Abilita.

Suggerimento: noi utilizziamo le regole di sicurezza della modalità di test solo a scopo di test. Prima di pubblicare l'azione in produzione, devi avere regole di sicurezza dei dati più efficaci. Scopri di più sulle regole di sicurezza di Cloud Firestore nella documentazione di Firestore.

Configura Dialogflow

Per creare il flusso di attivazione delle notifiche push, segui questi passaggi nella console di Dialogflow:

Chiedi all'utente di abbonarsi

1. Configura un nuovo intent per gestire l'utente che chiede di iscriversi alle notifiche push per i corsi annullati. Nella console di Dialogflow, fai clic sul pulsante + accanto a Intent nel menu di navigazione a sinistra per creare un nuovo intent.
2. Assegna un nome a questo nuovo intent: Setup Push Notifications.
3. Nella sezione Frasi di addestramento, aggiungi le seguenti espressioni utente:

• Subscribe to notifications
• Send notification
• Notify me
• Send class notifications
• Cancelled notifications

4. Nella sezione Fulfillment, attiva l'opzione Abilita chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Gestire la decisione dell'utente

1. Configura un nuovo intent per gestire la risposta dell'utente alla richiesta di iscrizione alle notifiche push. Fai clic sul pulsante + accanto a Intent nel riquadro di navigazione a sinistra per creare un nuovo intent.
2. Assegna un nome a questo nuovo intent: Confirm Push Notifications.
3. Nella sezione Eventi, aggiungi actions_intent_PERMISSION. Questo evento Dialogflow verrà attivato dall'utente che completa il flusso di sottoscrizione delle notifiche push, indipendentemente dal fatto che l'utente abbia sottoscritto o meno l'abbonamento.
4. Nella sezione Fulfillment, attiva l'opzione Abilita chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Gestire la notifica push

Puoi collegare le notifiche push a un intent specifico, in modo che gli utenti che toccano la notifica push siano direttamente collegati a tale intent nella tua azione. In questo esempio, aggiungi un nuovo intent per le notifiche push che forniscono dettagli sui corsi annullati.

Segui questi passaggi per aggiungere un intent che deve essere attivato dall'utente che tocca una notifica push:

1. Nella console di Dialogflow, fai clic sul pulsante + accanto a Intent nel menu di navigazione a sinistra per creare un nuovo intent.
2. Assegna un nome a questo nuovo intent: Class Canceled.
3. Nella sezione Frasi di addestramento, aggiungi Cancelations come espressione utente.
4. Nella sezione Fulfillment, attiva l'opzione Abilita chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Inviare notifiche di prova durante una conversazione

In produzione, dovresti avere uno script separato dal codice di evasione delle azioni che invia notifiche push. Per questo esempio, crea un intent che puoi richiamare per inviare una notifica push mentre parli con l'azione. Lo scopo di questa operazione è solo a scopo di debug; in pratica, le notifiche push non devono essere gestite dal tuo fulfillment o comunque attivate nell'ambito della conversazione sulla tua azione.

Per creare un intent per il test delle notifiche push, segui questi passaggi:

1. A scopo di test e debug, configura un nuovo intent che ti consenta di inviare notifiche push agli utenti iscritti. Nella console di Dialogflow, fai clic sul pulsante + accanto a Intent nel menu di navigazione a sinistra per creare un nuovo intent.
2. Assegna un nome a questo nuovo intent: Test Notification.
3. Nella sezione Frasi di addestramento, aggiungi Test notification come espressione utente.
4. Nella sezione Fulfillment, attiva l'opzione Abilita chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Attiva notifiche push

Segui questi passaggi per attivare le notifiche push per l'intent Class Annullato:

1. Nella console di Dialogflow, vai a Integrations (Integrazioni) nella barra di navigazione.
2. Nella scheda Assistente Google, fai clic su Impostazioni di integrazione.
3. Aggiungi Class Canceled (Classe annullata) come intent implicito di chiamata. Questo passaggio è necessario affinché Dialogflow riconosca che gli utenti possono avviare la conversazione con l'intent Classed Annullato (toccando una notifica push).
4. Fai clic su Chiudi.

5. Nella console di Actions, fai clic sulla scheda Sviluppo e scegli Azioni nella barra di navigazione a sinistra.
6. Fai clic su Corso annullato nell'elenco Azioni.
7. Nella sezione Coinvolgimento utenti, attiva l'opzione Vuoi inviare notifiche push?
8. Imposta un Titolo contenuti descrittivo che descriva la notifica push. Il contesto è &quo; Va bene se invio notifiche push per ?" quindi assicurati che il titolo sia descrittivo e corretto quando viene pronunciato ad alta voce. Per questo esempio, imposta il Titolo dei contenuti su class cancelations.
9. Fai clic su Salva nella parte superiore della pagina.

Implementare il fulfillment

Per implementare il fulfillment nel webhook, completa i seguenti passaggi:

Dipendenze carico

Nel file index.js, aggiorna la funzione require() per aggiungere il pacchetto UpdatePermission dal pacchetto actions-on-google, in modo che le importazioni abbiano il seguente aspetto:

indice.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
  UpdatePermission,
} = require('actions-on-google');

Aggiornare i chip di suggerimenti

Nel file index.js, aggiungi una voce NOTIFICATIONS all'elenco dei titoli dei chip di suggerimenti, in modo che la definizione di Suggestion abbia il seguente aspetto:

indice.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
  NOTIFICATIONS: 'Get notifications',
};

Configurare nuove importazioni

Per connetterti al database Firestore, aggiungi il pacchetto firebase-admin e aggiungi costanti per i campi archiviati nel database. Inoltre, importa i pacchetti google-auth-library e request per gestire l'autenticazione e le richieste nell'API Actions.

Nel file index.js, aggiungi il seguente codice alle importazioni:

indice.js

// Firebase admin import
const admin = require('firebase-admin');

// Initialize Firestore
admin.initializeApp();
const db = admin.firestore();

// Firestore constants
const FirestoreNames = {
 INTENT: 'intent',
 USER_ID: 'userId',
 USERS: 'users',
};

// Actions API authentication imports
const {auth} = require('google-auth-library');
const request = require('request');

Offerta di configurare notifiche di annullamento del corso

Nel file index.js, sostituisci il codice seguente:

indice.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

con questo:

indice.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like to receive daily reminders of upcoming classes, subscribe to notifications about cancelations, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.NOTIFICATIONS,
Suggestion.HOURS]));
    };
  };
});

Aggiungere fulfillment per nuovi intent

Quando l'utente dice di voler iscriversi alle notifiche push, chiama l'Assistente UpdatePermission per richiedere l'autorizzazione dell'utente. Se l'operazione ha esito positivo, l'argomento PERMISSION verrà aggiunto agli argomenti dell'oggetto conv che puoi controllare per pivot la conversazione.

Una volta ottenuta l'autorizzazione dell'utente, recupera l'ID utente dagli argomenti dell'oggetto conv e salvalo nel database. In seguito invierai questo ID utente all'API Actions, che determina l'assistente che stabilisce chi riceve la notifica.

Infine, aggiungi il fulfillment per l'intent Class Canceled attivato toccando la notifica push. In questo esempio, la tua risposta è una stringa segnaposto, anche se in una versione pronta per la produzione di questa azione lo script di notifica fornisce informazioni più dinamiche su quale classe è stata annullata.

Nel file index.js, aggiungi il seguente codice:

indice.js

// Call the User Information helper for permission to send push notifications
app.intent('Setup Push Notifications', (conv) => {
 conv.ask('Update permission for setting up push notifications');
 conv.ask(new UpdatePermission({intent: 'Class Canceled'}));
});

// Handle opt-in or rejection of push notifications
app.intent('Confirm Push Notifications', (conv) => {
 if (conv.arguments.get('PERMISSION')) {
   let userId = conv.arguments.get('UPDATES_USER_ID');
   if (!userId) {
     userId = conv.request.conversation.conversationId;
   }
   // Add the current conversation ID and the notification's
   // target intent to the Firestore database.
   return db.collection(FirestoreNames.USERS)
   .add({
     [FirestoreNames.INTENT]: 'Class Canceled',
     [FirestoreNames.USER_ID]: userId,
   })
   .then(() => {
     conv.ask(`Great, I'll notify you whenever there's a class cancelation. ` +
     'Can I help you with anything else?');
   });
 } else {
   conv.ask(`Okay, I won't send you notifications about class cancelations. ` +
     'Can I help you with anything else?');
 }
 if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.CLASSES, Suggestion.HOURS]));
  }
});

// Intent triggered by tapping the push notification
app.intent('Class Canceled', (conv) => {
 conv.ask('Classname at classtime has been canceled.');
});

Aggiungere notifiche di prova

Per inviare una notifica push a un utente, invia una richiesta POST all'API Actions con lo User-ID, il titolo della notifica e l'intent target. In questo esempio, l'attivazione dell'intent di notifica di prova esegue l'iterazione tramite il database Firestore e invia notifiche push a tutti gli utenti iscritti alle notifiche.

Tieni presente che, in questo esempio, includerai il codice che invia la notifica push nel fulfillment di webhook e attiverai tale codice richiamando un intent di test nella conversazione. In Azioni che vuoi pubblicare, il codice della notifica push deve esistere in uno script separato dal tuo fulfillment.

Nel file index.js, aggiungi il seguente codice:

indice.js

// Debug intent to trigger a test push notification
app.intent('Test Notification', (conv) => {
 // Use the Actions API to send a Google Assistant push notification.
 let client = auth.fromJSON(require('./service-account.json'));
 client.scopes = ['https://www.googleapis.com/auth/actions.fulfillment.conversation'];
 let notification = {
   userNotification: {
     title: 'Test Notification from Action Gym',
   },
   target: {},
 };
 client.authorize((err, tokens) => {
   if (err) {
     throw new Error(`Auth error: ${err}`);
   }
   // Iterate through Firestore and send push notifications to every user
   // who's currently opted in to canceled class notifications.
   db.collection(FirestoreNames.USERS)
       .where(FirestoreNames.INTENT, '==', 'Class Canceled')
       .get()
       .then((querySnapshot) => {
         querySnapshot.forEach((user) => {
           notification.target = {
             userId: user.get(FirestoreNames.USER_ID),
             intent: user.get(FirestoreNames.INTENT),
           };
           request.post('https://actions.googleapis.com/v2/conversations:send', {
             'auth': {
               'bearer': tokens.access_token,
             },
             'json': true,
             'body': {'customPushMessage': notification, 'isInSandbox': true},
           }, (err, httpResponse, body) => {
             if (err) {
               throw new Error(`API request error: ${err}`);
             }
             console.log(`${httpResponse.statusCode}: ` +
               `${httpResponse.statusMessage}`);
             console.log(JSON.stringify(body));
           });
         });
       })
       .catch((error) => {
         throw new Error(`Firestore query error: ${error}`);
       });
 });
 conv.ask('A notification has been sent to all subscribed users.');
});

Testare le notifiche push

Nel terminale, esegui il comando seguente per eseguire il deployment del codice webhook aggiornato in Firebase:

firebase deploy

Suggerimento: puoi trovare le informazioni più recenti sull'utilizzo del Simulatore delle azioni nella guida del Simulatore delle azioni. Consulta i dati se si verificano problemi seguendo i passaggi sotto riportati.

Per testare le notifiche nel simulatore di Actions:

1. Nella console di Actions, vai alla scheda Test.
2. Digita Talk to my test app nel campo Input e premi Invio.
3. Digita Learn about classes e premi Invio.
4. Digita Get notifications e premi Invio.
5. Se non hai già concesso l'autorizzazione Azione per inviarti notifiche push, digita yes e premi Invio.
6. Digita yes e premi Invio. Ora il tuo Account Google deve essere iscritto per ricevere notifiche push per questa azione.

Se viene visualizzato un messaggio di errore quando provi a iscriverti alle notifiche push nel passaggio 4, torna a Build > Actions > Class Canceled e disattiva le notifiche push. Fai clic su Save (Salva), riattiva le notifiche push, fai di nuovo clic su Save (Verifica), quindi riprova a eseguire il test nel Simulatore.

7. Digita no e premi Invio per uscire.
8. Digita Talk to my test app e premi Invio per avviare una nuova conversazione.
9. Digita Test notification e premi Invio.

Entro pochi minuti dovresti ricevere una notifica "Test notifica da palestra azione" sul tuo dispositivo mobile. Se tocchi questa notifica, troverai un link diretto all'intenzione Annullato il corso dell'Azione.

Se hai difficoltà a ricevere la notifica, prova a seguire le istruzioni di verifica sul tuo telefono. Apri l'assistente sul telefono e di' "talk to my test app", quindi segui le istruzioni sopra indicate per il test dal passaggio 3.

5. Crea un link dell'assistente

Finora abbiamo parlato delle funzionalità di coinvolgimento che puoi implementare per indurre gli utenti a tornare nella tua azione. Tuttavia, ciò si basa sulla possibilità per gli utenti di scoprire e utilizzare l'azione.

Puoi creare un link dell'assistente che colleghi gli utenti su dispositivi mobili direttamente all'assistente. Poiché il link dell'assistente è un link ipertestuale standard, puoi aggiungerlo a un sito web o a qualsiasi materiale di marketing web come un blog o un post sui social media.

In questo passaggio, imparerai che cos'è un link dell'assistente, come crearne uno per l'intenzione di benvenuto dell'azione e come aggiungerlo a un semplice sito web per testarlo.

In che modo coinvolgerà gli utenti?

Attirare gli utenti verso l'Azione per la prima volta può essere difficile, soprattutto quando devono richiamare esplicitamente l'Azione sull'assistente. Un link dell'assistente allenta questo problema fornendo agli utenti un link diretto all'azione. Quando un utente segue il link dell'assistente su un dispositivo con l'assistente integrato, viene indirizzato direttamente alla tua azione. Quando un utente apre il link su un dispositivo non mobile o su qualsiasi altro dispositivo che non supporta l'assistente, verrà comunque indirizzato alla scheda della directory delle azioni (se è stato pubblicato), in modo che il link possa comunque commercializzare l'azione per tali utenti.

I link dell'assistente possono essere uno strumento utile per il coinvolgimento, quindi devi crearne uno se hai intenzione di pubblicizzare la tua azione tramite il tuo sito web o i social media. Tieni presenti i seguenti suggerimenti prima di creare e distribuire un link dell'assistente:

• I link dell'assistente funzionano solo dopo la pubblicazione dell'azione. Mentre il progetto è in stato bozza, il link funziona solo sui tuoi dispositivi. Tutti gli altri verranno indirizzati a una pagina 404 nella directory Azioni.
• Puoi consentire agli utenti di testare un link dell'assistente prima di pubblicarlo pubblicando l'azione in un ambiente alpha o beta. Tieni presente che soltanto gli utenti che partecipano alla versione alpha o beta potranno testare il tuo link all'assistente.
• Assicurati che l'intent di destinazione del link dell'assistente faccia una buona prima impressione nei nuovi utenti. L'intent di benvenuto è la destinazione predefinita di un link dell'assistente perché dovrebbe già essere un buon modo per presentare la tua azione.

Suggerimento: in questo esempio puoi creare solo un semplice link dell'assistente che indirizzi gli utenti all'intent di benvenuto, ma puoi fare molto altro per personalizzare un link dell'assistente. Puoi aggiungere parametri URL al link che indirizzino gli utenti a intent specifici e includere parametri di personalizzazione per personalizzare la risposta che gli utenti ricevono quando seguono il link. Anche se non stiamo trattando queste opzioni avanzate in questo codelab, puoi trovare ulteriori informazioni nella documentazione per gli sviluppatori.

Attivare i link dell'assistente

Segui questi passaggi per creare un link dell'assistente per l'intent di benvenuto:

1. Nella console di Actions, fai clic sulla scheda Sviluppo e scegli Azioni nella barra di navigazione a sinistra.
2. Fai clic su actions.intent.MAIN nell'elenco Action (Azioni).
3. Nella sezione Link, attiva l'opzione Vuoi attivare un URL per questa azione.
4. Imposta un Titolo collegamento descrittivo che descriva l'Azione. Assegna al titolo una semplice combinazione di verbo e nome che descriva l'azione che l'utente può eseguire con l'Azione. Per questo esempio, imposta il Titolo collegamento su learn about Action Gym.
5. Copia lo snippet HTML dal fondo di questa pagina e salvalo per usarlo in un secondo momento.
6. Fai clic su Salva nella parte superiore della pagina.

Eseguire il deployment di un sito web di test

Per testare il link dell'assistente, puoi utilizzare gli strumenti Firebase per eseguire il deployment di un sito web di test insieme al tuo fulfillment. Abbiamo già creato un semplice sito web di test per questo esempio, devi solo aggiungere il tuo link all'assistente.

Vai alla directory /user-engagement-codelab-nodejs/start/public/ del tuo fulfillment e apri il file index.html in un editor di testo.

Nel file index.html, incolla lo snippet HTML del link dell'assistente nell'elemento body. Il file dovrebbe avere il seguente aspetto:

indice.html

<body>
    <p>
     <a href="https://assistant.google.com/services/invoke/uid/000000efb5f2fd97">🅖 Ask my test app to learn about Action Gym
     </a>
    </p>
</body>

Testa il tuo link all'assistente

Nel terminale, esegui il comando seguente per eseguire il deployment del tuo sito web di test in Firebase:

firebase deploy

Quando il comando di deployment termina l'esecuzione, prendi nota dell'URL di hosting nell'output.

Vai a questo URL sul browser web del tuo dispositivo mobile e dovresti vedere il link dell'assistente sul tuo sito web di test. Se fai clic su questo link sul dispositivo mobile, dovresti essere reindirizzato all'intenzione di benvenuto dell'azione nell'assistente.

Puoi anche provare a utilizzare l'URL Hosting su un browser per desktop, che dovrebbe reindirizzarti a una pagina 404 nella directory dell'assistente perché l'Azione non è pubblicata.

6. Passaggi successivi

Complimenti!

Ora sai quanto sia importante il coinvolgimento degli utenti durante lo sviluppo di un'azione, quali funzionalità di coinvolgimento degli utenti siano disponibili sulla piattaforma e come aggiungere ogni funzionalità a un'azione.

Risorse di apprendimento aggiuntive

Consulta queste risorse per saperne di più sul coinvolgimento degli utenti per la tua azione:

• Coinvolgimento utenti &Documenti con link all'assistente: la documentazione ufficiale di Actions on Google sulle funzionalità discusse in questo codelab e sul coinvolgimento degli utenti in generale.
• Analisi della fidelizzazione degli utenti: documentazione per la funzionalità di analisi nella console di Actions che mostra la fidelizzazione degli utenti per l'azione pubblicata.
• Linee guida per la progettazione conversazionale: best practice e linee guida per progettare funzionalità di coinvolgimento degli utenti.
• Repository di azioni su Google GitHub: codice e librerie di esempio.
• r/GoogleAssistantDev: la community ufficiale di Reddit per gli sviluppatori che lavorano con l'assistente.

Seguici su Twitter @ActionOnGoogle per non perderti i nostri ultimi annunci e twitta a #AoGDevs per condividere ciò che hai creato.

Sondaggio di feedback

Prima di andarci, compila questo modulo per farci sapere come stiamo andando.