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

1. Panoramica

Avviso: le azioni conversazionali sono state ritirate il 13 giugno 2023. Per ulteriori informazioni, consulta la sezione Ritiro di Azioni conversazionali.

Actions on Google è una piattaforma di sviluppo che ti consente di creare software per estendere la funzionalità dell'Assistente Google, l'assistente personale virtuale di Google, su oltre un miliardo di dispositivi, tra cui smart speaker, smartphone, auto, TV, cuffie e altro ancora. Gli utenti interagiscono con l'assistente per svolgere attività come acquistare generi alimentari o prenotare una corsa. Per un elenco completo delle possibilità, consulta la directory delle azioni. In qualità di sviluppatore, puoi utilizzare Azioni su Google per creare e gestire facilmente esperienze conversazionali efficaci e piacevoli tra gli utenti e il tuo servizio di terze parti.

Questo è un modulo codelab avanzato, destinato ai lettori che hanno già esperienza nella creazione di Azioni per l'Assistente Google. Se non hai esperienza di sviluppo precedente con Azioni su 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à dell'azione e ad aumentare il tuo pubblico.

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

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

Cosa creerai

Migliorerai una funzionalità già creata consentendole di:

• Invia agli utenti un aggiornamento giornaliero che possono toccare per parlare con la tua Azione
• Invia agli utenti notifiche push con un link alla tua azione
• Creare un link che indirizzi gli utenti alla tua Azione da un browser web mobile

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 degli utenti
• Quali funzionalità di coinvolgimento degli utenti utilizzare nei diversi tipi di azioni
• Come utilizzare l'API Actions per inviare notifiche tramite l'assistente

Che cosa ti serve

Devi disporre dei seguenti strumenti:

• Un IDE/editor di testo a tua scelta, ad esempio WebStorm, Atom o Sublime.
• Un terminale per eseguire comandi 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 Firebase
• Un dispositivo mobile (Android o iOS) con l'assistente (devi aver eseguito l'accesso all'assistente con lo stesso Account Google che utilizzerai per creare questo progetto).

È inoltre consigliata, anche se non obbligatoria, la familiarità con JavaScript (ES6) per comprendere il codice del webhook.

2. Configura il progetto

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

Termini chiave:

• Coinvolgimento degli utenti:la metrica utilizzata per misurare se gli utenti trovano valore in un prodotto o servizio. Il coinvolgimento può essere rappresentato dal numero di utenti che tornano alla tua Azione, una metrica utilizzata per determinare se promuovere un'Azione. Un elevato coinvolgimento degli utenti deriva da due componenti di un'Azione: informazioni utili che gli utenti vorranno consultare in un secondo momento e modi per tornare alla tua Azione quando è più probabile che recuperino queste informazioni.

Comprendere il campione

L'esempio per questo codelab è una semplice Azione per una palestra fittizia chiamata "Action Gym". L'azione fornisce informazioni sulla palestra, tra cui un elenco di corsi che cambiano ogni giorno. Un'azione informativa come questa è un buon candidato per tutte le funzionalità di coinvolgimento degli utenti, perché l'elenco dei corsi a rotazione fornisce informazioni utili diverse ogni giorno.

Il seguente diagramma mostra il flusso conversazionale dell'esempio Action Gym:

Apporterai piccole modifiche alla finestra di dialogo per adattarla meglio alle funzionalità di coinvolgimento che aggiungi. Tuttavia, il design generale della conversazione non cambierà molto.

Scaricare 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 Conversazionale.
6. Fai clic su Crea la tua azione per espandere le opzioni e seleziona Aggiungi azione.
7. Fai clic su Aggiungi la tua prima azione.
8. Nella finestra di dialogo Crea azione, seleziona Intent personalizzato e poi fai clic su Crea per avviare la console Dialogflow.
9. Nella pagina di creazione dell'agente della console Dialogflow, fai clic su Crea.
10. Fai clic sull'icona (a forma di ingranaggio) nel riquadro di navigazione a sinistra.
11. Fai clic su Esporta e importa, poi 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 fulfillment

Ora che il progetto Actions e l'agente Dialogflow sono pronti, esegui il deployment del 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 i seguenti comandi:

firebase use <PROJECT_ID>

Suggerimento: trova l'ID progetto dell'azione nella console Actions in Panoramica > (icona a forma di ingranaggio) > Impostazioni progetto.

npm install

firebase deploy

Se visualizzi il messaggio di errore "Si è verificato un errore imprevisto dalla CLI", prova a eseguire di nuovo il comando firebase deploy.

Dopo qualche minuto, dovresti visualizzare il messaggio "Deploy complete!" (Implementazione completata), che indica che hai eseguito il deployment del webhook su Firebase.

Recuperare l'URL di deployment

Devi fornire a Dialogflow l'URL della funzione cloud. Per recuperare questo URL, segui questi passaggi:

1. Apri la Console Firebase.
2. Seleziona il tuo progetto Actions dall'elenco di opzioni.
3. Vai a Sviluppa > Funzioni 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 Fallo in un secondo momento.
4. Nella scheda Dashboard, dovresti vedere una voce relativa all'"evasione" con un URL in Trigger. Salva questo URL, che dovrai copiare in Dialogflow nella sezione successiva.

Imposta l'URL webhook in Dialogflow

Ora devi aggiornare l'agente Dialogflow per utilizzare il webhook per il fulfillment. Per farlo, segui questi passaggi:

1. Apri la console Dialogflow (puoi chiudere la console Firebase, 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 Firebase se non è già presente.
5. Fai clic su Salva.

Verifica che il progetto sia configurato correttamente

Gli utenti devono essere in grado di richiamare l'azione per informazioni su Action Gym, inclusa una risposta di testo hardcoded con l'orario di apertura e una risposta di testo che elenca il programma dei corsi per ogni giorno della settimana.

Suggerimento:puoi trovare le informazioni più recenti sull'utilizzo del Simulatore delle azioni nella guida al Simulatore delle azioni. Consulta questa pagina se riscontri problemi durante l'esecuzione dei passaggi elencati di seguito.

Per testare l'azione nel simulatore di Actions:

1. Nel menu di navigazione a sinistra della console Dialogflow, fai clic su Integrazioni > Google Assistant.
2. Assicurati che l'opzione Anteprima automatica delle modifiche sia attivata e fai clic su Test per aggiornare il progetto Azioni.
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 visualizzare una risposta che ti dà il benvenuto in Action Gym. Prova a seguire le istruzioni per continuare la conversazione, assicurandoti che la tua evasione abbia una risposta per ogni input.

Se non vedi queste risposte, probabilmente si è verificato un problema con la configurazione di Firebase. In questo caso, prova a ripetere i passaggi della sezione Esegui il deployment dell'implementazione.

3. Aggiungere abbonamenti agli aggiornamenti giornalieri

Un modo comune per coinvolgere gli utenti è offrire loro informazioni quando sono più utili. Ciò avviene offrendo agli utenti la possibilità di iscriversi agli aggiornamenti giornalieri per un intent, che invia loro una notifica dell'assistente con un link diretto all'evasione dell'intent.

In questo passaggio, scoprirai di più sugli abbonamenti agli aggiornamenti giornalieri e li aggiungerai all'intent Elenco del corso dell'azione. Dopo aver seguito queste istruzioni, la conversazione dell'azione sarà simile al seguente diagramma:

In che modo ciò coinvolgerà gli utenti?

Gli utenti di smartphone conoscono probabilmente le notifiche push, che forniscono informazioni e aggiornamenti specifici per le app. Gli abbonamenti agli aggiornamenti giornalieri sono un modo semplice per raggiungere gli utenti su dispositivi mobili al di fuori dell'assistente, a condizione che l'intent per cui invii gli aggiornamenti continui a fornire valore all'utente su base giornaliera.

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

• Assicurati che gli aggiornamenti giornalieri consentano all'utente di visualizzare informazioni diverse e utili ogni giorno. Se toccando un aggiornamento quotidiano viene visualizzato lo stesso messaggio ogni volta, l'utente probabilmente annullerà l'iscrizione dopo un paio di giorni.
• Assicurati che la finestra di dialogo abbia senso per l'utente se passa direttamente all'intent dell'aggiornamento giornaliero. L'utente non inizierà necessariamente dall'inizio della conversazione, quindi non è detto che abbia molto contesto.
• Mostra all'utente il vantaggio della tua Azione prima di invitarlo a iscriversi agli aggiornamenti giornalieri. Quando viene data la possibilità di iscriversi, l'utente dovrebbe pensare "Voglio questi contenuti ogni giorno".
• Non sovraccaricare l'utente con suggerimenti ripetuti per abbonarsi. Offri un abbonamento agli aggiornamenti giornalieri subito dopo aver mostrato all'utente a cosa si abbonerà ed evita di importunarlo in altri modi.
• Mantieni la conversazione breve dopo l'attivazione dell'intent di aggiornamento. La maggior parte degli aggiornamenti giornalieri dovrebbe consistere in una singola risposta e chiudersi senza richiedere l'input dell'utente.

Suggerimento:poiché gli aggiornamenti giornalieri verranno visualizzati come notifiche sul dispositivo dell'utente, ti consigliamo di esaminare le nostre best practice per la progettazione di notifiche utili. La maggior parte dei contenuti della notifica di aggiornamento giornaliero è predefinita per l'assistente, ma gli stessi principi si applicano quando decidi se gli aggiornamenti giornalieri sono adatti al tuo intent o alla tua azione.

Attivare gli aggiornamenti quotidiani

Gli abbonamenti agli aggiornamenti giornalieri possono essere aggiunti all'intent di benvenuto, che posiziona l'utente all'inizio della conversazione, o a un intent più specifico per indirizzarlo a una sezione specifica della conversazione. Per questo codelab, l'intent Elenco corsi è il più sensato perché il dialogo cambierà ogni giorno e gli utenti potrebbero trovare utile ricevere un promemoria dei corsi disponibili.

Segui questi passaggi per attivare gli aggiornamenti giornalieri per l'intent Elenco della classe:

1. Nella console di Actions, fai clic sulla scheda Sviluppa e scegli Azioni nella barra di navigazione a sinistra.
2. Fai clic su Elenco della classe nell'elenco Azioni.
3. Nella sezione Coinvolgimento degli utenti, attiva o disattiva l'opzione Vuoi offrire aggiornamenti giornalieri agli utenti?.
4. Imposta un titolo dei contenuti descrittivo che descriva l'aggiornamento quotidiano. Il contesto sarà "A che ora vuoi che ti invii il tuo riepilogo giornaliero ", quindi assicurati che il titolo sia descrittivo e suoni corretto quando viene letto ad alta voce. Per questo esempio, imposta 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 Dialogflow per creare intent per il flusso di iscrizione all'aggiornamento quotidiano:

Chiedere all'utente di iscriversi

1. Configura un nuovo intent per gestire la richiesta dell'utente di iscriversi agli aggiornamenti giornalieri. Nella console Dialogflow, fai clic sul pulsante + accanto a Intent nel menu di navigazione a sinistra per creare un nuovo intent.
2. Assegna a questo nuovo intent il nome 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 al prompt di iscrizione agli aggiornamenti giornalieri. Fai clic sul pulsante + accanto a Intent nel riquadro di navigazione a sinistra per creare un nuovo intent.
2. Assegna a questo nuovo intent il nome Confirm Updates.
3. Nella sezione Eventi, aggiungi actions_intent_REGISTER_UPDATE. Questo evento Dialogflow verrà attivato al termine del flusso di iscrizione all'aggiornamento giornaliero, indipendentemente dal fatto che l'utente si sia iscritto o meno.
4. Nella sezione Fulfillment, attiva l'opzione Abilita chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Implementare l'evasione

Per implementare l'evasione nel webhook, completa i seguenti passaggi:

Carica dipendenze

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

index.js

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

Aggiornare i chip di suggerimento

Nel file index.js, aggiungi una voce DAILY all'elenco dei titoli dei chip di suggerimento, in modo che la definizione di Suggestion sia simile alla seguente:

index.js

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

Aggiungere l'evasione per nuovi intent

Quando l'utente dice di voler abbonarsi, avvia il flusso di abbonamento agli aggiornamenti giornalieri chiamando l'helper RegisterUpdate con l'intent di destinazione dell'aggiornamento (Elenco classi) e il tipo (DAILY). Al termine del flusso di abbonamento, l'assistente attiva l'evento actions_intent_REGISTER_UPDATE con un argomento status che descrive se l'abbonamento è andato a buon fine o meno. Offri all'utente prompt di follow-up che cambiano a seconda dello stato dell'abbonamento.

Nel file index.js, aggiungi il seguente codice:

index.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 all'utente prompt alternativi

La risposta all'elenco del corso offrirà l'abbonamento all'aggiornamento giornaliero alla fine, ma questo presenta un problema. Poiché la stessa risposta verrà attivata quando l'utente tocca la notifica di aggiornamento giornaliero, gli verrà comunque chiesto di iscriversi agli aggiornamenti giornalieri anche se ne ha appena ricevuto uno. Come puoi evitare che l'utente pensi di dover rinnovare l'abbonamento?

Fortunatamente, gli argomenti dell'oggetto conv includono informazioni sul punto di partenza della conversazione dell'utente. 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 anche utilizzare questo ramo della conversazione per chiudere la finestra di dialogo subito dopo aver fornito l'elenco delle classi, in linea con la nostra best practice di mantenere breve l'aggiornamento giornaliero.

Nel file index.js, sostituisci il seguente codice:

index.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:

index.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 quotidiani

Nel terminale, esegui questo comando per eseguire il deployment del codice webhook aggiornato su Firebase:

firebase deploy

Suggerimento:puoi trovare le informazioni più recenti sull'utilizzo del Simulatore delle azioni nella guida al Simulatore delle azioni. Consulta questa pagina se riscontri problemi durante l'esecuzione dei passaggi elencati di seguito.

Per provare il tuo messaggio di richiesta personalizzato nel simulatore di azioni, segui questi passaggi:

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. La risposta dell'azione ora dovrebbe offrire l'invio di promemoria giornalieri.
4. Digita Send daily reminders e premi Invio.
5. Digita l'ora in cui vuoi visualizzare l'aggiornamento e premi Invio. A scopo di test, prova a rispondere 3-5 minuti dopo l'ora attuale.

Se ricevi un errore quando provi a iscriverti agli aggiornamenti giornalieri nel passaggio 4, torna a Build > Actions > Class List e disattiva gli aggiornamenti giornalieri. Fai clic su Salva, riattiva gli aggiornamenti giornalieri, fai di nuovo clic su Salva e riprova a eseguire il test nel simulatore.

Sul tuo dispositivo mobile dovresti ricevere una notifica dall'assistente all'ora che hai specificato per gli aggiornamenti. Tieni presente che la visualizzazione di questa notifica potrebbe richiedere alcuni minuti. Tocca la notifica per accedere direttamente all'intent Elenco dei corsi nell'assistente, che ti fornirà un elenco dei corsi in programma:

4. Aggiungere notifiche push

Un'altra opzione per coinvolgere gli utenti al di fuori dell'azione è chiamare l'API Actions per inviare notifiche push agli utenti. A differenza degli aggiornamenti giornalieri, queste notifiche non vengono pianificate automaticamente dall'assistente, quindi puoi inviarle a tuo piacimento.

Termini chiave:

• API Actions:l'API Actions è un'API REST dell'assistente 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 nella tua Azione aggiungendo un nuovo intent Class Canceled e inviando notifiche agli utenti per informarli dell'annullamento di un corso. Configurerai anche i seguenti tre componenti necessari per inviare notifiche:

• Account API Actions: invii notifiche all'utente inviando 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 all'ID utente necessario per inviargli notifiche push. In questo esempio, utilizzerai una funzione della libreria client per chiamare l'helper per le autorizzazioni e richiedere questo ID.

Termini chiave:

• Helper:un helper è un intent che, una volta soddisfatto, consente all'assistente di prendere temporaneamente il controllo della conversazione per richiedere informazioni specifiche all'utente. Se la richiesta è andata a buon fine, l'helper ti restituisce queste informazioni.

• Archiviazione: per inviare notifiche push a un utente al di fuori di una conversazione, devi archiviare gli ID utente in un luogo in cui possano essere recuperati a piacimento. In questo esempio, configurerai un database Firestore per archiviare le informazioni di ogni utente.

Dopo aver seguito queste istruzioni, aggiungerai la seguente finestra di dialogo alla conversazione dell'azione:

In che modo ciò coinvolgerà gli utenti?

Gli utenti di smartphone conoscono probabilmente le notifiche push, che forniscono informazioni e aggiornamenti specifici per le app. Le notifiche push sono un modo flessibile per raggiungere gli utenti sui dispositivi mobili al di fuori dell'assistente, a condizione che agli utenti venga fornito un buon motivo per attivarle. Con gli aggiornamenti giornalieri, gli utenti sanno già che riceveranno notifiche ogni giorno. Con le notifiche push, tuttavia, gli utenti non sanno se stanno attivando la ricezione di notifiche poco frequenti o se riceveranno più notifiche al giorno.

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

• Pianifica alcuni orari di esempio per le notifiche push. Se prevedi di inviare una sola notifica push al giorno, valuta la possibilità di utilizzare gli aggiornamenti giornalieri.
• Assicurati che le notifiche push forniscano informazioni utili ogni volta che vengono ricevute. Le notifiche possono anche essere collegate direttamente a uno degli intent dell'azione, quindi assicurati che l'intent sia utile e pertinente.
• Sii esplicito quando chiedi a un utente di iscriversi alle notifiche push. Devono capire cosa aspettarsi da ogni notifica push e avere un'idea della frequenza con cui vengono inviate.

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

Abilita l'API Actions

1. Apri la console Google Cloud e seleziona il nome del progetto Azioni nel menu a discesa.

2. Nel menu di navigazione (☰), vai ad API e servizi > 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 service account per inviare richieste. Segui questi passaggi per creare e installare una chiave dell'account di servizio per l'API Actions:

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

• Nome dell'account di servizio: service-account
• Ruolo: Progetto > Proprietario
• ID service account: 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.

Attiva Firestore

Per inviare notifiche al di fuori della conversazione, devi disporre di un modo per archiviare gli ID utente a cui fare riferimento dal codice di notifica. Per questo esempio, utilizziamo un database Firestore per archiviare gli ID utente degli utenti abbonati.

Per creare un database Firestore per l'azione:

1. Nella console Firebase, seleziona il nome del progetto Azioni.
2. Nel riquadro di navigazione a sinistra, vai a Sviluppa > Database e fai clic su Crea database.
3. Seleziona Avvia in modalità di test.
4. Fai clic su Abilita.

Suggerimento:utilizziamo le regole di sicurezza in modalità di test solo a scopo di test. Prima che l'azione venga pubblicata in produzione, devi implementare regole di sicurezza dei dati più solide. 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 Dialogflow:

Chiedere all'utente di iscriversi

1. Configura un nuovo intent per gestire la richiesta dell'utente di iscriversi alle notifiche push per le lezioni annullate. Nella console Dialogflow, fai clic sul pulsante + accanto a Intent nel menu di navigazione a sinistra per creare un nuovo intent.
2. Assegna a questo nuovo intent il nome 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 al prompt 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 a questo nuovo intent il nome Confirm Push Notifications.
3. Nella sezione Eventi, aggiungi actions_intent_PERMISSION. Questo evento Dialogflow verrà attivato al termine del flusso di iscrizione alle notifiche push da parte dell'utente, indipendentemente dal fatto che l'iscrizione sia stata completata o meno.
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 vengano indirizzati direttamente a quell'intent nella tua Azione. In questo esempio, aggiungi un nuovo intent per le notifiche push che forniscono dettagli sulle lezioni annullate.

Per aggiungere un intent da attivare quando l'utente tocca una notifica push:

1. Nella console Dialogflow, fai clic sul pulsante + accanto a Intent nel menu di navigazione a sinistra per creare un nuovo intent.
2. Assegna a questo nuovo intent il nome 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 a metà conversazione

In produzione, devi avere uno script separato dal codice di completamento dell'azione che invia notifiche push. Per questo esempio, crea un intent che puoi richiamare per inviare una notifica push mentre parli con la tua Azione. Questo intent è solo a scopo di debug; in pratica, le notifiche push non devono essere gestite dal tuo fulfillment o attivate in altro modo nell'ambito della conversazione dell'azione.

Per creare un intent per testare le notifiche push:

1. A scopo di test e debug, configura un nuovo intent che ti consenta di inviare notifiche push agli utenti iscritti. Nella console Dialogflow, fai clic sul pulsante + accanto a Intent nel menu di navigazione a sinistra per creare un nuovo intent.
2. Assegna a questo nuovo intent il nome 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

Per attivare le notifiche push per l'intent Lezione annullata:

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

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

Implementare l'evasione

Per implementare l'evasione nel webhook, completa i seguenti passaggi:

Carica dipendenze

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

index.js

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

Aggiornare i chip di suggerimento

Nel file index.js, aggiungi una voce NOTIFICATIONS all'elenco dei titoli dei chip di suggerimento, in modo che la definizione di Suggestion sia simile alla seguente:

index.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 tuo database Firestore, aggiungi il pacchetto firebase-admin e le costanti per i campi archiviati nel database. Inoltre, importa i pacchetti google-auth-library e request per gestire l'autenticazione e le richieste all'API Actions.

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

index.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 configurazione delle notifiche di annullamento delle lezioni

Nel file index.js, sostituisci il seguente codice:

index.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:

index.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 l'evasione per nuovi intent

Quando l'utente dice di voler iscriversi alle notifiche push, chiama l'helper UpdatePermission per richiedere l'autorizzazione all'utente. Se l'operazione va a buon fine, l'argomento PERMISSION verrà aggiunto agli argomenti dell'oggetto conv, che puoi controllare per cambiare argomento della conversazione.

Una volta ottenuta l'autorizzazione dell'utente, prendi l'ID utente dagli argomenti dell'oggetto conv e salvalo nel tuo database. In seguito invierai questo ID utente all'API Actions, che è il modo in cui l'assistente determina chi riceve la notifica.

Infine, aggiungi l'evasione per l'intent Class Canceled attivato toccando la notifica push. In questo esempio, la risposta è una stringa segnaposto, anche se in una versione di questa azione pronta per la produzione lo script di notifica fornirebbe informazioni più dinamiche sulla lezione che è stata annullata.

Nel file index.js, aggiungi il seguente codice:

index.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 test

Per inviare una notifica push a un utente, invia una richiesta POST all'API Actions con l'ID utente, il titolo della notifica e l'intent di destinazione. In questo esempio, l'attivazione dell'intent Notifica di test scorrerà il database Firestore e invierà notifiche push a ogni utente che ha eseguito l'iscrizione alle notifiche.

Ricorda che, in questo esempio, stai includendo il codice che invia la notifica push nel webhook e attivando questo codice richiamando un intent di test nella conversazione. In Azioni che intendi pubblicare, il codice di notifica push deve esistere in uno script separato dall'evasione.

Nel file index.js, aggiungi il seguente codice:

index.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 questo comando per eseguire il deployment del codice webhook aggiornato su Firebase:

firebase deploy

Suggerimento:puoi trovare le informazioni più recenti sull'utilizzo del Simulatore delle azioni nella guida al Simulatore delle azioni. Consulta questa pagina se riscontri problemi durante l'esecuzione dei passaggi elencati di seguito.

Per provare le notifiche nel simulatore di azioni, segui questi passaggi:

1. Nella console Azioni, 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 ancora concesso all'azione l'autorizzazione a inviarti notifiche push, digita yes e premi Invio.
6. Digita yes e premi Invio. Ora il tuo Account Google dovrebbe essere iscritto alle notifiche push per questa azione.

Se ricevi un 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 Salva, riattiva le notifiche push, fai di nuovo clic su Salva e 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 push dell'assistente "Notifica di test da Action Gym" sul tuo dispositivo mobile. Se tocchi questa notifica, verrà visualizzato il link diretto all'intent Corso annullato della tua azione.

Se hai difficoltà a visualizzare la notifica, prova a seguire le istruzioni di test sul tuo smartphone. Apri l'assistente sullo smartphone e di' "talk to my test app", poi segui le istruzioni di test riportate sopra a partire dal passaggio 3.

5. Creare un link dell'assistente

Finora abbiamo parlato delle funzionalità di coinvolgimento che puoi implementare per fare in modo che gli utenti tornino a utilizzare la tua Azione, ma queste si basano sul fatto che gli utenti scoprano e utilizzino la tua Azione.

Puoi creare un link dell'assistente che indirizzi gli utenti sui dispositivi mobili direttamente alla tua Azione sull'assistente. Poiché un link dell'assistente è un collegamento ipertestuale standard, puoi aggiungerlo a un sito web o a qualsiasi materiale di web marketing, come un blog o un post sui social media.

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

In che modo ciò coinvolgerà gli utenti?

Attirare gli utenti verso la tua azione per la prima volta può essere difficile, soprattutto quando devono invocarla esplicitamente sull'assistente. Un link dell'assistente riduce questo attrito fornendo agli utenti un link diretto alla tua azione. Quando un utente segue il link dell'assistente su un dispositivo compatibile con l'assistente, viene indirizzato direttamente alla tua Azione. Quando un utente apre il tuo link su un dispositivo non mobile o su qualsiasi altro dispositivo che non supporta l'assistente, verrà comunque indirizzato alla tua scheda della directory delle Azioni (se è stata pubblicata), in modo che il link possa comunque promuovere la tua azione presso questi utenti.

I link dell'assistente possono essere uno strumento di coinvolgimento utile, quindi ti consigliamo di crearne uno se prevedi di pubblicizzare la tua Azione tramite il tuo sito web o i social media. Tieni presente 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 di bozza, il link funzionerà solo sui tuoi dispositivi. Tutti gli altri utenti verranno indirizzati a una pagina di errore 404 nella directory Azioni.
• Puoi consentire agli utenti di testare un link dell'assistente prima della pubblicazione rilasciando l'azione in un ambiente alpha o beta. Tieni presente che solo gli utenti che partecipano alla tua versione alpha o beta potranno testare il collegamento dell'assistente.
• Assicurati che l'intent di destinazione del link dell'assistente faccia una buona prima impressione sui nuovi utenti. L'intent di benvenuto è la destinazione predefinita per un link dell'assistente perché dovrebbe già fare un buon lavoro di presentazione dell'azione

Suggerimento:in questo esempio creerai solo un semplice link dell'assistente che indirizza gli utenti all'intent di benvenuto, ma puoi fare molto di più per personalizzare un link dell'assistente. Puoi aggiungere parametri URL al link che indirizzano gli utenti a intent specifici e includere anche parametri di intent per personalizzare la risposta che gli utenti ricevono quando seguono il link. Sebbene non trattiamo queste opzioni avanzate in questo codelab, puoi scoprire di più 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 Sviluppa e scegli Azioni nella barra di navigazione a sinistra.
2. Fai clic su actions.intent.MAIN nell'elenco Azioni.
3. Nella sezione Link, attiva l'opzione Vuoi attivare un URL per questa azione?.
4. Imposta un titolo del link descrittivo che descriva l'azione. Crea un titolo semplice composto da un verbo e un sostantivo che descriva cosa può fare l'utente con la tua azione. Per questo esempio, imposta il Titolo del link su learn about Action Gym.
5. Copia lo snippet HTML in fondo a questa pagina e salvalo per dopo.
6. Fai clic su Salva nella parte superiore della pagina.

Esegui il deployment di un sito web di test

Per testare il link dell'assistente, puoi utilizzare gli strumenti Firebase per implementare 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 link dell'assistente.

Vai alla directory /user-engagement-codelab-nodejs/start/public/ del tuo adempimento 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 l'aspetto dello snippet riportato di seguito:

index.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>

Testare il link dell'assistente

Nel terminale, esegui questo comando per eseguire il deployment del sito web di test su Firebase:

firebase deploy

Al termine dell'esecuzione del comando di deployment, annota l'URL di hosting nell'output.

Visita questo URL nel browser web del tuo dispositivo mobile e dovresti visualizzare il link dell'assistente sul tuo sito web di test. Se fai clic su questo link sul tuo dispositivo mobile, dovresti visualizzare l'intent di benvenuto dell'azione nell'assistente.

Puoi anche provare ad andare all'URL di hosting su un browser desktop, che dovrebbe indirizzarti a una pagina 404 nella directory dell'assistente, poiché l'azione non è pubblicata.

6. Passaggi successivi

Complimenti!

Ora hai imparato l'importanza del coinvolgimento degli utenti durante lo sviluppo di un'azione, quali funzionalità di coinvolgimento degli utenti sono disponibili sulla piattaforma e come aggiungere ciascuna funzionalità a un'azione.

Risorse didattiche aggiuntive

Esplora queste risorse per scoprire di più sul coinvolgimento degli utenti per la tua Azione:

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

Seguici su Twitter @ActionsOnGoogle per rimanere aggiornato sui nostri ultimi annunci e twitta con l'hashtag #AoGDevs per condividere ciò che hai creato.

Sondaggio di opinione

Prima di andare, compila questo modulo per farci sapere cosa pensi del nostro lavoro.