Raccogliere ed elaborare informazioni degli utenti di Google Chat

Questa guida descrive in che modo le app Google Chat possono raccogliere ed elaborare informazioni dagli utenti creando input di moduli in interfacce basate su schede.

Una finestra di dialogo con una serie di widget diversi.
Figura 1: A esempio app di chat che apre una finestra di dialogo per raccogliere dati di contatto.

Le app di Chat richiedono informazioni agli utenti per eseguire azioni all'interno o all'esterno di Chat, ad esempio nei seguenti modi:

  • Configura le impostazioni. Ad esempio, per consentire agli utenti di personalizzare le impostazioni di notifica o configurare e aggiungere l'app Chat a una o più spazi di archiviazione.
  • Creare o aggiornare informazioni in altre applicazioni di Google Workspace. Per Ad esempio, puoi consentire agli utenti di creare un evento di Google Calendar.
  • Consenti agli utenti di accedere e aggiornare le risorse in altre app o servizi web. Per Ad esempio, un'app di Chat può aiutare gli utenti ad aggiornare di un ticket di assistenza direttamente da uno spazio di Chat.

Prerequisiti

Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un'app di Chat interattiva, completa una delle seguenti guide rapide in base all'architettura dell'app che vuoi utilizzare:

Crea moduli utilizzando le schede

Per raccogliere informazioni, le app di chat progettano i moduli e i relativi input, e trasformarli in schede. Per mostrare le schede agli utenti: Le app di chat possono utilizzare le seguenti interfacce di Chat:

  • Messaggi che contengono una o più schede.
  • Home page, ovvero una scheda visualizzata nella scheda Home nei messaggi diretti con l'app Chat.
  • Dialoghi, ovvero schede che si aprono in una nuova finestra da messaggi e home page.

Le app di chat possono creare le schede utilizzando i seguenti widget:

  • Widget di input dei moduli che richiedono informazioni agli utenti. Se vuoi, puoi aggiungere la convalida ai widget di immissione dei moduli per assicurarti che gli utenti inseriscano e formattino correttamente le informazioni. Le app di chat possono utilizzare i seguenti widget di inserimento moduli:

    • Input di testo (textInput) per testo libero o suggerito.
    • Gli input di selezione (selectionInput) sono elementi dell'interfaccia utente selezionabili come caselle di controllo, pulsanti di opzione e menu a discesa. I widget di input di selezione possono anche compilare gli elementi da origini dati statiche o dinamiche. Ad esempio, gli utenti possono selezionare uno spazio di Chat di cui fanno parte da un elenco.
    • Selettori data e ora (dateTimePicker) per le voci di data e ora.

  • Un widget con pulsanti in modo che gli utenti possano inviare i valori che hanno inserito nella scheda. Dopo che l'utente fa clic sul pulsante, l'app Chat può elaborare le informazioni che riceve.

Di seguito viene mostrata una scheda composta da tre diversi tipi di date e input di tempo:

Per altri esempi di widget interattivi che puoi utilizzare per raccogliere le informazioni, vedi Progetta una scheda o una finestra di dialogo interattiva.

Ricevere dati da widget interattivi

Ogni volta che gli utenti fanno clic su un pulsante, le app di chat ricevono un CARD_CLICKED evento di interazione che contiene informazioni sull'interazione. Il payload degli eventi di interazione CARD_CLICKED contiene un oggetto common.formInputs con tutti i valori inseriti dall'utente.

Puoi recuperare i valori dall'oggetto common.formInputs.WIDGET_NAME, dove WIDGET_NAME è il campo name specificato per il widget. I valori vengono restituiti come tipo di dati specifico per il widget (rappresentato come un oggetto Inputs). Nell'esempio seguente, una scheda raccoglie dati di contatto utilizzando un messaggio selettore di data, ora e widget di input per l'input:

{
  "textInput": {
    "name": "contactName",
    "label": "First and last name",
    "type": "SINGLE_LINE"
  }
}, {
  "dateTimePicker": {
    "name": "contactBirthdate",
    "label": "Birthdate",
    "type": "DATE_ONLY"
  }
}, {
  "selectionInput": {
    "name": "contactType",
    "label": "Contact type",
    "type": "RADIO_BUTTON",
    "items": [
      {
        "text": "Work",
        "value": "Work",
        "selected": false
      },
      {
        "text": "Personal",
        "value": "Personal",
        "selected": false
      }
    ]
  }
}

Gestire l'evento di interazione

Quando un utente inserisce dati in una scheda o una finestra di dialogo, L'app Chat riceve un'app Chat Evento di interazione CARD_CLICKED contenente i valori inseriti dall'utente.

Di seguito viene mostrata una parte di un evento di interazione CARD_CLICKED in cui un valore inserito dall'utente per ogni widget:

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps Script 

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

Per ricevere i dati, l'app di Chat gestisce l'evento di interazione per ottenere i valori inseriti dagli utenti nei widget. La tabella riportata di seguito mostra come ottenere il valore di un determinato widget di input del modulo. Per ogni widget, la tabella mostra il tipo di dati accettato dal widget, dove viene memorizzato il valore nell'evento di interazione e un valore di esempio.

Widget di input del modulo Tipo di dati di input Valore inserito dall'evento di interazione Valore di esempio
textInput stringInputs events.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Per ottenere il primo o l'unico valore, events.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker che accetta solo date. dateInput events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

Trasferire i dati su un'altra carta

Dopo che un utente ha inviato i dati di una carta, potresti dover restituire altre carte per eseguire una delle seguenti operazioni:

  • Aiuta gli utenti a compilare moduli più lunghi creando sezioni distinte.
  • Consenti agli utenti di visualizzare l'anteprima e confermare le informazioni della scheda iniziale, in modo che possano rivedere le risposte prima di inviarle.
  • Compila dinamicamente le parti rimanenti del modulo. Ad esempio, per chiedere agli utenti di creare un appuntamento, un'app di chat potrebbe mostrare una scheda iniziale che richiede il motivo dell'appuntamento, quindi compilare un'altra scheda che fornisce gli orari disponibili in base al tipo di appuntamento.

Per trasferire l'input dei dati dalla scheda iniziale, puoi creare il widget button con actionParameters che contengono il name del widget e il valore inserito dall'utente, come mostrato nell'esempio seguente:

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

Dove WIDGET_NAME è il name del widget e USER_INPUT_VALUE è ciò che l'utente inserisce. Ad esempio, per un input text che raccoglie il nome di una persona, il nome del widget è contactName e un valore di esempio è Kai O.

Quando un utente fa clic sul pulsante, l'app Chat riceve un CARD_CLICKED evento di interazione. Per recuperare i valori, puoi utilizzare il metodo event.common.parameters .

Di seguito è riportato un esempio di come trasmettere parametri contenenti il inserisci i dati a una funzione che apre la scheda successiva:

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Python

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

Apps Script 

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

Rispondere a un invio di modulo

Dopo aver ricevuto i dati da un messaggio o da una finestra di dialogo in una scheda, L'app Chat risponde confermando la ricezione o che restituisce un errore.

Nell'esempio seguente, un'app di Chat invia un messaggio per confermare che ha ricevuto correttamente un modulo inviato da un messaggio della scheda.

Apps Script 

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

Per elaborare e chiudere una finestra di dialogo, restituisci una ActionResponse che specifica se si desidera inviare un messaggio di conferma, aggiornare il messaggio o la scheda originale oppure chiudi semplicemente la finestra di dialogo. Per la procedura, consulta Chiudere una finestra di dialogo.

Risoluzione dei problemi

Quando un'app Google Chat o card restituisce un errore, L'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la richiesta". A volte, l'UI di Chat non mostra alcun messaggio di errore, ma l'app Chat o la scheda restituisce un risultato inaspettato; Ad esempio, il messaggio di una scheda potrebbe non vengono visualizzate.

Sebbene un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente di Chat, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando la registrazione degli errori per le app Chat è attivata. Per assistenza su come visualizzare, eseguire il debug e correggere gli errori, consulta la sezione Risolvere gli errori di Google Chat.