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

1. Panoramica

Avviso: le azioni conversazionali verranno ritirate il 13 giugno 2023. Per ulteriori informazioni, vedi Ritiro delle azioni conversazionali.

Actions on Google è una piattaforma per sviluppatori che consente di creare software per estendere la funzionalità dell'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 nelle conversazioni per svolgere attività, come fare la spesa o prenotare una corsa. Per un elenco completo delle operazioni possibili, consulta la directory Actions. 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 codelab avanzato, destinato ai lettori che hanno già una certa esperienza nella creazione di azioni per l'Assistente Google. Se non hai alcuna esperienza di sviluppo con Actions on Google, ti consigliamo vivamente di acquisire familiarità 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 le funzionalità dell'Azione e 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 facilitare questa operazione, puoi implementare nell'azione diverse funzionalità che forniscono agli utenti percorsi di ritorno alla conversazione.

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

Cosa creerai

Migliorerai una funzionalità già creata abilitandola a:

• Invia agli utenti un aggiornamento giornaliero che possono toccare per interagire con l'azione
• Invia agli utenti notifiche push che rimandano all'azione
• Crea un link che indirizzi gli utenti all'azione da un browser web mobile

Cosa imparerai a fare

• 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 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 IDE/editor di testo a 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 (devi aver eseguito l'accesso all'assistente con lo stesso Account Google che utilizzerai per creare questo progetto).

Ti consigliamo vivamente di acquisire familiarità con JavaScript (ES6) anche se non è obbligatoria, per comprendere il codice 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 ritornano all'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 vedere in un secondo momento e modi per tornare all'azione quando è più probabile che li recuperino.

Comprendi l'esempio

L'esempio di questo codelab è un'azione semplice per una palestra immaginaria chiamata "Action Gym". L'azione fornisce informazioni sulla palestra, incluso un elenco di corsi che si alternano ogni giorno. Un'azione informativa come questa è una buona candidata per tutte le funzionalità di coinvolgimento degli utenti, poiché l'elenco a rotazione delle classi fornisce ogni giorno informazioni utili diverse.

Il seguente diagramma mostra il flusso conversazionale di esempio di Action Gym:

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

Scarica i tuoi file di base

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

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

Configura progetto e agente

Per configurare il progetto Actions e l'agente Dialogflow, completa i seguenti passaggi:

1. Apri la console di Actions.
2. Fai clic su Nuovo progetto.
3. Digita un nome del 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 azione per espandere le opzioni e seleziona Aggiungi azioni.
7. Fai clic su Aggiungi la tua prima azione.
8. Nella finestra di dialogo Crea azione, seleziona Intent personalizzato,quindi fai clic su Crea per avviare la console di 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 menu 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 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 questi comandi:

firebase use <PROJECT_ID>

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

npm install

firebase deploy

Se viene visualizzato il messaggio di errore "Si è verificato un errore imprevisto dall'interfaccia a riga di comando", prova a eseguire di nuovo il comando firebase deploy.

Dopo alcuni minuti, dovresti vedere il messaggio "Deployment completato", che indica che hai eseguito correttamente il deployment del webhook in Firebase.

Recupera l'URL di deployment

Devi fornire a Dialogflow l'URL della funzione Cloud Functions. 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 Sviluppo > Funzioni nella barra di navigazione a sinistra. Se ti viene chiesto di selezionare "Scegli le impostazioni di condivisione dei dati", puoi ignorare questa opzione facendo clic su In seguito.
4. Nella scheda Dashboard, dovresti vedere la voce "fulfillment" con un URL in Attivatore. Salva questo URL; dovrai copiarlo in Dialogflow nella sezione successiva.

Impostare 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 di Dialogflow (se vuoi, puoi chiudere la console Firebase).
2. Fai clic su Fulfillment nel riquadro di navigazione a sinistra.
3. Attiva Webhook.
4. Incolla l'URL copiato dalla dashboard di Firebase, se non viene già visualizzato.
5. Fai clic su Salva.

Verifica che il progetto sia configurato correttamente

Gli utenti devono essere in grado di richiamare l'azione per avere informazioni su Action Gym, ad esempio un messaggio di risposta hardcoded con l'orario di apertura e un messaggio di risposta che elenca la programmazione del corso per ogni giorno della settimana.

Suggerimento: puoi trovare le informazioni più recenti sull'utilizzo del simulatore di Actions nella guida del simulatore di Actions. In caso di problemi con i passaggi indicati di seguito, fai riferimento a questa pagina.

Per testare l'Azione nel simulatore di Actions:

1. Nel riquadro di navigazione a sinistra della console di Dialogflow, fai clic su Integrazioni > Assistente Google.
2. Assicurati che l'opzione Anteprima automatica delle modifiche sia attivata 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 di benvenuto in Action Gym. Prova a seguire le istruzioni per continuare la conversazione e assicurati che il completamento abbia una risposta per ogni input.

Se non vedi queste risposte, è probabile che si sia verificato un problema con la configurazione di Firebase. In questo caso, prova a ripetere i passaggi nella sezione Esegui il deployment del fulfillment.

3. Aggiungere iscrizioni ad aggiornamenti giornalieri

Un modo comune per coinvolgere gli utenti consiste nell'offrire loro informazioni nel momento più utile. A questo scopo, gli utenti hanno la possibilità di abbonarsi ad aggiornamenti giornalieri per un intent, inviando loro una notifica dell'assistente che rimanda direttamente al completamento di quell'intento.

In questo passaggio imparerai a conoscere le iscrizioni ad aggiornamenti giornalieri e le aggiungerai all'intent Elenco corsi dell'Azione. Dopo aver seguito queste istruzioni, la conversazione dell'Azione apparirà come il seguente diagramma:

In che modo questo coinvolgerà gli utenti?

Gli utenti di smartphone hanno probabilmente familiarità con le notifiche push, che forniscono informazioni e aggiornamenti specifici dell'app. Le iscrizioni agli aggiornamenti giornalieri sono un modo semplice per accedere agli utenti sui dispositivi mobili al di fuori dell'assistente, a condizione che l'intento per cui invii gli aggiornamenti continui a fornire valore all'utente su base giornaliera.

Gli aggiornamenti giornalieri possono essere un utile strumento di coinvolgimento, ma non devono necessariamente essere incorporati in ogni Azione. Per decidere se aggiungere o meno iscrizioni ad aggiornamenti giornalieri a un'azione, considera questi suggerimenti:

• Assicurati che gli aggiornamenti giornalieri facciano sì che l'utente visualizzi ogni giorno informazioni diverse e utili. Se tocchi un aggiornamento giornaliero genera sempre la stessa richiesta, è probabile che l'utente annulli l'iscrizione dopo un paio di giorni.
• Assicurati che la finestra di dialogo sia sensata per l'utente se passa direttamente all'intenzione dell'aggiornamento giornaliero. L'utente non partirà necessariamente dall'inizio della conversazione, quindi non è detto che abbia molto contesto.
• Mostra all'utente il vantaggio dell'azione prima di invitarlo ad abbonarsi agli aggiornamenti giornalieri. L'utente dovrebbe pensare: "Voglio questi contenuti ogni giorno" quando viene offerta la possibilità di abbonarsi.
• Non sopraffare l'utente con ripetuti suggerimenti di abbonamento. Offri un abbonamento con aggiornamento giornaliero subito dopo aver mostrato all'utente i prodotti dell'abbonamento ed evita di infastidirlo altrove.
• Mantieni la conversazione breve dopo l'attivazione dell'intento di aggiornamento. La maggior parte degli aggiornamenti giornalieri dovrebbe consistere in una sola risposta e poi chiudersi senza richiedere l'input dell'utente.

Suggerimento: poiché gli aggiornamenti giornalieri vengono visualizzati come notifiche sul dispositivo dell'utente, ti consigliamo di consultare le nostre best practice per creare notifiche utili. La maggior parte dei contenuti della notifica di aggiornamento giornaliera è preconfigurata per l'assistente, ma questi stessi principi si applicano per stabilire se gli aggiornamenti giornalieri sono adatti al tuo obiettivo o all'azione.

Attiva gli aggiornamenti giornalieri

Le iscrizioni di aggiornamento giornaliere possono essere aggiunte all'intento di benvenuto, che colloca l'utente all'inizio della conversazione o a un intento più specifico per creare un link diretto a un punto all'interno della conversazione. Per questo codelab, l'intent Elenco corsi è più logico perché la finestra di dialogo cambia ogni giorno e agli utenti potrebbe essere utile ricevere un promemoria sui corsi disponibili.

Segui questi passaggi 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 corsi nell'elenco Azioni.
3. Nella sezione Coinvolgimento degli utenti, attiva l'opzione Vuoi offrire aggiornamenti giornalieri agli utenti.
4. Imposta un Titolo dei contenuti descrittivo che descriva l'aggiornamento giornaliero. Il contesto sarà "A che ora vuoi che ti invii il tuo quotidiano <titolo dei contenuti>", quindi assicurati che il titolo sia descrittivo e abbia un suono corretto quando viene pronunciato ad alta voce. 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 Dialogflow per creare intent per il flusso di aggiornamento giornaliero dell'abbonamento:

Chiedere 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 ad Intent nel riquadro 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/disattiva l'opzione Abilita la 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 ad 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 dall'utente che termina il flusso di aggiornamento giornaliero dell'abbonamento, indipendentemente dal fatto che abbia terminato o meno un abbonamento.
4. Nella sezione Fulfillment, attiva/disattiva l'opzione Abilita la chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Implementa il fulfillment

Per implementare il fulfillment nel tuo 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 abbiano il seguente aspetto:

index.js

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

Aggiornare i chip di suggerimenti

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

index.js

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

Aggiungere il completamento per i nuovi intent

Quando l'utente dice di voler abbonarsi, avvia il flusso di iscrizione agli aggiornamenti giornalieri chiamando l'assistente RegisterUpdate con l'intent target dell'aggiornamento (Elenco corsi) 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 è riuscito o meno. Offri all'utente richieste di follow-up che variano in base allo 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 richieste alternative

Al termine, la risposta dell'Elenco corsi offrirà l'iscrizione all'aggiornamento giornaliero, ma presenta un problema. Poiché la stessa risposta viene attivata quando l'utente tocca la notifica relativa all'aggiornamento giornaliero, gli verrà chiesto di abbonarsi agli aggiornamenti giornalieri anche se provengono soltanto da uno di questi aggiornamenti. Come puoi evitare che l'utente pensi di dover iscriversi nuovamente?

Per fortuna, gli argomenti dell'oggetto conv includono informazioni su dove l'utente ha iniziato la conversazione. Puoi controllare gli argomenti conv per verificare se contengono una sezione UPDATES, che indica che l'utente ha avviato la conversazione da una notifica di aggiornamento giornaliero, e modificare la risposta di conseguenza. Puoi anche utilizzare questo ramo di conversazione per chiudere la finestra di dialogo subito dopo aver fornito l'elenco dei corsi, che segue la nostra best practice di non interrompere 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]));
    };
  };
});

Verifica gli aggiornamenti giornalieri

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 di Actions nella guida del simulatore di Actions. In caso di problemi con i passaggi indicati di seguito, fai riferimento a questa pagina.

Per testare il prompt personalizzato nel simulatore di azioni:

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

Se ricevi un messaggio di errore quando provi a iscriverti agli aggiornamenti giornalieri al passaggio 4, torna a Crea > Azioni > Elenco dei corsi e disattiva gli aggiornamenti giornalieri. Fai clic su Salva, riattiva gli aggiornamenti giornalieri, fai nuovamente clic su Salva e prova di nuovo a eseguire il test nel simulatore.

Sul tuo dispositivo mobile, dovresti ricevere una notifica dall'assistente all'orario specificato per gli aggiornamenti. Tieni presente che la visualizzazione di questa notifica potrebbe richiedere un paio di minuti. Toccando la notifica, questa dovrebbe rimandare direttamente all'intent Elenco dei corsi nell'assistente e visualizzare un elenco dei corsi in programma:

4. Aggiungi notifiche push

Come ulteriore opzione 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, quindi puoi inviarle quando vuoi.

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 API Actions per inviare una notifica push utilizzando i contenuti della richiesta.

In questo passaggio, imparerai a implementare le notifiche push nell'azione aggiungendo un nuovo intent Corso annullato e inviando notifiche agli utenti che li informano dell'annullamento di un corso. Puoi anche configurare i tre componenti seguenti, necessari per inviare notifiche:

• Account API Actions: per inviare notifiche all'utente, invii una richiesta POST a un'API. Quindi, dovrai configurare un account di servizio e le credenziali per interfacciarti con questa API.
• Assistente 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 delle autorizzazioni e richiedere questo ID.

Termini chiave:

• Assistente:un assistente è un intent che, una volta completato, consente all'assistente di assumere temporaneamente il controllo della conversazione per richiedere informazioni specifiche all'utente. Se la richiesta ha esito positivo, l'assistente ti restituisce queste informazioni.

• Spazio di archiviazione - Per inviare notifiche push a un utente al di fuori di una conversazione, devi archiviare gli ID utente in una posizione che possa essere richiamata a piacimento. In questo esempio, configurerai un database Firestore per archiviare le informazioni per ciascun utente.

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

In che modo questo coinvolgerà gli utenti?

Gli utenti di smartphone hanno probabilmente familiarità con le notifiche push, che forniscono informazioni e aggiornamenti specifici dell'app. Le notifiche push sono un modo flessibile per accedere agli utenti che utilizzano dispositivi mobili al di fuori dell'assistente, a condizione che gli utenti abbiano un valido motivo per attivarle. Grazie agli aggiornamenti giornalieri, gli utenti sono già consapevoli che riceveranno una notifica ogni giorno. Con le notifiche push, tuttavia, gli utenti non possono sapere se stanno attivando la ricezione di notifiche non frequenti o se saranno preoccupati dall'invio di più notifiche al giorno.

Le notifiche push possono essere un utile strumento di coinvolgimento, ma non devono necessariamente essere incorporate in ogni azione. Per decidere se aggiungere notifiche push a un'azione, considera questi suggerimenti:

• Pianifica alcuni esempi di pianificazioni per le notifiche push. Se prevedi di inviare una sola notifica push al giorno, puoi prendere in considerazione l'utilizzo di aggiornamenti giornalieri.
• Assicurati che le notifiche push forniscano informazioni utili ogni volta che le ricevi. Le notifiche possono anche rimandare direttamente a uno degli intenti dell'Azione, quindi assicurati che l'intento sia utile e pertinente.
• Chiedi esplicitamente a un utente di iscriversi alle notifiche push. Dovrebbero capire cosa aspettarsi da ogni notifica push e avere un'idea della frequenza di invio.

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

Abilita l'API Actions

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

2. Nel menu di navigazione (☰), vai ad API e Servizi > Raccolta.
3. Cerca l'API Actions e fai clic su Abilita.

Crea un account di servizio

L'API Actions richiede l'autenticazione, quindi 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 della console Google Cloud (☰), vai ad 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 trovare un modo per archiviare gli ID utente a cui si può fare riferimento nel codice di notifica. Per questo esempio, utilizziamo un database Firestore per archiviare gli ID utente degli utenti iscritti.

Segui questi passaggi per creare un database Firestore per l'azione:

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

Suggerimento:utilizziamo le regole di sicurezza della modalità di test solo a scopo di test. Devi aver applicato regole più solide per la sicurezza dei dati prima che l'azione venga pubblicata in produzione. Scopri di più sulle regole di sicurezza di Cloud Firestore nella documentazione di Firestore.

Configura Dialogflow

Segui questi passaggi nella console Dialogflow per creare il flusso di attivazione delle notifiche push:

Chiedere 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 ad Intent nel riquadro 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/disattiva l'opzione Abilita la 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 ad 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 dall'utente che completa il flusso di iscrizione alle notifiche push, indipendentemente dal fatto che abbia terminato o meno l'iscrizione.
4. Nella sezione Fulfillment, attiva/disattiva l'opzione Abilita la chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Gestire le notifiche push

Puoi collegare le notifiche push a un intento specifico, in modo che gli utenti che la toccano siano direttamente collegati a tale intenzione nell'Azione. In questo esempio, aggiungi un nuovo intent per le notifiche push che fornisca i dettagli sui corsi annullati.

Per aggiungere un intent che venga attivato quando l'utente tocca una notifica push, procedi nel seguente modo:

1. Nella console di Dialogflow, fai clic sul pulsante + accanto ad Intent nel riquadro 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/disattiva l'opzione Abilita la chiamata webhook per questo intent.
5. Fai clic su Salva nella parte superiore della pagina.

Invia notifiche di prova durante una 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 all'azione. Questo intent è solo a scopo di debug. in pratica, le notifiche push non devono essere gestite dal tuo evasione degli ordini o altrimenti attivate come parte della conversazione dell'Azione.

Per creare un intent per testare le notifiche push:

1. A scopo di test e debug, imposta un nuovo intent che ti consenta di inviare notifiche push agli utenti iscritti. Nella console di Dialogflow, fai clic sul pulsante + accanto ad Intent nel riquadro 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/disattiva l'opzione Abilita la 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 Corso annullato:

1. Nella console di Dialogflow, vai a Integrazioni nella barra di navigazione.
2. Nella scheda Assistente Google, fai clic su Impostazioni di integrazione.
3. Aggiungi Class Canceled (Corso annullato) come intent di chiamata 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 Sviluppo 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 l'opzione Vuoi inviare notifiche push?.
8. Imposta un Titolo dei contenuti descrittivo che descriva la notifica push. Il contesto sarà "Va bene se invio notifiche push per <titolo del contenuto>?", quindi assicurati che il titolo sia descrittivo e abbia l'audio 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.

Implementa il fulfillment

Per implementare il fulfillment nel tuo 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 abbiano il seguente aspetto:

index.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 di titoli dei chip di suggerimento, in modo che la definizione di Suggestion abbia il seguente aspetto:

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 aggiungi 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 configurare le notifiche di annullamento di un corso

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 il completamento per i nuovi intent

Quando l'utente dice di volersi abbonare alle notifiche push, chiama l'assistente UpdatePermission per richiedere l'autorizzazione all'utente. Se ha esito positivo, l'argomento PERMISSION verrà aggiunto agli argomenti dell'oggetto conv, che puoi verificare per eseguire un pivot della conversazione.

Una volta ottenuta l'autorizzazione dell'utente, recupera l'ID utente dagli argomenti dell'oggetto conv e salvalo nel database. Successivamente, dovrai inviare questo ID utente all'API Actions, che consente all'assistente di determinare chi deve ricevere la notifica.

Infine, aggiungi il completamento per l'intent Class Canceled che viene 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 fornirebbe informazioni più dinamiche sulla classe 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 prova

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 target. In questo esempio, l'attivazione dell'intent di notifica di prova eseguirà l'iterazione attraverso il tuo database Firestore e invierà notifiche push a ogni utente iscritto alle notifiche.

Ricorda che, in questo esempio, hai incluso il codice che invia la notifica push nel fulfillment webhook e l'attivazione di quel codice richiamando un intent di test nella tua conversazione. In Azioni che vuoi pubblicare, il codice delle notifiche push deve trovarsi in uno script separato dal tuo fulfillment.

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.');
});

Verificare 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 di Actions nella guida del simulatore di Actions. In caso di problemi con i passaggi indicati di seguito, fai riferimento a questa pagina.

Per testare le notifiche nel simulatore di Actions, procedi nel seguente modo:

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 all'azione per inviarti notifiche push, digita yes e premi Invio.
6. Digita yes e premi Invio. Il tuo Account Google dovrebbe ora essere iscritto alle notifiche push per questa azione.

Se ricevi un messaggio di errore quando provi a iscriverti alle notifiche push al passaggio 4, torna a Crea > Azioni > Corso annullato e disattiva le notifiche push. Fai clic su Salva, riattiva le notifiche push, fai nuovamente clic su Salva e prova di nuovo 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 di prova da Action Gym" Notifica push dell'assistente sul tuo dispositivo mobile. Se tocchi questa notifica, ti reindirizzeremo all'intent Corso annullato dell'Azione.

Se hai difficoltà a ricevere la notifica, prova a seguire le istruzioni per la verifica sullo smartphone. Apri l'assistente sullo smartphone e di' "talk to my test app", quindi segui le istruzioni per il test riportate sopra, dal passaggio 3 in poi.

5. Crea un link all'assistente

Finora abbiamo parlato delle funzionalità di coinvolgimento che puoi implementare per invogliare gli utenti a tornare sull'Azione, ma si basano sull'avere utenti che scoprono e utilizzano l'Azione.

Puoi creare un link all'assistente che colleghi gli utenti sui dispositivi mobili direttamente all'azione. Poiché un link all'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 scoprirai cos'è un link all'assistente, come crearne uno per l'intento di benvenuto dell'azione e come aggiungerlo a un semplice sito web per i test.

In che modo questo coinvolgerà gli utenti?

Attirare utenti verso l'azione per la prima volta può essere difficile, soprattutto quando devono richiamare esplicitamente l'azione sull'assistente. Un link all'assistente allevia questa difficoltà fornendo agli utenti un link diretto all'azione. Quando un utente segue il link all'assistente su un dispositivo con l'assistente integrato, viene indirizzato direttamente all'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 scheda della directory di Actions (se è stato pubblicato), in modo che il link possa comunque commercializzare l'azione a questi utenti.

I link all'assistente possono essere un utile strumento di coinvolgimento, quindi ti consigliamo di crearne uno se hai intenzione di pubblicizzare l'Azione sul tuo sito web o sui tuoi social media. Tieni presente i seguenti suggerimenti prima di creare e distribuire un link all'assistente:

• I link all'assistente funzionano solo dopo che l'azione è stata pubblicata. Mentre il progetto è in stato di bozza, il link funziona solo sui tuoi dispositivi. Tutte le altre persone verranno indirizzate a una pagina 404 nella directory Actions.
• Puoi consentire agli utenti di testare un link all'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 link all'assistente.
• Assicurati che l'intent di destinazione del link all'assistente faccia una buona prima impressione con i nuovi utenti. Il tuo intent di benvenuto è la destinazione predefinita di un link all'assistente perché dovrebbe già introdurre l'azione in modo adeguato

Suggerimento: in questo esempio creerai solo un semplice link all'assistente che indirizzi gli utenti all'intent di benvenuto, ma puoi fare molto di più per personalizzare un link all'assistente. Puoi aggiungere parametri URL al tuo link per indirizzare gli utenti a intent specifici e persino includere parametri di intent per personalizzare la risposta che gli utenti ricevono quando seguono il link. Anche se non tratteremo queste opzioni avanzate in questo codelab, puoi scoprire di più nella documentazione per gli sviluppatori.

Attiva i link dell'assistente

Per creare un link all'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 Azioni.
3. Nella sezione Link, attiva l'opzione Vuoi attivare un URL per questa azione?
4. Imposta un Titolo link descrittivo che descriva l'Azione. Usa il titolo con una semplice coppia verbo-nome che descriva cosa può fare l'utente con l'Azione. Per questo esempio, imposta Titolo link su learn about Action Gym.
5. Copia lo snippet HTML dalla parte inferiore di questa pagina e salvalo per un secondo momento.
6. Fai clic su Salva nella parte superiore della pagina.

Esegui il deployment di un sito web di test

Per testare il collegamento all'assistente, puoi utilizzare gli strumenti Firebase per eseguire il deployment di un sito web di test insieme al tuo fulfillment. Per questo esempio abbiamo già creato un semplice sito web di prova, che ti basta aggiungere il link all'assistente.

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

Nel file index.html, incolla lo snippet HTML del link all'assistente nell'elemento body. Il file dovrebbe essere simile al seguente:

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>

Prova il link all'assistente

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

firebase deploy

Al termine dell'esecuzione del comando di deployment, prendi nota dell'URL di Hosting nell'output.

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

Puoi anche provare ad andare all'URL di hosting su un browser desktop; dovresti visualizzare una pagina 404 nella directory dell'assistente perché l'azione non è pubblicata.

6. Passaggi successivi

Complimenti!

Hai appreso l'importanza del coinvolgimento degli utenti quando sviluppa 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 saperne di più sul coinvolgimento degli utenti per l'Azione:

• Coinvolgimento degli utenti e Documentazione sui link dell'assistente: la documentazione ufficiale di Actions on Google sulle funzionalità descritte in questo codelab e il coinvolgimento degli utenti in generale.
• Analisi sulla fidelizzazione 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 su come progettare funzionalità di coinvolgimento degli utenti.
• Repository GitHub di Actions on Google: codice e librerie di esempio.
• r/GoogleAssistantDev: la community ufficiale di Reddit per gli sviluppatori che lavorano con l'assistente.

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

Sondaggio di opinione

Prima di terminare, compila questo modulo per farci sapere la tua opinione.