Raccogliere ed elaborare informazioni degli utenti di Google Chat

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

Figura 1: un'app di Chat di esempio che apre una finestra di dialogo per raccogliere i 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 di configurare e aggiungere l'app Chat a uno o più spazi.
• Creare o aggiornare informazioni in altre applicazioni di Google Workspace. Ad esempio, consenti agli utenti di creare un evento di Google Calendar.
• Consenti agli utenti di accedere e aggiornare le risorse in altre app o servizi web. Ad esempio, un'app di Chat può aiutare gli utenti ad aggiornare lo stato di un ticket di assistenza direttamente da uno spazio di Chat.

Prerequisiti

Node.js

Un'app Google Chat per cui sono abilitate le funzionalità interattive. Per creare un'app di Chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Python

Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un'app di Chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Java

Un'app Google Chat per cui sono abilitate le funzionalità interattive. Per creare un'app Chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Apps Script

Un'app Google Chat per cui sono abilitate le funzionalità interattive. Per creare un'app Chat interattiva in Apps Script, completa questa guida rapida.

Crea moduli utilizzando le schede

Per raccogliere informazioni, le app di chat progettano i moduli e i relativi input e li trasformano 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, una scheda che viene visualizzata nella scheda Home nei messaggi diretti con l'app Chat.
• Finestre di dialogo, 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. Facoltativamente, puoi aggiungere la convalida per formare widget di input, per garantire 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 in formato 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 da un elenco di spazi di Chat di cui sono membri.
  • Selettori data e ora (dateTimePicker) per le voci di data e ora.

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

Nell'esempio seguente, una scheda raccoglie i dati di contatto utilizzando un input di testo, un selettore di data e ora e un widget di input per la selezione:

Node.js

node/contact-form-app/index.js

Visualizza su GitHub

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py

Visualizza su GitHub

# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

Visualizza su GitHub

// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps Script

apps-script/contact-form-app/contactForm.gs

Visualizza su GitHub

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
];

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

Ricevere dati da widget interattivi

Per altri esempi, vedi Esempi di app Google Chat.

Ogni volta che gli utenti fanno clic su un pulsante, le app di chat ricevono un evento di interazione CARD_CLICKED 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 che hai specificato per il widget. I valori vengono restituiti come tipo di dati specifico per il widget (rappresentato come oggetto Inputs).

Di seguito è riportata una parte di un evento di interazione CARD_CLICKED in cui un utente ha inserito valori 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 seguente mostra come ottenere il valore per 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.

Importante: se l'app Chat è creata con Apps Script, devi aggiungere [""] dopo il nome del widget, ad esempio formInputs.contactName[""].stringInputs.value[0].

Widget di immissione modulo	Tipo di dati di input	Valore inserito dall'evento di interazione	Valore di esempio
textInput	stringInputs	event.common.formInputs.contactName.stringInputs.value[0]	Kai O
selectionInput	stringInputs	Per ottenere il primo o l'unico valore, event.common.formInputs.contactType.stringInputs.value[0]	Personal
dateTimePicker che accetta solo date.	dateInput	event.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 completare moduli più lunghi creando sezioni distinte.
• Consenti agli utenti di visualizzare in anteprima e confermare le informazioni dalla 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 di dati dalla scheda iniziale, puoi creare il widget button con actionParameters che contiene il valore name del widget e il valore inserito dall'utente, come mostrato nell'esempio seguente:

Node.js

node/contact-form-app/index.js

Visualizza su GitHub

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py

Visualizza su GitHub

'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

Visualizza su GitHub

new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps Script

apps-script/contact-form-app/main.gs

Visualizza su GitHub

buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Quando un utente fa clic sul pulsante, l'app Chat riceve un evento di interazione CARD_CLICKED dal quale puoi ricevere dati.

Rispondere a un invio di modulo

Dopo aver ricevuto i dati da un messaggio o una finestra di dialogo della scheda, l'app Chat risponde confermando la ricezione o generando un errore.

Nell'esempio seguente, un'app di chat invia un messaggio di testo per confermare di aver ricevuto correttamente un modulo inviato da un dialogo o da un messaggio della scheda.

Node.js

node/contact-form-app/index.js

Visualizza su GitHub

const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

Python

python/contact-form-app/main.py

Visualizza su GitHub

contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
if contact_name == "":
  error_message = "Don't forget to name your new contact!"
  if "SUBMIT_DIALOG" == event.get('dialogEventType'):
    return { 'actionResponse': {
      'type': "DIALOG",
      'dialogAction': { 'actionStatus': {
        'statusCode': "INVALID_ARGUMENT",
        'userFacingMessage': error_message
      }}
    }}
  else:
    return {
      'privateMessageViewer': event.get('user'),
      'text': error_message
    }

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java

Visualizza su GitHub

String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (contactName.isEmpty()) {
  String errorMessage = "Don't forget to name your new contact!";
  if (event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
    return new Message().setActionResponse(new ActionResponse()
      .setType("DIALOG")
      .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
        .setStatusCode("INVALID_ARGUMENT")
        .setUserFacingMessage(errorMessage))));
  } else {
    return new Message()
      .setPrivateMessageViewer(new User().setName(event.at("/user/name").asText()))
      .setText(errorMessage);
  }
}

Apps Script

apps-script/contact-form-app/main.gs

Visualizza su GitHub

const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

Per elaborare e chiudere una finestra di dialogo, restituisci un oggetto ActionResponse che specifica se vuoi inviare un messaggio di conferma, aggiornare la scheda o il messaggio originale o semplicemente chiudere la finestra di dialogo. Per i passaggi da seguire, vedi Chiudere una finestra di dialogo.

Risoluzione dei problemi

Quando un'app o una scheda di Google Chat restituisce un errore, l'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la richiesta". A volte nella UI di Chat non viene visualizzato alcun messaggio di errore, ma l'app o la scheda Chat produce un risultato imprevisto. Ad esempio, il messaggio di una scheda potrebbe non essere visualizzato.

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 informazioni su visualizzazione, debug e correzione degli errori, vedi Risolvere i problemi e correggere gli errori di Google Chat.

Argomenti correlati

• Visualizza l'esempio di Gestore contatti, che è un'app di Chat che chiede agli utenti di compilare un modulo di contatto da messaggi e finestre di dialogo della scheda.
• Aprire finestre di dialogo interattive